Building and Deploying Web Apps With SASjs CLI
Abstract
In recent years, JavaScript has become the most popular programming language for web development. The rise of NodeJS has led to JavaScript being widely adopted for building both server-side and client-side apps. Frameworks such as React and Angular have become the de facto standard for building modern, sophisticated web apps. While SAS has traditionally not been known as a platform for web development, there is great value in simplifying the process of building web apps on top of the valuable data contained within SAS platforms.
It would lower the barrier for entry if web developers could focus on implementing the app while having an easy way to access and manipulate SAS data. Another pain point when developing apps on top of SAS is deployment - deploying apps to a SAS web server usually requires elevated access levels and is not a simple process.
A set of tools to automate building and deploying apps would help improve the adoption of SAS as a web app platform. The SASjs framework was conceptualised with the vision of bridging the gap between SAS and modern web applications. It includes an adapter that manages connection and communication with SAS servers, a library of SAS macros and a command-line interface (CLI) that provides the ability to create, build and deploy web apps onto SAS servers.
This paper will demonstrate how easy it is to generate, build and deploy a React app using the SASjs CLI.
Watch the presentation
Watch Building and Deploying Web Apps With SASjs CLI as presented by the author on the SAS Users YouTube channel.
SAS and Modern web development workflows
Workflows for web developers have also changed over time in line with the evolution of JavaScript. Frontend development these days typically involves use of a command-line tool to scaffold out projects, manage configuration and create new components. Tools such as the Angular CLI and create-react-app provide opinionated workflows to automate such tasks. This means that you can have a codebase up and running for a new project in a matter of minutes, making for much more accelerated development.
CI/CD, DevOps and automation are a key aspect of the modern web developer's workflow. Most web projects use Git for version control, and often use one of many available CI/CD providers to implement quality checks, coding standards, testing and automated deployments.
When I first started developing SAS-based web apps, I was struck by the differences in workflow between myself, a JavaScript/web dev, and my fellow SAS devs. There were a few key challenges to overcome - firstly, there was a shift in mindset to thinking about data in terms of tables rather than JSON objects. In addition, the differences between SAS9 and SAS Viya were a pain point when building apps that were required to work across server types. While I was using an IDE like Visual Studio Code for my development work, most SAS development is done in SAS Studio, which is browser-based.
The idea of addressing these challenges and bridging the gap between SAS and modern web development prompted my colleagues and I to come up with the SASjs framework.
The sasjs framework
SASjs started out as a set of tools to aid rapid development of web apps on SAS. The first components of SASjs were the SASjs Core library which included a number of reusable macros, and SASjs Adapter which provided a means to connect and communicate with SAS9 and SAS Viya servers.
We quickly realised that in order to truly accelerate the development of SAS web apps, we needed a tool that could help generate new projects, compile, build and deploy them to a SAS server. We then built SASjs CLI to be able to do just that, although the project has since expanded with a number of advanced features such as the ability to run flows with multiple SAS jobs against a server, generate project documentation and enforce coding standards.
With these building blocks in place, the framework has seen more growth with projects using the underlying infrastructure to provide useful functionality. As a result, SASjs now features a more full-fledged suite of DevOps tooling and a number of other components that aim to improve the developer experience when working with SAS. We have built a VS Code Extension that provides SAS syntax highlighting, code issue detection and the ability to execute code from your SAS files and inspect logs and results within VS Code. We have also built a SAS Linter that detects code smells such as encoded passwords, missing macro names in %mend statements and nested macro definitions in your SAS code. In addition, there are a number of seed apps available for different frontend frameworks to kickstart your SAS apps journey.
In the following sections, we will focus more closely on the web app development aspects of SASjs. More information on DevOps with SASjs can be found in my colleague @AllanBowe's paper here.
GETTING STARTED
SASjs CLI uses NodeJS as the runtime, and Node Package Manager (NPM) to manage dependencies.
NPM is automatically installed along with NodeJS. To make sure you have it installed correctly, you can run:
npm -vThis should display a version number if it is installed correctly. If not, it is likely that the NodeJS executable is missing from the PATH variable. You can fix this by restarting your terminal, or otherwise manually adding the location of the NodeJS executable to your PATH variable.
If you're on Windows, using Git Bash or the Linux subsystem is highly recommended, although not strictly necessary.
You can also use a text editor/IDE of your choice, however we recommend VS Code since it allows use of the SASjs extension.
Once you have these set up, you are ready to install the SASjs CLI. You can run:
npm install -g @sasjs/cli
This will install the SASjs CLI globally on your machine, which lets you run sasjs commands from any directory. You can verify this by running:
sasjs vThis will return the version number.
Now that we have the CLI, let's get started with building our web app!
Scaffolding a REACT APP
You can simply run the following command to create a brand new React app with SASjs built in.
sasjs create <app-name> -t react
Note that you can also scaffold out Angular, vanilla JS and SAS-only apps using the different options documented here.
When the command has completed, there'll be a React app with a couple of SAS services available in a folder with the specified app name.
APP Structure
The app contains a top-level sasjs folder, which contains all the SAS-related configuration and the SAS code.
The sasjsconfig.json file contains all the required configuration to connect and interface with your SAS server via the app.
The key property in this file is targets, which is a set of server configurations. This can be useful when your app needs to be deployed to multiple different server types, or if you use multiple environments. Each target specifies at a minimum a server URL, server type (either SAS9 or Viya) and an appLoc which is the location of your app on SAS Drive. The app comes with two default targets - one for Viya and one for SAS 9. There are a number of other options that can be configured within the file, and a detailed explanation of these can be found here.
Apart from the config file, the sasjs folder also contains a couple of SAS 'services' - SAS jobs with a Doxygen header block describing them. The header block specifies any dependencies for the service, such as macros from the SASjs core library. It is also used to automatically generate documentation using sasjs doc.
The appinit service fetches a list of areas from the demo springs database. This is used to populate a dropdown in the app.
/**
@file appinit.sas
@brief Initialisation service - runs on app startup
@details This is always the first service called when the app is opened.
<h4> SAS Macros </h4>
**/
proc sql;
create table areas as select distinct area
from sashelp.springs;
%webout(OPEN)
%webout(OBJ,areas)
%webout(CLOSE)
The getdata service fetches information about springs in a given area. This is used to fetch and display information when an area is selected from the dropdown.
/**
@file getdata.sas
@brief Get Data service - runs on app startup
@details This is always the first service called when the app is opened.
<h4> SAS Macros </h4>
**/
%webout(FETCH)
proc sql;
create table springs as select * from sashelp.springs
where area in (select area from areas);
%webout(OPEN)
%webout(OBJ,springs)
%webout(CLOSE)
Homepage 
Springs display
This app also includes a SASContext which handles all the communication with your SAS server via the SASjs Adapter. The SASContext specifies the connection parameters for your SAS server, and comes with helper methods to log in, log out and fetch data.
Deploying The App
Authentication
Now that we have the app codebase ready, let us try to deploy it to a SAS server.
The SASjs CLI can handle deployments to both SAS9 and Viya servers - it uses the REST API for Viya and falls back to an SSH-based approach for SAS9, which will require privileged access.
In this section, we will deploy our app to a SAS Viya server. To do so, we must first authenticate against the server, i.e the viya target in our SASjs config file.
This can be done using the following CLI command:
sasjs add cred -t viyaThis will bring up a prompt to enter a valid Client ID and Secret (which can be obtained from your SAS administrator). Once those are entered, a link to log into SAS via the browser is displayed. On successful login, the browser displays a one-time code which needs to be pasted back into the terminal. We then use the one-time code along with the client ID and secret to obtain access and refresh tokens. These are saved in a local .env file and attached to the request headers when interacting with the Viya REST API.
Deploying SAS Components
Once authenticated, we can deploy our SAS app using the following command:
sasjs cbd -t viyaThe cbd in the command above stands for compile, build and deploy. Let us now understand what each of these steps means.
Compilation is the process of running through each defined service/job, recursively fetching its dependencies (specified in the header block) and appending them onto the output file. This can be run independently using the command:
sasjs compile -t viya
Next in line is the build step - at this point, the compiled services are combined into one single file that's ready for deployment. The name of this file is configurable in the SASjs config file. For Viya targets, this step also generates a JSON file describing the different folders and files to be deployed. This is called a service pack. This command can also be run independently of the compile and deploy steps using:
sasjs build -t viya
Now the code is ready for deployment. The deploy step uses the Viya REST API to create the files and folders specified in the service pack JSON. Once this is done, all the SAS components of our app are deployed and ready to use.
Deploying Web App
Now that we have all our backend components deployed, we can switch focus to the React frontend app.
Before we can deploy, we will need to first build the app using the provided script.
npm run build
There are two ways to deploy this app to a SAS server - one that requires SSH access and one that doesn't.
Deployment using rsync
There is a deploy NPM script provided with the app, which uses rsync to transfer the built app files to a web server. This requires the SSH_ACCOUNT and DEPLOY_PATH variables to be populated. You can populate the variables and run the command like so:
SSH_ACCOUNT=me@myserver.com DEPLOY_PATH=/var/www/html/myapp npm run deploy
When done, the app will be available on <your server URL>/myapp.
This approach does, however, require SSH access to the server.
Streaming App with SASjs CLI
If you do not have SSH access, there is another way to deploy your app - converting it into a SAS service that streams the HTML, CSS and JavaScript content straight to the browser.
To use this approach, we need to provide a streamConfig property within the target in the SASjs config file. This will be an object with the following shape:
"streamConfig": {
"assetPaths": [],
"streamWeb": true,
"streamWebFolder": "webv",
"webSourcePath": "build",
"streamServiceName": "myStreamApp"
}When the streamWeb flag is set to true, sasjs build will create a service with the given stream service name. This service will contain SAS code that will stream the content of the built web app (previously built using npm run build).
We can use the usual sasjs deploy mechanism to deploy this service and all the others.
Once the deployment has completed, your app will be available on <your server URL>/SASJobExecution?_PROGRAM=<your appLoc>/services/myStreamApp.
THE FUTURE
Although SASjs started out mainly as a way to ease web app development on SAS, it has now evolved into a full suite of tooling that supports the entire lifecycle of SAS development. We now have tools that let SAS developers create, build, deploy and maintain their SAS code.
Our next important milestones are:
- Full support for SAS9, potentially using the SAS9 REST API.
- Support for Base SAS via a NodeJS backend component.
Conclusion
SASjs is a fully open source (MIT) and community-driven project. We have been primarily sponsored by Analytium, but are looking for additional sponsors and collaborators. We'd also love to hear your feedback on SASjs and would like to work with you to build the most useful features for the community. If you'd like to contribute or have any feedback, please get in touch!
Contact information
Krishna can be contacted on:
- Email: krishna.acondy@analytium.co.uk
- LinkedIn: https://www.linkedin.com/in/krishna-acondy/
- GitHub: https://github.com/krishna-acondy
Useful Links
- SASjs Main Site: https://sasjs.io
- SASjs Core docs: https://core.sasjs.io
- SASjs CLI docs: https://cli.sasjs.io
- SASjs Adapter docs: https://adapter.sasjs.io
- NodeJS Website: https://nodejs.org/
- VS Code Website: https://code.visualstudio.com/
Click image to register for webinar
Classroom Training Available!
Select SAS Training centers are offering in-person courses. View upcoming courses for:
