There are times when the default parameters created for a SysOperation Framework job do not function as desired. In this article, learn to override the D365 SysOperation Framework lookup to show different columns and data than are shown by default. All of this is accomplished by creating a fourth class that extends SysOperationAutomaticUIBuilder.
Review
Before creating this fourth class, let us review. In a previous article, I explained how to develop a batch job using SysOperation Framework in D365. Before adding a user interface to your batch job you need to first follow the steps in that article. As a reminder, you need to create three classes in Visual Studio and add them to a project.
- First, create a Contract class. This was empty in the last article. In this article, we will add code to this class. This will contain the parameters that will be shown in the D365 SysOperation Framework user interface.
- Secondly, you need to create a Service class. One that extends the class SysOperationServiceBase. This class contains the code that performs some kind of process. In this article, we will allow a developer to use the parameters from the Contract class to affect how the processing code works.
- Thirdly, you need to create a Controller class. This class really just configures how the batch job works. It tells the system what method on the Service class to run.
Add Parameters To The Contract Class
Before overriding the D365 SysOperation Framework lookup to change the default behavior of the parameters, we need to first add those parameters.
To add parameters that show on the Dialog form you need to add code to the Contract class. See my article on D365 SysOperation Framework Parameters for the detailed steps.
In the previous article we only added an integer parameter. For the examples in this lesson, we need some string parameters with lookups. Update your Contract class so that it looks like this:
[DataContractAttribute]
class rsmTutSysOperationsContract
{
private int retentionDays;
private CustAccount custAccount;
private InventLocationId inventLocationId;
private WMSLocationId wmsLocationId;
[DataMember,
SysOperationLabel(literalStr("Retention days")),
SysOperationHelpText(literalStr("Data older than the retention days will be cleaned up.")),
SysOperationDisplayOrder('1')]
public int parmRetentionDays(int _retentionDays = retentionDays)
{
retentionDays = _retentionDays;
return retentionDays;
}
[DataMember,
SysOperationLabel(literalStr("Customer account")),
SysOperationHelpText(literalStr("The customer account to use")),
SysOperationDisplayOrder('1')]
public CustAccount parmCustAccount(CustAccount _custAccount = custAccount)
{
custAccount = _custAccount;
return custAccount;
}
}Notice, we added the following variables and parameters: custAccount, InventLocationId, wmsLocationId. Additionally, we added the ‘DataMember‘ attribute above each one. This will cause a parameter to now show on batch job form. The result looks like this:
SysOperationAutomaticUIBuilder
Next, in order to use D365 SysOperation Framework overrides to change the way these parameters work, we need to add a fourth class. The SysOperationAutomaticUIBuilder class is a fourth class. First, I will explain the steps for creating this class. Then, I will show you all you can do with with several examples.
First, in Visual Studio, right click on your project, and select Add>New Item. Next, select the ‘Class’ type, and provide a name for your class. In this example, I will call the class ‘rsmTutSysOperationsUIBuilder‘. It is a best practice to end the name of this class with ‘UIBuilder‘.
Finally, add this code to the end of the class declaration: ‘extends SysOperationAutomaticUIBuilder‘. The final code should look like this:
class rsmTutSysOperationsUIBuilder extends SysOperationAutomaticUIBuilder
{
}Link The Contract To the UIBuilder Class
Importanly, now that the UIBuilder class is created, you need to link the Contract class to the UIBuilder class. The ‘parm‘ methods in the Contract class will cause parameters to show on the Dialog form without a UIBuilder class. However, the UIBuilder class is needed to override the default functionality.
SysOperationContractProcessing Attribute
First, in the Contract class, add the attribute ‘SysOperationContractProcessing‘ above the class declaration. Pass in the name of the UIBuilder class you created. The code will look like this:
[DataContractAttribute]
[SysOperationContractProcessing(classStr(rsmTutSysOperationsUIBuilder))]
class rsmTutSysOperationsContract
{
...
}Recap
To review, the UIBuilder class is created and linked to the Contract class. Additionally, the Contract class variables and parm methods are created. Now, we can demonstrate how to override the D365 SysOperation Framework lookup.
Reference The Parameters In The UIBuilder Class
Next, in the UIBuilder class, we need to do the following four things.
- First, declare a variable to hold a reference to the Dialog form control we wish to override.
- Second, add code to get a reference to the field control and store it in the variable created in step one.
- Third, tell the system to replace the code in the ‘lookup‘ method with a new method whose name we provide.
- Fourth, write the new ‘lookup‘ method.
Next, I will explain each step.
Add Dialog Field Variable
First, add a variable of type ‘DialogField‘ to the UIBuilder class. Give the variable a name that matches the parameter you are setting.
class rsmTutSysOperationsUIBuilder extends SysOperationAutomaticUIBuilder
{
private DialogField custAccountDialogField;
}Get Dialog Field Control
Secondly, we need to add a method named ‘PostBuild‘. The ‘PostBuild‘ method exists on the base class. We need to call ‘super()’ which calls all the code in the base class. Then, this new code will use the specified parm method on the Contract class, to find and get a reference to the field control on the Dialog form. Then store it into the DialogField variable we declared in the first step. Do not worry if you do not fully understand this code at first. Add the following code:
public void postBuild()
{
super();
//get reference to custAccount dialog field
custAccountDialogField = this.bindInfo().getDialogField(this.dataContractObject(), methodStr(rsmTutSysOperationsContract, parmCustAccount));
}Notice, the code specifies the name of the Contract class and the name of the parm method. Swap these out for the name of your Contract class and parm method.
Override The SysOperation Lookup
Now that we have a reference to the control, we need to tell the system to override the ‘lookup’ method and replace it with a method that we write. The ‘registerOverrideMethod‘ allows us to do this. The first parameter tells the system what method we are replacing. Next, the second parameter tells the system what method to run instead. In this case, we pass in the method named ‘lookupCustAccount‘ on the rsmTutSysOperationsUIBuilder class. Add code to make the method look like this:
public void postBuild()
{
super();
//get reference to custAccount dialog field
custAccountDialogField = this.bindInfo().getDialogField(this.dataContractObject(), methodStr(rsmTutSysOperationsContract, parmCustAccount));
//override the lookup method
custAccountDialogField.registerOverrideMethod(methodStr(FormStringControl, lookup), methodStr(rsmTutSysOperationsUIBuilder, lookupCustAccount), this);
}Write The Lookup Method
In the last section, we told the system to replace the existing ‘lookup‘ method with a method named ‘lookupCustAccount‘. Therefore, add this method now to the UIBuilder class. In my example, the class is named rsmTutSysOperatoinsUIBuilder:
private void lookupCustAccount(FormStringControl _formStringControl)
{
Query query = new Query();
QueryBuildDataSource qbds;
SysTableLookup sysTableLookup;
sysTableLookup = SysTableLookup::newParameters(tableNum(CustTable), _formStringControl);
qbds = query.addDataSource(tableNum(custTable));
sysTableLookup.addLookupfield(fieldNum(CustTable, AccountNum), true);
sysTableLookup.parmQuery(query);
sysTableLookup.performFormLookup();
}This code uses the passed in FormStringControl parameter and the SysTableLookup class to make the lookup work.
First, this code tells the system to show data from the ‘CustTable‘ table. Secondly, it tells the system to show the ‘AccountNum‘ field in the lookup grid that is shown. Lookups are often overridden to show the columns that are most useful for what the user is doing. Thirdly, code can be added to filter the records shown in the lookup grid. No filter is applied in this example. Finally, the ‘performFormLookup‘ method causes the drop-down to be shown.
For more details on how to write this type of method, see my article on How To Override A Lookup.
Demonstration
Finally, after overriding the D365 SysOperation Framework lookup, run the batch job in the browser. In this example, go to Accounts Receivable>Tutorials>process sys operations job. Click on the customer account drop-down. Notice, unlike the default lookup that shows multiple columns, this lookup only shows the customer account column.
As a reminder, overriding a lookup is usually done to change the columns shown. Or to filter the results that show in the drop-down.
Parameters, Defaults, Validation, Mandatory and UIBuilder
Please see these other articles for more advanced SysOperation Framework functionality.
First, learn how to add parameters to your batch jobs. D365 SysOperation Framework Parameters
After adding parameters to a SysOperation Framework batch job, you may want to set those parameters to start with an initial value. Learn how to set a D365 SysOperation Framework default value.
Additionally, add validation to the parameters. D365 SysOperation Framework Validation
Lastly, learn to add D365 SysOperation Framework mandatory parameters that show a red outline and a star to indicate the field must be populated.
For another great reference on how to create classes using the SysOperation Framework in D365, see this article.
Conclusion
The ability to provide parameter values to a D365 SysOperation Framework batch job allows the background process to run against different data sets. To ensure that only valid parameter is passed in, the D365 SysOperation Framework lookup can be overridden to only show appropriate values. Additionally, the columns shown in the lookup grid can be changed to allow users to more easily use the built in filters to find the right value.
