D365 SysOperation Framework Mandatory

In the last tutorial, I showed you how to add validation to the parameters of a batch job. In this article, learn to add D365 SysOperation Framework mandatory parameters. Validation can be added to ensure a user cannot run the job without setting a parameter. However, code can be added to actually show the parameter with a red outline and a star to indicate the field must be populated. This makes it that much clearer to the user that they need to set this parameter. 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.

1. 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.
2. 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.
3. 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 making the D365 SysOperation Framework mandatory 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.

For the examples in this lesson, we will add two date controls. Update your Contract class so that it looks like this:

[DataContractAttribute]
class rsmTutSysOperationsContract 
{
    private FromDate dateFrom;
    private ToDate dateTo;

    [DataMember]
    public FromDate parmDateFrom(FromDate _dateFrom = dateFrom)
    {
        dateFrom = _dateFrom;
        return dateFrom;
    }

    [DataMember]
    public ToDate parmDateTo(ToDate _dateTo = dateTo)
    {
        dateTo = _dateTo;
        return dateTo;
    }
}

Notice, we added the following variables and parameters: dateFrom and dateTo. 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 add D365 SysOperation Framework mandatory parameters, we need to add a fourth class. The SysOperationAutomaticUIBuilder class is a fourth class.

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 make the parameters mandatory.

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 add D365 SysOperation Framework mandatory parameters.

Reference The Parameters In The UIBuilder Class

Next, in the UIBuilder class, we need to do the following threethings.

1. First, declare a variable to hold a reference to the Dialog form control we wish to override.
2. Second, add code to get a reference to the field control and store it in the variable created in step one.
3. Third, tell the system to make the field control mandatory

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 dialogFieldDateFrom;
    private DialogField dateToDialogField;
}

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();

        //from date
        DialogField dateFromDialogField = this.bindInfo().getDialogField(this.dataContractObject(), methodStr(rsmTutSysOperationsContract, parmDateFrom));
        

        //to date
        dateToDialogField = this.bindInfo().getDialogField(this.dataContractObject(), methodStr(rsmTutSysOperationsContract, parmDateTo));
        
    }

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.

Make The Field Control Mandatory

Now that we have a reference to the control, we need to tell the system to make the field mandatory. Fortunately, there is a method named ‘mandatory‘ on the field control that we can call to do this. Simply, pass in true to this method. Add code to make the method look like this:

    public void postBuild()
    {
        super();

        //from date
        DialogField dateFromDialogField = this.bindInfo().getDialogField(this.dataContractObject(), methodStr(rsmTutSysOperationsContract, parmDateFrom));

        dateFromDialogField.fieldControl().mandatory(true);

        //to date
        dateToDialogField = this.bindInfo().getDialogField(this.dataContractObject(), methodStr(rsmTutSysOperationsContract, parmDateTo));

        dateToDialogField.fieldControl().mandatory(true);

    }

Demonstration

Finally, after adding the D365 SysOperation Framework mandatory parameters, run the batch job in the browser. In this example, go to Accounts Receivable>Tutorials>process sys operations job. Notice the fields now show with a red outline. Additionally, they have a red star inside. These indicate that the fields are mandatory and must be populated.

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

Next, override the drop-downs to show only validate options. D365 SysOperation Framework Override Lookups

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

For another great reference on how to create classes using the SysOperation Framework in D365, see this article.

Conclusion

Marking parameter fields as mandatory allows a user to right away know what they need to populate. While validation can be added to ensure a user sets a parameter, they would still have to click the ‘ok’ button before receiving the validation message. The red outline and the red star matches the mandatory functionality found on other Microsoft Dynamics 365 forms. This provides clarity and speed of use to the user.

Peter Ramer

Peter Ramer is a part of the Managed Application Services team at RSM working on Microsoft Dynamics 365. He focuses on the Retail and Commerce industries. When he is not solving problems and finding ways to accelerate his clients' business, he enjoys time with his three kids and amazing wife.