Create a SAS Viya Job with a prompt using Task Prompts
In the Data Entry article series, I've been building SAS Viya jobs using HTML forms to pass parameters. SAS Viya 3.5 introduces the functionality to create prompts for SAS Viya jobs using the Common Task Model (CTM). The CTM (Common Task Model) is an XML based model that is used to build custom tasks in SAS Studio. The SAS Viya jobs are using a similar syntax to build the prompts.
If you are new to SAS Viya and SAS Viya jobs, a quick definition is that SAS Viya jobs are the way to submit custom code in batch similar to the role of Stored Processes in SAS 9. At the end of this article, you should be able to create a prompt for a SAS Viya Job using XML syntax.
Let me first show you the prompt that will be generated.
Select any image to see a larger version.
Mobile users: If you do not see this image, scroll to the bottom of the page and select the "Full" version of this post.
The job that creates an HTML table based on SASHELP.CARS dataset. The end-user selects values for specific variables and the SAS code filters the data that are displayed in the report. The variables used to filter the data are:
- the Origin
- the Type
- the DriveTrain
- the Invoice
The prompts have dependencies between them. Selecting the origin of the car filters the prompt for the Type which impacts the list of available options in the DriveTrain drop-down list which is referred to as a combobox.
In this example, the Financial aspect section is only displayed when Asia is selected for the Origin variable. You will see the selection dependency in action from the demo I included at the end of the article.
In this example, the Financial aspect section is only displayed when Asia is selected for the Origin variable. You will see this in the little demo at the end of the article.
Building the SAS Viya Job
SAS Viya Jobs can be created from two applications: SAS Job Execution web application or SAS Studio. I will use SAS Studio as it is considered as the programming interface of choice for SAS code and SAS Viya Jobs.
Within SAS Studio 5, from the New menu, select Job > Definition.
When the job opens up in SAS Studio, choose the type of Task prompt.
You are now ready to start building the job. The job has two components:
- Code: SAS code that is executed.
- Task prompt: XML code that defines the layout of the prompt
The first step will be to create the prompt. If you want to follow along the SAS code and the Task Prompt XML are available for download: code.sas and taskPrompt.xml
Building the prompt
As mentioned, the Task prompt is defined using XML code.
In this basic example, the XML will be composed by different sections:
- Registration: information about the prompt itself
- Metadata: information about the data source and options
- UI: information about the prompt structure
- OptionDependencies: information about the dependencies between options
This is the basic structure of the file.
The next step will be to fill information for each section of the XML file.
Registration section
The Registration section contains the information about the prompt.
The XML tags are self-descriptive. For the Version tag, it is a good practice to specify the version that was used to create the prompt. It will be easier to maintain when future releases will add functionalities and the developer wants to know if the functionality was available or not in the release it was created in.
Metadata section
The Metadata section contains information about the data source and also the options. Let’s first see how the DataSources section is written.
This section references the different data sources that will be used in the prompt. In this example, only one data source is used but you can define multiple sources. The prompt queries the data source to populate some of the fields. The data source needs to be accessible from the SAS Compute Server and the library should be pre-assigned when the Compute Server starts up.
The DataSources section also defines the filters that will be available for the data source. This information is used when a combobox filters the data of another element of the user interface. As you can see, the filter can reference:
- a column
- a column filtered based on expression using a value selected from the other prompts
In the typeFilter filter, the where section filters the type variable using the value of var_origin to filter out the origin variable. As you see, the Value tag uses option.
It is now time to explain what options are.
Options section
The Options are the building blocks of the prompt. They are defining the properties of the UI elements. Each option has a name that should be unique that name is used when building expressions as we have seen in the Filter but also to define elements in the UI or within the OptionsDependencies section.
In our example, the options are defined in the following code example. Click on the image to enlarge.
Every element that will be displayed in the prompt needs to be defined as an option. An option has a name and an inputType. The list of inputTypes is quite large as you can see in the documentation
Looking at the var_origin option, you see that the originFilter defined in the data source is assigned to the filter property. This creates the link between the data source and the UI element. As a result, the combobox named var_origin will be populated by the origin variable from the data source. The same will happen for var_type and var_driveTrain.
Each option type has a specific properties that are unique. If you want to know more about each type and properties, the documentation is the best source of information.
Now that building blocks of the interface are defined, it is time to build the layout of the prompt.
UI section
The UI defines different types of elements and each element points to an option to retrieve the properties to be applied.
- Container element displays a tab
- Group element displays a group of elements that can be collapsed or expanded
- OptionChoice displays elements like selects and comboboxes
- OptionItem displays a single element like an input field or a slider
- DataItem is a specific element that displays the name of the data source
For more information about the different options, refer to the documentation
Here is the UI section for our example:
OptionsDependencies section
As a last section, we have the OptionsDependencies. This section will define if elements of the UI should be displayed or not based on the value of another element. In our scenario, we want only to display the financialGroup if the var_origin is set to Asia.
Here is the code to achieve this:
Now that the prompt is defined, it is time to write the SAS code that will be executed based on the values from the prompt.
Writing the SAS code
The values selected from the prompts are passed to the SAS code as macro variables. If you want to know which macro variables are available, you can save the following code in the code tab of the job: %put _ALL_;
The code in this example is basic as the purpose is to demonstrate how to create the prompts and use the values from the prompts in the job execution.
The code first defines some macro variables that will store the different parts of the where clause used in the proc print.
The generate macro is in charge of checking the existence of the macro variable and to generate the elements of the where clause.
The last bit is a simple proc print that creates an HTML output.
Run the SAS Viya Job
Now that you have both the prompts defined and the SAS code complete, you can run the SAS Viya job. If you want to look at the SAS log after execution, you can activate the Show Log. To activate that option, you should save the changes after clicking on the button. When your job is ready for production, don't forget to inactivate that option otherwise the end-user will see the SAS Log.
Little demo
Conclusion
SAS Viya Jobs are a great way to submit custom code to solve your reporting and analytic needs. You can create prompts using different techniques HTML forms or Task Prompts. Using the Task Prompt, you don't need to know about the HTML syntax and writing XML is enough. During the building process, you should always keep an eye on the documentation as it contains a lot of information that will help you to pass the hurdles that you may encounter while building the Task Prompt. At this stage, the SAS Viya Jobs with Task Prompts can be used within SAS Job Execution web application and SAS Studio. It is not currently possible to use them within SAS Visual Analytics reports as Web Content or Data-Driven Content objects. The limitation is due to the usage of iFrames in SAS Visual Analytics and for security reasons the iFrames are not allowing pop-ups. The objective will be to give the administrators the opportunity to allow or not the pop-ups. As soon as that option will be available, the SAS Viya Jobs with Task Prompts will be the best option for the developers who prefer to write XML code to building an HTML form.
Share this content:
SAS Users channel on YouTube
