Building web applications is one of the easiest approaches to provide data insights to a large amount of users. SAS Viya provides out of the box HTML data tags which can be used to build forms for SAS Viya Jobs as described in this article and documented here. This approach is handy as you can use HTML tags and populate the drop-down boxes with data coming directly from SAS. When the selection is done, the selected values are passed to the SAS Viya Job and code is executed based on these values. You can use the JavaScript library to build simple forms for your SAS code. As soon as you start building more advanced forms or integrate jobs into an existing web application, it can become more complex to write the code. In this article, you will learn how you can build a reusable set of JavaScript/TypeScript classes which can then be used to build customized forms or integrate easily with React components.
Requirements
A SAS Hackathon team has asked for mentoring on how to build a form for a SAS Viya Job. The team wants to pass multiple values to the job. They tried to use the SAS provided JavaScript library to build the form, but they want to add some business logic in the user interface. They want to display a list of checkboxes from which the user should at least select two values before they submit the form and execute the SAS Viya Job. While this seems easy to achieve, changing a select box into a list of checkboxes is not so obvious. Using the SAS provided JavaScript library, you can create a select HTML tag which supports multiple selections. You can also make the different elements dependent on each other by building cascading prompts. But you can be limited in the business logic you are implementing because the JavaScript library hides the complexity and doesn’t let you do a deep integration. This is where I come in and my creativity for solving custom web applications starts. My idea is to build a few functions which would let the web developers interact with the SAS Compute Server to build a dynamic web interface.
The objective is to provide nearly the same functionalities as the SAS provided JavaScript library, but in a less restricted approach. While the SAS provided JavaScript library provides HTML tags which can be inserted in a web interface, the SAS Viya API Wrappers for JS would just provide the needed infrastructure to get a list of:
- Retrieve Compute Server contexts
- Start a Compute Server session
- Retrieve a list of libraries from the active Compute Server session
- Retrieve a list of tables from a library
- Retrieve a list of columns from a table
- Retrieve the values from specific column
- Execute SAS code to retrieve data from the Compute Server session
- Close the Compute Server session
This would basically cover the needs of a web developer when building a custom web application which integrates dynamic data into forms.
SAS Viya API Wrappers for JS
What the SAS Viya API Wrappers for JS is not: a replacement for the SAS Viya Job and the SAS Viya Job Execution. The library is tool which can be used to reduce redundant code in multiple applications and hides the relative complexity of working with the SAS REST APIs. Based on my own experience, you often end-up rewriting similar code to call REST APIs for authentication, to start a Compute Server session, to retrieve a list of libraries, tables, columns, values, …
In addition, if you are new to SAS REST APIs, you might find difficult to interact with them as you are maybe not familiar with the SAS Viya architecture. The wrappers are there to help you and hide a bit of the complexity behind classes with methods which will allow you to be more productive.
The wrappers are made available as classes which can be imported into your web page from a CDN link or into your Node based application through npm install and traditional import statement.
The npm package can be found here. The CDN link is this. And the GIT repository is available here.
The APICall class
At the heart of the library, you have the APICall class. When instantiated, the class can execute calls to a specific REST API endpoint. When you create a new object based on it, you need to pass a few parameters:
- {string} baseURL - The SAS Viya server.
- {Link} link - A link object that contains the method, rel, and other required information.
- {Headers} headers - The headers to include in the request.
- {string} data - The data to include in the request body.
- {URLSearchParams} urlSearchParams - The URL search parameters to include in the request.
The
baseURL contains the URL of the SAS Viya environment. For example:
https://server.demo.sas.com
The
link is an object which provides information about the API endpoint that you are calling. It should contain information like the HTTP method, the HREF of the endpoint, the type of content that is expected. This information is used to build the HTTP request and interact with the endpoint.
If you are familiar with JavaScript/TypeScript, the
headers and the
URLSearchParams are instances of
Headers and
URLSearchParams.
The
data parameter should be a string resulting from JSON.stringify() function. It used as the body of the HTTP request. Internally, the class will check if the user is authenticated before any API call. It will also handle the CSRF token which is required for most POST method calls to the REST APIs. The methods to authenticate and handle the CSRF token are private to the class instance. This means you can't use the method from the created object. The only methods you can call after creating an APICall object are the
execute and
logout methods . You can of course interact with the object properties using the dot notation. The code for this class is available
here.
The ComputeSession class
This wrapper class uses the APICall class to perform different tasks through public methods like:
- getComputeContexts()
- getLibraries({outputType: OutputType = 'data', searchParams: URLSearchParams} )
- getTables( {libraryName: string, outputType: OutputType = 'data', searchParams: URLSearchParams} )
- getColumns( {libraryName: string, tableName: string, outputType: OutputType = 'data', searchParams: URLSearchParams})
- getValues( {libraryName: string, tableName: string, columnName: string, filters?: { column: string; value: string }[], searchParams: URLSearchParams} )
- executeCode( code: string[], resultName: string )
- deleteSession()
Each method can be called directly after instantiating the class like this:
const computeSession = await ComputeSession.init({
baseURL: 'https://server.demo.sas.com',
contextName: 'SAS Job Execution compute context'
})
As you can see, we are passing the SAS Viya Server name but also the compute context we want to use. If you don’t know which compute context should be used or you want to leave the choice to the end-user, you can use the
getComputeContexts method. This will provide a list of the compute server contexts you have access to. If you want to reuse an authentication instance which created earlier with sas-auth-browser, you can reuse that instance and pass it as the third parameter when you instantiate the object. If you don’t have an instance, you will automatically be prompted to enter a user name and password using SAS Logon.
Most of the method names are meaningful enough not be described one by one. As you can see in most of the calls, the
OutputType is preset to ‘data’. Using the
OutputType as ‘data’ tells the method that data should be returned as a JSON object which can be consumed to display data in the HTML page. The other option is to set the
OutputType to ‘api’. In that case, the method will return a JSON object which contains information which can then be passed to the APICall as a Link. Using that technique, you can extend the functionalities of the ComputeSession class to give more options to the users like registering or deleting tables, libraries, … These functionalities are not implemented in the current release of the package as the main intent is to consume data from SAS Viya Compute Server.
You should also be aware that the
deleteSession . The
deleteSession will stop the current compute context session, but will keep the user logged in. This way, a new compute session can be created using the already logged in user. Deleting a session is a good practice to reduce cloud usage and costs. Note that it also possible for administrators to limit the number of compute server sessions for a user. This means that if you don’t close your sessions, you may end up in a situation where the user is not allowed to start a new session until a previous one expires.
The code for this class can be found
here.
Conclusion
At this point, you should have a better understanding about the usage of the SAS Viya API Wrappers for JavaScript. You can even extend the functionalities by cloning the repository and adding your own methods.
For more information about the SAS Viya REST APIs, please refer to SAS for Developers.
Articles in this series are:
SAS Viya API Wrappers for JS – Integrating SAS Compute Server into a custom web application made eas...(this article)
SAS Viya API Wrappers for JS – Building dynamic prompts for SAS Viya Jobs
SAS Viya API Wrappers for JS – Building advanced dynamic prompts for SAS Viya Jobs
SAS Viya API Wrappers for JS – Building a Data Filtering and Display Application with React
Find more articles from SAS Global Enablement and Learning here.
