@@ -164,14 +164,14 @@ under the identity in the JES context. If useComputeApi is n
triggered using the APIs instead of the Job Execution Web Service broker.
+
All authentication from the adapter is done against SASLogon. There are two approaches that can be taken, which are configured using the loginMechanism attribute of the sasJs config object (above):
+
All authentication from the adapter is done against SASLogon. There are two approaches that can be taken, which are configured using the loginMechanism attribute of the sasJs config object (above):
-
loginMechanism:'Redirected' - this approach enables authentication through a SASLogon window, supporting complex authentication flows (such as 2FA) and avoids the need to handle passwords in the application itself. The styling of the window can be modified using CSS.
-
loginMechanism:'Default' - this approach requires that the username and password are captured, and used within the .login() method. This can be helpful for development, or automated testing.
+
loginMechanism:'Redirected' - this approach enables authentication through a SASLogon window, supporting complex authentication flows (such as 2FA) and avoids the need to handle passwords in the application itself. The styling of the window can be modified using CSS.
+
loginMechanism:'Default' - this approach requires that the username and password are captured, and used within the .login() method. This can be helpful for development, or automated testing.
Sample code for logging in with the Default approach:
A simple request can be sent to SAS in the following fashion:
-
sasJs.request("/path/to/my/service", dataObject) .then((response) => { // all tables are in the response object, eg: console.log(response.tablewith2cols1row[0].COL1.value) })
+
sasJs.request('/path/to/my/service', dataObject).then((response) => { // all tables are in the response object, eg: console.log(response.tablewith2cols1row[0].COL1.value) })
We supply the path to the SAS service, and a data object.
-
If the path starts with a / then it should be a full path to the service. If there is no leading / then it is relative to the appLoc.
+
If the path starts with a / then it should be a full path to the service. If there is no leading / then it is relative to the appLoc.
The data object can be null (for services with no input), or can contain one or more "tables" in the following format:
Validation is also performed on the values. The following combinations will throw errors:
+
Validation is also performed on the values. The following combinations will throw errors:
@@ -200,7 +199,7 @@
1.1, '.', 0
-
Error: mixed types. For regular nulls, use null
+
Error: mixed types. For regular nulls, use null
@@ -213,13 +212,13 @@
A numeric column containing only special missing values (is considered character)
To cater for these scenarios, an optional array of formats can be passed along with the data to ensure that SAS will read them in correctly.
-
To understand these formats, it should be noted that the JSON data is NOT passed directly (as JSON) to SAS. It is first converted into CSV, and the header row is actually an infile statement in disguise. It looks a bit like this:
+
To understand these formats, it should be noted that the JSON data is NOT passed directly (as JSON) to SAS. It is first converted into CSV, and the header row is actually an infile statement in disguise. It looks a bit like this:
It is not necessary to provide formats for ALL the columns, only the ones that need to be overridden.
@@ -230,11 +229,11 @@ ABCD,X,.
The following snippet shows the process of SAS tables arriving / leaving:
/* convert frontend input tables from into SASWORK datasets */ %webout(FETCH)
/* some sas code */ data a b c; set from js; run;
%webout(OPEN) /* Open the JSON to be returned */ %webout(OBJ,a) /* Rows in table `a` are objects (easy to use) */ %webout(ARR,b) /* Rows in table `b` are arrays (compact) */ %webout(OBJ,c,fmt=N) /* Table `c` is sent unformatted (raw) */ %webout(OBJ,c,dslabel=d) /* Rename table as `d` in output JSON */ %webout(OBJ,c,dslabel=e, maxobs=10) /* send only 10 rows back */ %webout(CLOSE) /* Close the JSON and add default variables */
-
By default, special SAS numeric missings (_a-Z) are converted to null in the JSON. If you'd like to preserve these, use the missing=STRING option as follows:
+
By default, special SAS numeric missings (_a-Z) are converted to null in the JSON. If you'd like to preserve these, use the missing=STRING option as follows:
%webout(OBJ,a,missing=STRING)
In this case, special missings (such as .a, .b) are converted to javascript string values ('A', 'B').
-
Where an entire column is made up of special missing numerics, there would be no way to distinguish it from a single-character column by looking at the values. To cater for this scenario, it is possible to export the variable types (and other attributes such as label and format) by adding a showmeta param to the webout() macro as follows:
+
Where an entire column is made up of special missing numerics, there would be no way to distinguish it from a single-character column by looking at the values. To cater for this scenario, it is possible to export the variable types (and other attributes such as label and format) by adding a showmeta param to the webout() macro as follows:
%webout(OBJ,a,missing=STRING,showmeta=YES)
The %webout() macro itself is just a wrapper for the mp_jsonout macro.
Configuration on the client side involves passing an object on startup, which can also be passed with each request. Technical documentation on the SASjsConfig class is available here. The main config items are:
+
Configuration on the client side involves passing an object on startup, which can also be passed with each request. Technical documentation on the SASjsConfig class is available here. The main config items are:
appLoc - this is the folder (eg in metadata or SAS Drive) under which the SAS services are created.
-
serverType - either SAS9, SASVIYA or SASJS. The SASJS server type is for use with sasjs/server.
+
serverType - either SAS9, SASVIYA or SASJS. The SASJS server type is for use with sasjs/server.
serverUrl - the location (including http protocol and port) of the SAS Server. Can be omitted, eg if serving directly from the SAS Web Server, or in streaming mode.
debug - if true then SAS Logs and extra debug information is returned.
verbose - optional, if true then a summary of every HTTP response is logged.
-
loginMechanism - either Default or Redirected. See SAS Logon section.
-
useComputeApi - Only relevant when the serverType is SASVIYA. If true the Compute API is used. If false the JES API is used. If null or undefined the Web approach is used.
-
contextName - Compute context on which the requests will be called. If missing or not provided, defaults to Job Execution Compute context.
-
requestHistoryLimit - Request history limit. Increasing this limit may affect browser performance, especially with debug (logs) enabled. Default is 10.
+
loginMechanism - either Default or Redirected. See SAS Logon section.
+
useComputeApi - Only relevant when the serverType is SASVIYA. If true the Compute API is used. If false the JES API is used. If null or undefined the Web approach is used.
+
contextName - Compute context on which the requests will be called. If missing or not provided, defaults to Job Execution Compute context.
+
requestHistoryLimit - Request history limit. Increasing this limit may affect browser performance, especially with debug (logs) enabled. Default is 10.
-
The adapter supports a number of approaches for interfacing with Viya (serverType is SASVIYA). For maximum performance, be sure to configure your compute context with reuseServerProcesses as true and a system account in runServerAs. This functionality is available since Viya 3.5. This configuration is supported when creating contexts using the CLI.
+
The adapter supports a number of approaches for interfacing with Viya (serverType is SASVIYA). For maximum performance, be sure to configure your compute context with reuseServerProcesses as true and a system account in runServerAs. This functionality is available since Viya 3.5. This configuration is supported when creating contexts using the CLI.
In this setup, all requests are routed through the JES web app, at YOURSERVER/SASJobExecution?_program=/your/program. This is the most reliable method, and also the slowest. One request is made to the JES app, and remaining requests (getting job uri, session spawning, passing parameters, running the program, fetching the log) are handled by the SAS server inside the JES app.
+
In this setup, all requests are routed through the JES web app, at YOURSERVER/SASJobExecution?_program=/your/program. This is the most reliable method, and also the slowest. One request is made to the JES app, and remaining requests (getting job uri, session spawning, passing parameters, running the program, fetching the log) are handled by the SAS server inside the JES app.
Here we are running Jobs using the Job Execution Service except this time we are making the requests directly using the REST API instead of through the JES Web App. This is helpful when we need to call web services outside of a browser (eg with the SASjs CLI or other commandline tools). To save one network request, the adapter prefetches the JOB URIs and passes them in the __job parameter. Depending on your network bandwidth, it may or may not be faster than the JES Web approach.
+
Here we are running Jobs using the Job Execution Service except this time we are making the requests directly using the REST API instead of through the JES Web App. This is helpful when we need to call web services outside of a browser (eg with the SASjs CLI or other commandline tools). To save one network request, the adapter prefetches the JOB URIs and passes them in the __job parameter. Depending on your network bandwidth, it may or may not be faster than the JES Web approach.
This approach (useComputeApi: false) also ensures that jobs are displayed in Environment Manager.
This approach is by far the fastest, as a result of the optimisations we have built into the adapter. With this configuration, in the first sasjs request, we take a URI map of the services in the target folder, and create a session manager. This manager will spawn a additional session every time a request is made. Subsequent requests will use the existing 'hot' session, if it exists. Sessions are always deleted after every use, which actually makes this less resource intensive than a typical JES web app, in which all sessions are kept alive by default for 15 minutes.
+
This approach is by far the fastest, as a result of the optimisations we have built into the adapter. With this configuration, in the first sasjs request, we take a URI map of the services in the target folder, and create a session manager. This manager will spawn a additional session every time a request is made. Subsequent requests will use the existing 'hot' session, if it exists. Sessions are always deleted after every use, which actually makes this less resource intensive than a typical JES web app, in which all sessions are kept alive by default for 15 minutes.
With this approach (useComputeApi: true), the requests/logs will not appear in the list in Environment manager.
Set to
trueto enable additional debugging.