SAS Viya 2021.1.2 (June 2021) – Custom Step UI Control Dependency

1 Like

New in SAS Viya 2021.1.2 (June 2021) stable release is the ability to have controls in the Custom Step UI dependent on the value/selection of another control. In a previous post, I walked through an introduction of Custom Steps in SAS Studio Flow. In this article, I expand on that introduction and demonstrate how you can use control dependencies in the user interface (UI) of a Custom Step.

Custom Step UI Control Dependency

Using dependent controls allows you to control which controls are displayed based on a selection or entry of another control. For example, if a checkbox is checked, then display a field selection control and if it is not checked, then don't display that control.

The new property for dependent controls is called visible. You set an expression for this property based on another control and if is evaluated to be true, then the control that has this property will be visible (displayed). You reference the other control by adding a $ before its id (e.g., "$control_id").

I will review some examples that will become part of the Sample Controls example in SAS Viya 2021.1.3 (July 2021) stable release, so you can see how to build your own.

Checkbox Dependency Example

Below is the JSON for a checkbox dependency. The Text field will only be displayed if the checkbox is checked. Note the "visible" property for the textfield control is set as "$ckbox_depend" referencing the checkbox control.

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

The check box is checked, so the text field is displayed.

The check box is NOT checked, so the text field is NOT displayed.

Number Field Dependency Example

In this example, different text is displayed based on the number entered. Note the expressions used for the "visible" properties below to display the various text. (You can click the picture to enlarge the screenshot). For example, in the expression "!$num1" the use of ! indicates that the field is null (or empty) and this expression will evaluate to true if that is the case.

The number text field is blank, so "The number field is empty." text is displayed.

The number entered is a negative number, so the "The number is less than zero." text is displayed.

The number entered is greater than or equal to 0 and less than or equal to 100, so the "The number is between 0 and 100." text is displayed.

The number entered is greater than 100, so the "The number is greater than 100." text is displayed.

Drop-down Example

In this example, different checkboxes are displayed based on the selection in the drop-down. Note the expressions used for the "visible" properties below to display the various checkboxes. (You can click the picture to enlarge the screenshot).

No fruit category is selected, so no checkboxes are displayed.

The fruit category of Berries is selected, so the 3 checkboxes where the "visible" expression is equal to Berries are displayed.

The fruit category of Melons is selected, so the 3 checkboxes where the "visible" expression is equal to Melons are displayed.

Remove Duplicates Custom Step with Control Dependency

To demonstrate the Custom Step UI Control Dependency in action, I created a CAS Remove Duplicates Custom Step. This example is modeled after the Remove Duplicates node in SAS Data Studio. For more information on this node, refer to its documentation in the SAS Data Studio User's Guide. The CAS Remove Duplicates custom step example, I walk thru below is available in the {INTERNAL LINK - replace or remove} this GitLab repository along with other example custom steps.

Prompt UI

For my Prompt UI JSON, I first named my page and then added the input and output table sections like you would do most for Custom Steps you create.

Next, I want to add the controls for my actual step. Below is a screenshot of the Remove Duplicates node in SAS Data Studio on which I am modeling my custom step.

For my custom step, I only want the Select columns to group by section to be displayed only if the Remove duplicates across all columns checkbox is unchecked. To do that I add the following sections to my prompt UI JSON.

To create the control dependency to only display the column selection section if the checkbox is unchecked, I add "visible": "!$removeAll" to the column selector section to control its visibility. "removeAll" is the id of the checkbox and $ is how you refer to a control dependency. Then, ! is used to represent the checkbox being unchecked. If I wanted the dependency to be if the checkbox was checked, then I would leave off the !.

Next, I want the Remove duplicates across all columns checkbox to be checked by default. To do that I add the following to the values section of the JSON.

removeAll is the id of the checkbox and setting the value to true means the checkbox will be checked by default.

Confirm Control Dependency

Now I can preview my custom step to ensure my UI control dependencies are working as designed.

The Remove duplicates across all columns checkbox is selected by default and the column selection control is NOT displayed.

If I uncheck the Remove duplicates across all columns checkbox, then the column selection control is displayed.

Complete Prompt UI JSON

Below is the full Prompt UI JSON if you want to re-create this custom step for yourself.

{
   "syntaxversion": "1.0.0",
   "pages": [
   {
	"id": "RemoveDuplicates",
	"type": "page",
	"label": "Remove Duplicates",
	"children": [
	{
		"id": "inTable",
		"type": "inputtable",
		"label": "Select an input table:",
		"required": true
	},	
	{
		"id": "removeAll",
		"type": "checkbox",
		"label": "Remove duplicates across all columns"
	},
	{
		"id": "groupBy",
		"type": "columnselector",
		"label": "Select columns to group by:",
		"table": "inTable",
		"order": true,
		"max": 0,
		"min": 1,
		"visible": "!$removeAll"	
	},
	{
		"id": "outTable",
		"type": "outputtable",
		"label": "Specify the output table:",
		"required": true
	}
	]
   }
   ],
	"values": 
		{
			"removeAll":true
		}
}

Program

Note: The Template Code section discussed in my prior article on Custom Steps has been renamed to Program.

For the program code of the CAS Remove Duplicates custom step, I need to do a few things:

Remove the duplicate records by using the CAS action groupByInfo.
If the user selects to remove duplicates based on only certain columns, then put the list of selected columns in the format expected by the option inputs.

The simple.groupByInfo CAS action is the one used by the Remove duplicates node in SAS Data Studio. For more information on this CAS action review its documentation.

Program Code

Below is the full program code if you want to re-create this custom step.

/* CAS Remove Duplicates Custom Step Code */

/* Set GroupVarList based on Selected Columns */
%let groupVarList=;

%macro groupVars;
   %do i = 1 %to &groupBy_count;
      %if &i=1 %then %let groupVarList="&&groupBy_&i._name";
      %else %let groupVarList= &groupVarList, "&&groupBy_&i._name";
   %end;
%mend;
%groupVars;


/* CAS Remove Duplicates All fields */
%if &removeAll=1 %then %do;
proc cas;
    simple.groupByInfo /
    table ={ name="&inTable_name" caslib="&inTable_lib"}
    casout = {replace=1, name="&outTable_name" caslib="&outTable_lib"}
    includeMissing=TRUE generatedColumns={"NONE"};
run;
quit;
%end;

/* CAS Remove Duplicates Selected Field(s) */
%else %do;
proc cas;
    simple.groupByInfo /
    table ={name="&inTable_name" caslib="&inTable_lib"}
    inputs = {&groupVarList}
    casout = {replace=1, name="&outTable_name" caslib="&outTable_lib"}
    includeMissing=TRUE generatedColumns={"NONE"};
run;
quit;
%end;

Testing the Custom Step in SAS Studio Flow

Now that the custom step has been built and I've tested the control dependency in the UI, I need to test custom step and its code in SAS Studio Flow.

The following are the requirements for the CAS Remove Duplicates custom step:

CAS session established
CAS library for the input and output tables are part of the session. Note: You can use {INTERNAL LINK - replace or remove} this custom step.
Table node connected to input port that specifies CAS library and table name for which duplicate records should be removed
Table node connected to output port that specifies CAS library and table name for the session output table. Note: You will want to promote and/or save this table. You can use {INTERNAL LINK - replace or remove} this custom stepto do that.

I build a flow that meets these requirements.

The input table I am using for my test has 10 rows.

Running the flow with the selection below will remove a row if another one exists with ALL the same values in it.

When I run the flow, my output table has 7 rows.

If I change the selections for the CAS Remove Duplicates custom step to what is shown below, then only records where one already exists with the same Name and Email values are removed.

When I run the flow, my output table now has 6 rows.

Here is a GIF that shows the testing of the CAS Remove Duplicates custom step in action:

Summary

The use of control dependencies in the Custom Step UI allows you to add some logic to your UI design. For more information on Custom Steps and control dependencies, review its documentation.