Explaining Custom Steps using SAS Studio Assets

[#1]

This blog enables you to demonstrate the fundamentals of custom steps using templates that are supplied with SAS Studio!

We’ll start by using a template to create a custom step and examine the components to get a high-level overview of what is needed. Then, we will explain how to use a custom step in a flow in SAS Studio or as stand-alone in SAS Studio.

This blog assumes you have a basic knowledge of building flows with SAS Studio flows. Knowledge of SAS Programming and the SAS Macro language is also necessary to create custom steps in SAS Studio, although not needed to use the templates.

What is a custom Step?

A custom step provides a user interface to enable customization of SAS code that is routinely performed by you or other SAS Studio users. It could be as simple as creating a user interface to select a date within a specified date range. Or you might not want to expose inexperienced coders to a complex program, but the program requires specific input parameters each time the code is submitted.

 

Explore a Custom Step Template

Let’s begin by creating a custom step using the templates available and explore some of the capabilities you’ll see when creating your own custom step.

I've already logged into SAS Studio. The starter template we will use, will create a simple custom step to rank one column from a SAS data table. The easiest method to create a custom step is to use the Designer tab, which is available in SAS Studio Analyst and SAS Studio Engineer.

1. Using the navigation pane, click the Steps icon.
2. Using the Steps toolbar, click New and sample custom steps, select Starter templates, and select Basic – Rank. We are now editing a custom step.
   
   

3. The Designer tab is a visual interface to help you quickly build the JSON code for the prompt user interface. The Designer tab has three main components:

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

Controls can be added by dragging them from the extensive list in the Control Library to the workspace area, also referred to as the canvas.
 

The Properties pane is then used to modify the controls settings. For example, every custom step requires at least one Page control. Here the Page control ID is inPage and the label that the user will see is Rank Options. Both properties have an asterisk, which indicates they are required. You will soon see the ID  is especially important and is a common control property!

On the canvas, select the control labelled Select an input table to view the properties of the Input Table control, which has additional options compared to the Page control.

On the canvas, right-click the control labelled Select an input table. You can copy and paste any controls that already exist, which means you can bypass the initial setup and configuration when implementing your custom step. You can also move the controls up and down the canvas, move them to a different section or page, and delete them.

4. Whilst you are constructing your user interface using the Designer, the appropriate JSON code is added to the Prompt UI tab. Select the Prompt UI tab to view, and edit, the JSON code.

5. Select Program to view the SAS code that is executed when a custom step is run. Each control in the Designer tab generates one or more macro variables. The ID of each control is used to generate SAS macro variables that can be used in SAS code on the Program tab of the step. The values of these macro variables are generally derived from the user input at run time.

6. Click Preview to view the controls in the user interface as a new tab. You can add the options required in the preview to test your controls, however you cannot submit the code here. Please note the information alert that states “Input and output tables do not display in flows; they will display as ports”. We will see this in action when we use the custom step in a flow.

7. Click the Rank-Basic.step tab to return to edit the custom step tab. The vertical menu on the right side of the Designer, the custom step's Properties menu, provides access to attributes assigned to the custom step. These attributes include a summary of properties, port details, and prompt hierarchies.

8. Let’s save the custom step by clicking Save As and navigating to the Shortcut to My Folder. Confirm the custom step is named Rank-Basic and click Save.

There you go! Now we have our custom step, saved from a template, let’s move on to look at the various methods of using the custom step in SAS Studio.

Using a Custom Step in SAS Studio.

The first method is using the custom step in a flow. The second method is using a custom step in a tab in the SAS Studio workspace, also referred to as stand-alone. Both methods will create an output data table that includes ranked values of MSRP from the SASHELP.CARS table.

Use a Custom Step in a Flow

 1. On the SAS Studio toolbar, in the top left of the application, click New and select Flow.

 2. If necessary, click Steps in the navigation pane and select Shared.

 3. Right-click Rank-Basic and select Add to flow.

4. Now that the step has been added to the flow we refer to it as a node in the flow. When the node is selected, the node details appear under the flow canvas so that we can specify the attributes and content.

Notice there are no options to add the input and output tables and the Select a column to rank control is not yet available. We need to add the input table first. There are multiple methods of achieving this, I will go with simply add the SAS table from the libraries section of the navigation pane.

Select Libraries in the navigation pane and expand SASHELP. Drag and drop the CARS table to the input port of the Rank-Basic custom step. Once the mouse tool tip says Connect to input port, you can drop the table.

In the Table node details, notice the Library text field states SASHELP and the Table name text field states CARS.

5. Select the Rank – Basic node to return to the node and click Add columns on the Select a column to rank prompt. Click MSRP and select OK.

6. Check the Create a new column for the ranked column checkbox.

7. Click Run entire flow to submit the flow.

8. Select Submitted Code and Results and click Output Data (1) to view the output data.
 

Scroll to the right of the table and view the column named rank_MSRP that contains the ranking number.

Notice the name of the output table includes a long string of random numbers and is not very memorable.

9. Let's direct the output data to a specific table and location.

Select the Flow.flw tab.

Right-click the output port on the Rank - Basic node and select Add a table.

In the node details on the Table Properties tab, type work in the Library field and RankData in the Table name field.

Click Run entire flow to execute the flow.

Select Submitted Code and Results, Output Data (1) and confirm the table name is RANKDATA.

Open a Custom Step in a Tab

Let’s move on to the second method of using a custom step, which is opening directly in a tab.

 1. If necessary, select Steps in the navigation pane and click Shared.

 2. Right-click on Rank-Basic and select Open in a tab. This opens a stand-alone custom step as a tab in the SAS Studio workspace.

• • Stand-alone custom steps are session-based, so when you close the custom steps, any specified values are not saved.
  • You can open the same custom step multiple times in the SAS Studio workspace and can provide different values for the controls to quickly compare the results.
  • You may also have already noticed that the input and output table controls are visible when using the step as stand-alone but not when using the step in a flow.
    
    

3. Click Input data, select SASHELP, select CARS and click OK.

4. In the Select a column to rank prompt, click Add columns, select MSRP and click OK.

5. Click Output data, select WORK and type Rank in the Table field. Click OK.

6. Check the Create a new column for the ranked column checkbox.

7. Click Submit custom step.

8. Once the code is submitted, the results appear. Scroll to the right of the data table and review the rank_MSRP column.

9. Click Code panel and Log to review the log of the code that was submitted using the custom step. RANK has 428 observations and 16 variables.

SAS Studio custom steps are a great way to promote code reusability and include many more features. Look out for my next blog that shows how to access and explore other custom steps available!