Kinetic UI mod with Function > Report Job Quantity

Problem

A high-volume manufacturer wanted to reduce the number of clicks required by users to report quantity on a job in Kinetic MES.

The request was to add controls to the MES Production screen that allow users to input a quantity and report that quantity to the job without having to pop up another screen.

Solution

1. Trace the out of box method of reporting quantity in MES

2. Create an Epicor Function that replicates Report Quantity

3. Modify the Kinetic MES Production screen by creating a new layer in Application Studio

1. Create a layer

2. Add panel, numeric input, button, and label controls

3. Create a row rule to enable/disable our new controls

4. Create an event that allows the button to call the new Report Quantity Function

Details

Following are details of how we accomplished step 3, Modify the Kinetic MES Production screen. If you'd like details for steps 1 and 2 please let us know.

Create layer

• From MES

  • Launch Application Studio

  • Click "New Layer"

  • Give the layer a name and description

  • Click "Save Layer"

Add panel, numeric input, button, and label controls

• We added a panel card with an id of pcReportQty and Title of "Repot Job Quantity".

• Next we added three labels. Labels do not have id's. They do have Label Text. We set those to "Selected Job:", "selected job number", and "Qty:".The "selected job number" label was databound to LaborDtl.JobNum. When an Employee is logged in and has one or more jobs in there queue, those jobs appear in the queue grid (see the Screenshot 3). The selected job in the queue replaces "selected job number" in our Label Text.

• A numeric box was added with an id of numQtyToReport and Labeled "Enter Qty to Report". This control was databound to CallContextBpmData.QtyToReport. Note that QtyToReport is an "on the fly" data column. We could have chosen one the various Numberxx columns (e.g. Number01), but we felt this made our intent clear.

• Finally a button was added with an id of btnCustomReportQty and Label Text of "Save". The button was also databound to CallContextBpmData.QtyToReport. This binding gives us the ability to control the state of the button, we'll explain how in a bit.

In the screenshots below inside the red box, you can see where we added the requested controls.

Screenshot 1 - Application Studio. Our numeric input is selected - you can see its properties on the right side of the screen.

Screenshot 2

Create row rule to enable/disable our new controls

Although the client didn't request it, we need to make sure the custom report quantity functionality respects basic Epicor rules.

For instance, we need an Employee to be logged in and actively working on one or more job/operations, and we need a specific job/operation selected. There are some other checks involved, such as certain Employee permissions, licensing, and other restrictions.

Notice that in the first screenshot above, both the standard "Report Quantity" button (in the Apps panel) and our custom number box and button are inactive.

In the second screenshot, with an Employee logged in and all the requirements satisfied, those controls are active. You can see that the "selected job number" numeric box now displays the job number of the selected row in the Queue grid.

How did we get our custom controls to behave as we wanted?

The answer is Data Rules. (I know some of you agree, data does rule - but that's a little different).

From Epicor "Data rules highlight key fields, disable selected fields, hide pages, and activate other actions that help you to control how your company uses an application."

You can build User Defined Rules in application studio. Once you understand them, they are pretty straightforward. But, how to capture all the rules of the road for MES Report Quantity?

It turns out that is easy too. Epicor exposes their System Rules. In our case, we were interested in one named MESControl.ReportQty. This rule controls the style of the MESControl.ReportQty field.

All we had to do is copy it and rename the copy - almost.

We changed the Action Data View from MESControl to CallContextBpmData and the Action's Field to QtyToReport. Remember that bogus "on the fly" field we bound our numeric box and button to? Once we got this rule working, it mimics the Report Quantity rule, enabling and disabling our custom controls as desired.

There were a few gotcha's though.

Two row rules reference a Field name $rowCount, comparing them to zero.

This is a screenshot of the stock MESControl.ReportQty row rule

In our copied rule, $rowCount was declared invalid, so we had to find another way to do this.

After some digging, we found that when the Employee doesn't have any jobs in their queue, LaborDtl.LaborDtlSeq is "undefined".

We changed the two unhappy row rules to test for "undefined". It worked, and now our controls behave as desired.

There appears to be a bug in Kinetic-related custom row rules. Our new rule works correctly, but when we look at it now, it is missing almost everything.

We thought it might have to do with copying an existing rule so we built our own from scratch. It had the same issue.

We tried building a customer rule in a non-MES environment and we did not have this issue.

Here is a screenshot of our custom row rule. It works, but something is not right.

Note: when closing this rule the UI asks if you want to save your changes.

Create an event that allows the button to call the new Report Quantity Function

You can create new events in three ways. You can create new a new one, copy an existing one, or select a control (like our btnCustomReportQty), and in Properties go to Behavior>OnClick and click the "+" on the right.

Once we had our new event wired to our button click, we added an erp-function to our event. Using Properties>Advanced we configured the call to our ReportQuantity Epicor Function.

Key properties are:

• API Key (allows access to the Function)

• ERP Functions Library (contains one or more Function)

• Service Operation (the actual Function being called)

• Method Parameters (if the Function uses input parameters, which ours does).

• Our Function requires the following parameters:

• LaborHedSeq

• LaborDtlSeq

• employeeID

• ReportQty

We set our Field/Field Values as follows:

If you've been paying attention, you may remember that earlier we said that we bound our numeric "numQtyToReport" to  CallContextBpmData.QtyToReport.

In testing, we found if we clicked our new "Save" quickly more than once, we would Report Qty more than once.

To fix this we first tried setting CallContextBpmData.QtyToReport = 0 after the function call with a row-update in our event, but this didn't prevent our issue.

We finally settled on a using two row-updates before we call our function.

• The first sets CallContextBpmData.Number01 = to CallContextBpmData.QtyToReport.

• The second sets CallContextBpmData.QtyToReport = 0.

This strategy worked. The rows are updated before the function call, so the "double-click" still happens, but any call after the first one is stopped by the UI because 0 is an invalid ReportQty.

Conclusion

Application Studio combined and Epicor Functions are powerful tools for controlling the functionality and user experience in Epicor Kinetic.

There is a bit of a learning curve, but once you've mastered the concepts you can implement some very useful modifications. It does seem that the current version has a few minor bugs (sorry Epicor, should we say issues or quirks?). Hopefully these will be addressed in a future release.

Bonus Material

Something we learned in this project is how to access data that is in context and use that to see what's going on under the hood a bit.

Our button click event's erp-function will pass the selected LaborDtl record to the called Epicor Function. What is actually in the queue are LaborDtl records. 

In order to find out what kind of row rule test we could use to see if there were any jobs in the employees queue, we added a erp-message-handler to our event.

In the erp-message-hander>Advanced>Param Message setting, you can interrogate data.

The syntax looks like this:

• LaborDtl.LaborDtlSeq = "{LaborDtl.LaborDtlSeq}"

Which, when the employee queue has no jobs, results in this message:

• LaborDtl.LaborDtlSeq = "undefined"

Note - the double quotes are treated as literals, they are not required. Without them our message would read:

• LaborDtl.LaborDtlSeq = undefined

Here is another example:

LaborDtl.LaborDtlSeq = "{LaborDtl.LaborDtlSeq}", "{CallContextBpmData.QtyToReport}", ok?!? "{MESControl.ReportQty}"===true

And here is a screenshot of the erp-message-hander Param section:

We hope you've enjoyed this article.