Top 10 Tips & Tricks for Building Custom Steps in SAS Viya

[#1]

Custom Steps enable you to create a user interface to complete a specific task.  Available custom steps are listed on the Steps pane in SAS Studio on the Custom Steps tab. They can then be used in multiple SAS Studio Flows or stand-alone to ensure a common, repeatable process.

Below are the top 10 Tips and Tricks for building custom steps in SAS Viya.

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

Let’s look at each of these in more detail.

1. Review the custom step sample controls

The sample controls provide an explanation for each of the control types you can use when designing a custom step.

In SAS Studio on the Steps pane, select  → Sample controls

On the Design tab, select Data in the Control Library section to view the Data page of the Sample Controls custom step.

There is an example and text explanation for each of the Data controls with the exception of the Output Table data control.  There is an example and text explanation of that control on another page.

Select Controls in the Control Library section to view the Controls page of the Sample Controls custom step.

There is an example and text explanation for each of the Common controls.  Expand the control to view each example and text explanation.

Select Dependencies in the Control Library section to view the Dependencies page of the Sample Controls custom step.

There is an example and text explanation for dependencies with check box, number field, and drop-down list.  Expand the control to view each example and text explanation.

Select Output in the Control Library section to view the Output page of the Sample Controls custom step. On this page is an example and text explanation for the Output table Data control.

2. Review the custom step starter templates

The starter templates are example custom steps with associated program code, so you can review some real-life examples of how they were built.

On the Steps pane, select  → Starter templates → Basic - Rank.

There are also more complex starter template examples to review; however, for this post we will focus on the basic example.

Select the Select an input table control to view its properties.

The property ID for the control is inTable.

Select the Add a numeric column control to view its properties.

The property ID for the control is rankBy.

Select the Specify the output table control to view its properties.

The property ID for the control is outTable.

Select the Create a new column for the ranked column check-box control to view its properties.

The property ID for the control is createNewVariables.

Select the Program tab to view the code for the custom step.

The screenshot above shows the property ID references for the various controls from the user interface design for the custom step.

3. Search the Custom Step GitHub Repository

Search the Custom Step GitHub Repository for any similar custom steps that you may be trying to build and download them to use as a starting point for your design.

In a browser enter: https://github.com/sassoftware/sas-studio-custom-steps. At the bottom of the page, you can view the README information for the repository.  Select the link for List of custom steps in this repository.

Scroll down until you locate the entry for GeoDistance with Rounding in the table of Available Custom Steps.

Select the link for GeoDistance with Rounding to view additional descriptive information about the custom step.  On the left-hand side in the Files section, select the GeoDistance with Rounding.step.

Click  to download the file for this custom step.

Return to SAS Studio and select  to view the SAS Content folders.  Expand the SAS Content folder and select the Public folder (or whatever folder to which you want to upload the custom step).  Click  to upload files to the selected folder.

Click  and navigate to Downloads folder.  Select the GeoDistance with Rounding.step file and click Open.

Click Upload to upload the attached file(s).

Select  to view the Steps pane.  Select the Custom Steps tab to confirm the GeoDistance with Rounding custom step is listed.

There is a SAS Community article on how you can download all the custom steps for this repository.

4. Test the custom step using stand-alone mode

Use the stand-alone mode to quickly test your custom step.  To do this for the GeoDistance with Rounding custom step, in the Steps pane, select the GeoDistance with Rounding custom step and right-click then select Open to open the custom step in stand-alone mode.

Select the following required information for the custom step and click  to run the custom step in stand-alone mode.

• Input table: AFRICA
• Calculate distance in: Miles
• Location 1:
  • X
  • Y
• Location 2:
  • LAT
  • LONG
• Output table: TEST

Review the Output Data tab.

5. Review the log for macro variable names and values

Review the log for the macro variable names and their respective values.  Select the Log tab and expand the section named /*region: Generated macro initialization*/.

Scroll up to the section heading named /* Macro variables derived from user input to this step - BEGIN */ to view macro variable names and current values for the user input from the custom step.

Notice that the macro variable disType is set to Miles.

Scroll to the section closer named /* Macro variables derived from user input to this step - END */. This ends the section of the macro variable names and values for the user input from the custom step.

6. Use %put statements to aid in the testing of your code

Use %put statements to aid in the testing of your code.  This allows you to write out values or show that you have reached a particular portion of the code.

In the Steps pane, select the GeoDistance with Rounding custom step and right-click then select Edit to open the custom step in edit mode.

Select the Program tab to view the code for the custom step. Add the following line at the beginning of the code block and save the changes.

%put The value of disType is: &disType;

Now, when the same test from the previous section is run the value of the disType macro variable written to the log.

7. Use %global statement to assign macro variable values for use outside of the custom step

Use a %global statement to assign macro variable values for use outside of the custom step, if needed.

On the Program tab, add the following lines of code at the beginning of the code block and save the changes:

%global g_disType;

%let g_disType=&disType;

Now, the global macro variable &g_disType can be referenced outside of the custom step in a SAS Studio flow.

8. Use the New column control (if your code creates a new column)

Use the New column control if the code within your custom step creates a new column.  You can hide this column if you don’t want the end user to change the name or you can choose to display it if you want to give the end user the opportunity to name the new column.

Select the Design tab to view the page design(s) for the custom step.  Select the Calculate Geo Distance page tab and then select the Distance between the locations new column control to view its properties.

The ID name for the control is newColumn.

9. Use Port Details to control the output columns

Use Port Details to control the output columns from the custom step.  If removing columns, you also need to remove them in the code of the custom step.

Click  to view the port details for the custom step.  Select  in the Output Tables section to view the output table structure for the custom step.

All the columns from the input table are part of the output in addition to the new column Distance between the locations.

If you decide to drop columns from the output table, then you should also explicitly drop the columns in the Program code as well.

10. Create an About tab for the custom step

Create an About tab to provide a description of the custom step and its release date information.

Click the About page tab for the custom step to view its properties. It is a best practice to include a Text control on this page with information about what the step does and its version information on this tab.

To create a new page for an About tab, select  in the Control Library section on the Design tab for the custom step.

Summary

Here is the list of the top 10 tips and tricks for building custom steps in SAS Viya again.

Additional Resources

Hope you find these tips & tricks helpful!  Here are some additional resources to aid you in building custom steps with SAS Viya.

• Training Course: Developing Custom Steps with SAS® Studio Analyst
• Documentation: SAS Help Center: SAS Studio: Working with Custom Steps
• SAS Community Articles: Search - SAS Support Communities for Custom Steps
• Quick Start Video: Create Custom Steps with SAS Studio
• YouTube Video Series: Creating a Custom Step in SAS Studio
• GitHub Repository of Custom Steps: https://github.com/sassoftware/sas-studio-custom-steps.

Find more articles from SAS Global Enablement and Learning here.