sasjs/adapter
1
0
Fork 0
mirror of https://github.com/sasjs/adapter.git synced 2025-12-10 17:04:36 +00:00
Code Issues Projects Releases Wiki Activity
Files
c498783d76561693445f932071e96a814b42f20e
adapter/docs/index.html
Sabir Hassan d7330617df chore: update docs
2022-09-20 22:02:15 +05:00

337 lines
38 KiB
HTML
Raw Blame History

<!DOCTYPE html><html class="default" lang="en"><head><meta charSet="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@sasjs/adapter</title><meta name="description" content="Documentation for @sasjs/adapter"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script async src="assets/search.js" id="search-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os"</script><header class="tsd-page-toolbar">
<div class="tsd-toolbar-contents container">
<div class="table-cell" id="tsd-search" data-base=".">
<div class="field"><label for="tsd-search-field" class="tsd-widget search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><path d="M15.7824 13.833L12.6666 10.7177C12.5259 10.5771 12.3353 10.499 12.1353 10.499H11.6259C12.4884 9.39596 13.001 8.00859 13.001 6.49937C13.001 2.90909 10.0914 0 6.50048 0C2.90959 0 0 2.90909 0 6.49937C0 10.0896 2.90959 12.9987 6.50048 12.9987C8.00996 12.9987 9.39756 12.4863 10.5008 11.6239V12.1332C10.5008 12.3332 10.5789 12.5238 10.7195 12.6644L13.8354 15.7797C14.1292 16.0734 14.6042 16.0734 14.8948 15.7797L15.7793 14.8954C16.0731 14.6017 16.0731 14.1267 15.7824 13.833ZM6.50048 10.499C4.29094 10.499 2.50018 8.71165 2.50018 6.49937C2.50018 4.29021 4.28781 2.49976 6.50048 2.49976C8.71001 2.49976 10.5008 4.28708 10.5008 6.49937C10.5008 8.70852 8.71314 10.499 6.50048 10.499Z" fill="var(--color-text)"></path></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div>
<ul class="results">
<li class="state loading">Preparing search index...</li>
<li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">@sasjs/adapter</a></div>
<div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><rect x="1" y="3" width="14" height="2" fill="var(--color-text)"></rect><rect x="1" y="7" width="14" height="2" fill="var(--color-text)"></rect><rect x="1" y="11" width="14" height="2" fill="var(--color-text)"></rect></svg></a></div></div></header>
<div class="container container-main">
<div class="col-8 col-content">
<div class="tsd-page-title">
<h2>@sasjs/adapter</h2></div>
<div class="tsd-panel tsd-typography">
<a href="#sasjsadapter" id="sasjsadapter" style="color: inherit; text-decoration: none;">
<h1>@sasjs/adapter</h1>
</a>
<p><a href="http://npmjs.org/package/@sasjs/adapter"><img src="https://img.shields.io/npm/v/@sasjs/adapter.svg" alt="npm package"></a>
<a href="https://github.com/sasjs/adapter/blob/main/.github/workflows/build.yml"><img src="https://github.com/sasjs/adapter/actions/workflows/build.yml/badge.svg" alt="Github Workflow"></a>
<a href=""><img src="https://img.shields.io/npm/dt/@sasjs/adapter" alt="npm"></a>
<img src="https://img.shields.io/snyk/vulnerabilities/npm/@sasjs/adapter" alt="Snyk Vulnerabilities for npm package">
<a href="/LICENSE"><img src="https://img.shields.io/apm/l/atomic-design-ui.svg" alt="License"></a>
<img src="https://img.shields.io/github/languages/top/sasjs/adapter" alt="GitHub top language">
<img src="https://img.shields.io/github/issues/sasjs/adapter" alt="GitHub issues">
<a href="https://gitpod.io/#https://github.com/sasjs/adapter"><img src="https://img.shields.io/badge/Gitpod-ready--to--code-908a85?logo=gitpod" alt="Gitpod ready-to-code"></a></p>
<p>SASjs is a open-source framework for building Web Apps on SAS® platforms. You can use as much or as little of it as you like. This repository contains the JS adapter, the part that handles the to/from SAS communication on the client side. There are 3 ways to install it:</p>
<p>1 - <code>npm install @sasjs/adapter</code> - for use in a nodeJS project (recommended)</p>
<p>2 - <a href="https://cdn.jsdelivr.net/npm/@sasjs/adapter@3/index.min.js">Download</a> and use a copy of the latest JS file</p>
<p>3 - Reference directly from the CDN - in which case click <a href="https://www.jsdelivr.com/package/npm/@sasjs/adapter?tab=collection">here</a> and select &quot;SRI&quot; to get the script tag with the integrity hash.</p>
<p>If you are short on time and just need to build an app quickly, then check out <a href="https://vimeo.com/393161794">this video</a> and the <a href="https://github.com/sasjs/react-seed-app">react-seed-app</a> which provides some boilerplate.</p>
<p>For more information on building web apps with SAS, check out <a href="https://sasjs.io">sasjs.io</a></p>
<a href="#none-of-this-makes-sense-how-do-i-build-an-app-with-it" id="none-of-this-makes-sense-how-do-i-build-an-app-with-it" style="color: inherit; text-decoration: none;">
<h2>None of this makes sense. How do I build an app with it?</h2>
</a>
<p>Ok ok. Deploy this <a href="https://raw.githubusercontent.com/sasjs/adapter/master/example.html">example.html</a> file to your web server, and update <code>servertype</code> to <code>SAS9</code>, <code>SASVIYA</code>, or <code>SASJS</code> depending on your backend.</p>
<p>The backend part can be deployed as follows:</p>
<pre><code class="language-sas"><span class="hl-0">%let appLoc=/Public/app/readme; /* Metadata or Viya Folder per SASjs config */</span><br/><span class="hl-0">filename mc url &quot;https://raw.githubusercontent.com/sasjs/core/main/all.sas&quot;;</span><br/><span class="hl-0">%inc mc; /* compile macros (can also be downloaded &amp; compiled seperately) */</span><br/><span class="hl-0">filename ft15f001 temp;</span><br/><span class="hl-0">parmcards4;</span><br/><span class="hl-0"> %webout(FETCH) /* receive all data as SAS datasets */</span><br/><span class="hl-0"> proc sql;</span><br/><span class="hl-0"> create table areas as select make,mean(invoice) as avprice</span><br/><span class="hl-0"> from sashelp.cars</span><br/><span class="hl-0"> where type in (select type from work.fromjs)</span><br/><span class="hl-0"> group by 1;</span><br/><span class="hl-0"> %webout(OPEN)</span><br/><span class="hl-0"> %webout(OBJ,areas)</span><br/><span class="hl-0"> %webout(CLOSE)</span><br/><span class="hl-0">;;;;</span><br/><span class="hl-0">%mx_createwebservice(path=&amp;appLoc/common,name=getdata)</span>
</code></pre>
<p>You now have a simple web app with a backend service!</p>
<a href="#detailed-overview" id="detailed-overview" style="color: inherit; text-decoration: none;">
<h2>Detailed Overview</h2>
</a>
<p>The SASjs adapter is a JS library and a set of SAS Macros that handle the communication between the frontend app and backend SAS services.</p>
<p>There are three parts to consider:</p>
<ol>
<li>JS request / response</li>
<li>SAS inputs / outputs</li>
<li>Configuration</li>
</ol>
<a href="#js-request--response" id="js-request--response" style="color: inherit; text-decoration: none;">
<h3>JS Request / Response</h3>
</a>
<p>To install the library you can simply run <code>npm i @sasjs/adapter</code> or include a <code>&lt;script&gt;</code> tag with a reference to our <a href="https://www.jsdelivr.com/package/npm/@sasjs/adapter">CDN</a>.</p>
<p>Full technical documentation is available <a href="https://adapter.sasjs.io">here</a>. The main parts are:</p>
<a href="#instantiation" id="instantiation" style="color: inherit; text-decoration: none;">
<h3>Instantiation</h3>
</a>
<p>The following code will instantiate an instance of the adapter:</p>
<pre><code class="language-javascript"><span class="hl-1">let</span><span class="hl-0"> </span><span class="hl-2">sasJs</span><span class="hl-0"> = </span><span class="hl-1">new</span><span class="hl-0"> </span><span class="hl-2">SASjs</span><span class="hl-0">.</span><span class="hl-3">default</span><span class="hl-0">(</span><br/><span class="hl-0"> {</span><br/><span class="hl-0"> </span><span class="hl-2">appLoc:</span><span class="hl-0"> </span><span class="hl-4">&quot;/Your/SAS/Folder&quot;</span><span class="hl-0">,</span><br/><span class="hl-0"> </span><span class="hl-2">serverType:</span><span class="hl-4">&quot;SAS9&quot;</span><br/><span class="hl-0"> }</span><br/><span class="hl-0">);</span>
</code></pre>
<p>If you&#39;ve installed it via NPM, you can import it as a default import like so:</p>
<pre><code class="language-js"><span class="hl-0"> </span><span class="hl-5">import</span><span class="hl-0"> </span><span class="hl-2">SASjs</span><span class="hl-0"> </span><span class="hl-5">from</span><span class="hl-0"> </span><span class="hl-4">&#39;@sasjs/adapter&#39;</span><span class="hl-0">;</span>
</code></pre>
<p>You can then instantiate it with:</p>
<pre><code class="language-js"><span class="hl-1">const</span><span class="hl-0"> </span><span class="hl-6">sasJs</span><span class="hl-0"> = </span><span class="hl-1">new</span><span class="hl-0"> </span><span class="hl-3">SASjs</span><span class="hl-0">({your </span><span class="hl-2">config</span><span class="hl-0">})</span>
</code></pre>
<p>More on the config later.</p>
<a href="#sas-logon" id="sas-logon" style="color: inherit; text-decoration: none;">
<h3>SAS Logon</h3>
</a>
<p>All authentication from the adapter is done against SASLogon. There are two approaches that can be taken, which are configured using the <code>loginMechanism</code> attribute of the sasJs config object (above):</p>
<ul>
<li><code>loginMechanism:&#39;Redirected&#39;</code> - 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.</li>
<li><code>loginMechanism:&#39;Default&#39;</code> - this approach requires that the username and password are captured, and used within the <code>.login()</code> method. This can be helpful for development, or automated testing.</li>
</ul>
<p>Sample code for logging in with the <code>Default</code> approach:</p>
<pre><code class="language-javascript"><span class="hl-2">sasJs</span><span class="hl-0">.</span><span class="hl-3">logIn</span><span class="hl-0">(</span><span class="hl-4">&#39;USERNAME&#39;</span><span class="hl-0">,</span><span class="hl-4">&#39;PASSWORD&#39;</span><br/><span class="hl-0"> ).</span><span class="hl-3">then</span><span class="hl-0">((</span><span class="hl-2">response</span><span class="hl-0">) </span><span class="hl-1">=&gt;</span><span class="hl-0"> {</span><br/><span class="hl-0"> </span><span class="hl-5">if</span><span class="hl-0"> (</span><span class="hl-2">response</span><span class="hl-0">.</span><span class="hl-2">isLoggedIn</span><span class="hl-0"> === </span><span class="hl-1">true</span><span class="hl-0">) {</span><br/><span class="hl-0"> </span><span class="hl-2">console</span><span class="hl-0">.</span><span class="hl-3">log</span><span class="hl-0">(</span><span class="hl-4">&#39;do stuff&#39;</span><span class="hl-0">)</span><br/><span class="hl-0"> } </span><span class="hl-5">else</span><span class="hl-0"> {</span><br/><span class="hl-0"> </span><span class="hl-2">console</span><span class="hl-0">.</span><span class="hl-3">log</span><span class="hl-0">(</span><span class="hl-4">&#39;do other stuff&#39;</span><span class="hl-0">)</span><br/><span class="hl-0"> }</span><br/><span class="hl-0">}</span>
</code></pre>
<p>More examples of using authentication, and more, can be found in the <a href="https://github.com/search?q=topic%3Asasjs-app+org%3Asasjs+fork%3Atrue">SASjs Seed Apps</a> on github.</p>
<a href="#request--response" id="request--response" style="color: inherit; text-decoration: none;">
<h3>Request / Response</h3>
</a>
<p>A simple request can be sent to SAS in the following fashion:</p>
<pre><code class="language-javascript"><span class="hl-2">sasJs</span><span class="hl-0">.</span><span class="hl-3">request</span><span class="hl-0">(</span><span class="hl-4">&quot;/path/to/my/service&quot;</span><span class="hl-0">, </span><span class="hl-2">dataObject</span><span class="hl-0">)</span><br/><span class="hl-0"> .</span><span class="hl-3">then</span><span class="hl-0">((</span><span class="hl-2">response</span><span class="hl-0">) </span><span class="hl-1">=&gt;</span><span class="hl-0"> {</span><br/><span class="hl-0"> </span><span class="hl-7">// all tables are in the response object, eg:</span><br/><span class="hl-0"> </span><span class="hl-2">console</span><span class="hl-0">.</span><span class="hl-3">log</span><span class="hl-0">(</span><span class="hl-2">response</span><span class="hl-0">.</span><span class="hl-2">tablewith2cols1row</span><span class="hl-0">[</span><span class="hl-8">0</span><span class="hl-0">].</span><span class="hl-6">COL1</span><span class="hl-0">.</span><span class="hl-2">value</span><span class="hl-0">)</span><br/><span class="hl-0"> })</span>
</code></pre>
<p>We supply the path to the SAS service, and a data object.</p>
<p>If the path starts with a <code>/</code> then it should be a full path to the service. If there is no leading <code>/</code> then it is relative to the <code>appLoc</code>.</p>
<p>The data object can be null (for services with no input), or can contain one or more &quot;tables&quot; in the following format:</p>
<pre><code class="language-javascript"><span class="hl-1">let</span><span class="hl-0"> </span><span class="hl-2">dataObject</span><span class="hl-0">={</span><br/><span class="hl-0"> </span><span class="hl-4">&quot;tablewith2cols1row&quot;</span><span class="hl-2">:</span><span class="hl-0"> [{</span><br/><span class="hl-0"> </span><span class="hl-4">&quot;col1&quot;</span><span class="hl-2">:</span><span class="hl-0"> </span><span class="hl-4">&quot;val1&quot;</span><span class="hl-0">,</span><br/><span class="hl-0"> </span><span class="hl-4">&quot;col2&quot;</span><span class="hl-2">:</span><span class="hl-0"> </span><span class="hl-8">42</span><br/><span class="hl-0"> }],</span><br/><span class="hl-0"> </span><span class="hl-4">&quot;tablewith1col2rows&quot;</span><span class="hl-2">:</span><span class="hl-0"> [{</span><br/><span class="hl-0"> </span><span class="hl-4">&quot;col&quot;</span><span class="hl-2">:</span><span class="hl-0"> </span><span class="hl-4">&quot;row1&quot;</span><br/><span class="hl-0"> }, {</span><br/><span class="hl-0"> </span><span class="hl-4">&quot;col&quot;</span><span class="hl-2">:</span><span class="hl-0"> </span><span class="hl-4">&quot;row2&quot;</span><br/><span class="hl-0"> }]</span><br/><span class="hl-0">};</span>
</code></pre>
<p>These tables (<code>tablewith2cols1row</code> and <code>tablewith1col2rows</code>) will be created in SAS WORK after running <code>%webout(FETCH)</code> in your SAS service.</p>
<p>The <code>request()</code> method also has optional parameters such as a config object and a callback login function.</p>
<p>The response object will contain returned tables and columns. Table names are always lowercase, and column names uppercase.</p>
<p>The adapter will also cache the logs (if debug enabled) and even the work tables. For performance, it is best to keep debug mode off.</p>
<a href="#variable-types" id="variable-types" style="color: inherit; text-decoration: none;">
<h3>Variable Types</h3>
</a>
<p>The SAS type (char/numeric) of the values is determined according to a set of rules:</p>
<ul>
<li>If the values are numeric, the SAS type is numeric</li>
<li>If the values are all string, the SAS type is character</li>
<li>If the values contain a single character (a-Z + underscore + .) AND a numeric, then the SAS type is numeric (with special missing values).</li>
<li><code>null</code> is set to either &#39;.&#39; or &#39;&#39; depending on the assigned or derived type per the above rules. If entire column is <code>null</code> then the type will be numeric.</li>
</ul>
<p>The following table illustrates the formats applied to columns under various scenarios:</p>
<table>
<thead>
<tr>
<th>JS Values</th>
<th>SAS Format</th>
</tr>
</thead>
<tbody><tr>
<td>&#39;a&#39;, &#39;a&#39;</td>
<td>$char1.</td>
</tr>
<tr>
<td>0, &#39;_&#39;</td>
<td>best.</td>
</tr>
<tr>
<td>&#39;Z&#39;, 0</td>
<td>best.</td>
</tr>
<tr>
<td>&#39;a&#39;, &#39;aaa&#39;</td>
<td>$char3.</td>
</tr>
<tr>
<td>null, &#39;a&#39;, &#39;aaa&#39;</td>
<td>$char3.</td>
</tr>
<tr>
<td>null, &#39;a&#39;, 0</td>
<td>best.</td>
</tr>
<tr>
<td>null, null</td>
<td>best.</td>
</tr>
<tr>
<td>null, &#39;&#39;</td>
<td>$char1.</td>
</tr>
<tr>
<td>null, &#39;a&#39;</td>
<td>$char1.</td>
</tr>
<tr>
<td>&#39;a&#39;</td>
<td>$char1.</td>
</tr>
<tr>
<td>&#39;a&#39;, null</td>
<td>$char1.</td>
</tr>
<tr>
<td>&#39;a&#39;, null, 0</td>
<td>best.</td>
</tr>
</tbody></table>
<p>Validation is also performed on the values. The following combinations will throw errors:</p>
<table>
<thead>
<tr>
<th>JS Values</th>
<th>SAS Format</th>
</tr>
</thead>
<tbody><tr>
<td>null, &#39;aaaa&#39;, 0</td>
<td>Error: mixed types. &#39;aaaa&#39; is not a special missing value.</td>
</tr>
<tr>
<td>0, &#39;a&#39;, &#39;!&#39;</td>
<td>Error: mixed types. &#39;!&#39; is not a special missing value</td>
</tr>
<tr>
<td>1.1, &#39;.&#39;, 0</td>
<td>Error: mixed types. For regular nulls, use <code>null</code></td>
</tr>
</tbody></table>
<a href="#variable-format-override" id="variable-format-override" style="color: inherit; text-decoration: none;">
<h3>Variable Format Override</h3>
</a>
<p>The auto-detect functionality above is thwarted in the following scenarios:</p>
<ul>
<li>A character column containing only <code>null</code> values (is considered numeric)</li>
<li>A numeric column containing only special missing values (is considered character)</li>
</ul>
<p>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.</p>
<p>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 <code>infile</code> statement in disguise. It looks a bit like this:</p>
<pre><code class="language-csv">CHARVAR1:$char4. CHARVAR2:$char1. NUMVAR:best.
LOAD,,0
ABCD,X,.
</code></pre>
<p>To provide overrides to this header row, the tables object can be constructed as follows (with a leading &#39;$&#39; in the table name):</p>
<pre><code class="language-javascript"><span class="hl-1">let</span><span class="hl-0"> </span><span class="hl-2">specialData</span><span class="hl-0">={</span><br/><span class="hl-0"> </span><span class="hl-4">&quot;tablewith2cols2rows&quot;</span><span class="hl-2">:</span><span class="hl-0"> [</span><br/><span class="hl-0"> {</span><span class="hl-4">&quot;col1&quot;</span><span class="hl-2">:</span><span class="hl-0"> </span><span class="hl-4">&quot;val1&quot;</span><span class="hl-0">,</span><span class="hl-4">&quot;specialMissingsCol&quot;</span><span class="hl-2">:</span><span class="hl-0"> </span><span class="hl-4">&quot;A&quot;</span><span class="hl-0">},</span><br/><span class="hl-0"> {</span><span class="hl-4">&quot;col1&quot;</span><span class="hl-2">:</span><span class="hl-0"> </span><span class="hl-4">&quot;val2&quot;</span><span class="hl-0">,</span><span class="hl-4">&quot;specialMissingsCol&quot;</span><span class="hl-2">:</span><span class="hl-0"> </span><span class="hl-4">&quot;_&quot;</span><span class="hl-0">}</span><br/><span class="hl-0"> ],</span><br/><span class="hl-0"> </span><span class="hl-4">&quot;$tablewith2cols2rows&quot;</span><span class="hl-2">:</span><span class="hl-0">{</span><span class="hl-4">&quot;formats&quot;</span><span class="hl-2">:</span><span class="hl-0">{</span><span class="hl-4">&quot;specialMissingsCol&quot;</span><span class="hl-2">:</span><span class="hl-4">&quot;best.&quot;</span><span class="hl-0">}</span><br/><span class="hl-0"> }</span><br/><span class="hl-0">};</span>
</code></pre>
<p>It is not necessary to provide formats for ALL the columns, only the ones that need to be overridden.</p>
<a href="#sas-inputs--outputs" id="sas-inputs--outputs" style="color: inherit; text-decoration: none;">
<h2>SAS Inputs / Outputs</h2>
</a>
<p>The SAS side is handled by a number of macros in the <a href="https://github.com/sasjs/core">macro core</a> library.</p>
<p>The following snippet shows the process of SAS tables arriving / leaving:</p>
<pre><code class="language-sas"><span class="hl-7">/* convert frontend input tables from into SASWORK datasets */</span><br/><span class="hl-0">%webout(FETCH)</span><br/><br/><span class="hl-7">/* some sas code */</span><br/><span class="hl-0">data a b c;</span><br/><span class="hl-0"> set from js;</span><br/><span class="hl-0">run;</span><br/><br/><span class="hl-0">%webout(OPEN) /* Open the JSON to be returned */</span><br/><span class="hl-0">%webout(OBJ,a) /* Rows in table `a` are objects (easy to use) */</span><br/><span class="hl-0">%webout(ARR,b) /* Rows in table `b` are arrays (compact) */</span><br/><span class="hl-0">%webout(OBJ,c,fmt=N) /* Table `c` is sent unformatted (raw) */</span><br/><span class="hl-0">%webout(OBJ,c,dslabel=d) /* Rename table as `d` in output JSON */</span><br/><span class="hl-0">%webout(OBJ,c,dslabel=e, maxobs=10) /* send only 10 rows back */</span><br/><span class="hl-0">%webout(CLOSE) /* Close the JSON and add default variables */</span>
</code></pre>
<p>By default, special SAS numeric missings (_a-Z) are converted to <code>null</code> in the JSON. If you&#39;d like to preserve these, use the <code>missing=STRING</code> option as follows:</p>
<pre><code class="language-sas"><span class="hl-0">%webout(OBJ,a,missing=STRING)</span>
</code></pre>
<p>In this case, special missings (such as <code>.a</code>, <code>.b</code>) are converted to javascript string values (<code>&#39;A&#39;, &#39;B&#39;</code>).</p>
<p>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 <code>showmeta</code> param to the <code>webout()</code> macro as follows:</p>
<pre><code class="language-sas"><span class="hl-0">%webout(OBJ,a,missing=STRING,showmeta=YES)</span>
</code></pre>
<p>The <code>%webout()</code> macro itself is just a wrapper for the <a href="https://core.sasjs.io/mp__jsonout_8sas.html">mp_jsonout</a> macro.</p>
<a href="#configuration" id="configuration" style="color: inherit; text-decoration: none;">
<h2>Configuration</h2>
</a>
<p>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 <a href="https://adapter.sasjs.io/classes/types.sasjsconfig.html">here</a>. The main config items are:</p>
<ul>
<li><code>appLoc</code> - this is the folder (eg in metadata or SAS Drive) under which the SAS services are created.</li>
<li><code>serverType</code> - either <code>SAS9</code>, <code>SASVIYA</code> or <code>SASJS</code>. The <code>SASJS</code> server type is for use with <a href="https://github.com/sasjs/server">sasjs/server</a>.</li>
<li><code>serverUrl</code> - 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.</li>
<li><code>debug</code> - if <code>true</code> then SAS Logs and extra debug information is returned.</li>
<li><code>loginMechanism</code> - either <code>Default</code> or <code>Redirected</code>. See <a href="#sas-logon">SAS Logon</a> section.</li>
<li><code>useComputeApi</code> - Only relevant when the serverType is <code>SASVIYA</code>. If <code>true</code> the <a href="#using-the-compute-api">Compute API</a> is used. If <code>false</code> the <a href="#using-the-jes-api">JES API</a> is used. If <code>null</code> or <code>undefined</code> the <a href="#using-jes-web-app">Web</a> approach is used.</li>
<li><code>contextName</code> - Compute context on which the requests will be called. If missing or not provided, defaults to <code>Job Execution Compute context</code>.</li>
<li><code>requestHistoryLimit</code> - Request history limit. Increasing this limit may affect browser performance, especially with debug (logs) enabled. Default is 10.</li>
</ul>
<p>The adapter supports a number of approaches for interfacing with Viya (<code>serverType</code> is <code>SASVIYA</code>). For maximum performance, be sure to <a href="https://sasjs.io/guide-viya/#shared-account-and-server-re-use">configure your compute context</a> with <code>reuseServerProcesses</code> as <code>true</code> and a system account in <code>runServerAs</code>. This functionality is available since Viya 3.5. This configuration is supported when <a href="https://sasjs.io/sasjs-cli-context/#sasjs-context-create">creating contexts using the CLI</a>.</p>
<a href="#using-jes-web-app" id="using-jes-web-app" style="color: inherit; text-decoration: none;">
<h3>Using JES Web App</h3>
</a>
<p>In this setup, all requests are routed through the JES web app, at <code>YOURSERVER/SASJobExecution?_program=/your/program</code>. 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.</p>
<pre><code><span class="hl-0">{</span><br/><span class="hl-0"> </span><span class="hl-9">appLoc</span><span class="hl-0">:</span><span class="hl-4">&quot;/Your/Path&quot;</span><span class="hl-0">,</span><br/><span class="hl-0"> </span><span class="hl-9">serverType</span><span class="hl-0">:</span><span class="hl-4">&quot;SASVIYA&quot;</span><span class="hl-0">,</span><br/><span class="hl-0"> </span><span class="hl-9">contextName</span><span class="hl-0">: </span><span class="hl-4">&#39;yourComputeContext&#39;</span><br/><span class="hl-0">}</span>
</code></pre>
<p>Note - to use the web approach, the <code>useComputeApi</code> property must be <code>undefined</code> or <code>null</code>.</p>
<a href="#using-the-jes-api" id="using-the-jes-api" style="color: inherit; text-decoration: none;">
<h3>Using the JES API</h3>
</a>
<p>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 <code>__job</code> parameter. Depending on your network bandwidth, it may or may not be faster than the JES Web approach.</p>
<p>This approach (<code>useComputeApi: false</code>) also ensures that jobs are displayed in Environment Manager.</p>
<pre><code class="language-json"><span class="hl-0">{</span><br/><span class="hl-0"> </span><span class="hl-10">appLoc</span><span class="hl-0">:</span><span class="hl-4">&quot;/Your/Path&quot;</span><span class="hl-0">,</span><br/><span class="hl-0"> </span><span class="hl-10">serverType</span><span class="hl-0">:</span><span class="hl-4">&quot;SASVIYA&quot;</span><span class="hl-0">,</span><br/><span class="hl-0"> </span><span class="hl-10">useComputeApi</span><span class="hl-0">: </span><span class="hl-1">false</span><span class="hl-0">,</span><br/><span class="hl-0"> </span><span class="hl-10">contextName</span><span class="hl-0">: </span><span class="hl-10">&#39;yourComputeContext&#39;</span><br/><span class="hl-0">}</span>
</code></pre>
<a href="#using-the-compute-api" id="using-the-compute-api" style="color: inherit; text-decoration: none;">
<h3>Using the Compute API</h3>
</a>
<p>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 &#39;hot&#39; session, if it exists. Sessions are always deleted after every use, which actually makes this <em>less</em> resource intensive than a typical JES web app, in which all sessions are kept alive by default for 15 minutes.</p>
<p>With this approach (<code>useComputeApi: true</code>), the requests/logs will <em>not</em> appear in the list in Environment manager.</p>
<pre><code class="language-json"><span class="hl-0">{</span><br/><span class="hl-0"> </span><span class="hl-10">appLoc</span><span class="hl-0">:</span><span class="hl-4">&quot;/Your/Path&quot;</span><span class="hl-0">,</span><br/><span class="hl-0"> </span><span class="hl-10">serverType</span><span class="hl-0">:</span><span class="hl-4">&quot;SASVIYA&quot;</span><span class="hl-0">,</span><br/><span class="hl-0"> </span><span class="hl-10">useComputeApi</span><span class="hl-0">: </span><span class="hl-1">true</span><span class="hl-0">,</span><br/><span class="hl-0"> </span><span class="hl-10">contextName</span><span class="hl-0">: </span><span class="hl-4">&quot;yourComputeContext&quot;</span><br/><span class="hl-0">}</span>
</code></pre>
<a href="#more-resources" id="more-resources" style="color: inherit; text-decoration: none;">
<h1>More resources</h1>
</a>
<p>For more information and examples specific to this adapter you can check out the <a href="https://sasjs.io/sasjs-adapter/">user guide</a> or the <a href="http://adapter.sasjs.io/">technical</a> documentation.</p>
<p>For more information on building web apps in general, check out these <a href="https://sasjs.io/training/resources/">resources</a> or contact the <a href="https://www.linkedin.com/in/allanbowe/">author</a> directly.</p>
<p>As a SAS customer you can also request a copy of <a href="https://datacontroller.io">Data Controller</a> - free for up to 5 users, this tool makes use of all parts of the SASjs framework.</p>
<a href="#star-gazing" id="star-gazing" style="color: inherit; text-decoration: none;">
<h2>Star Gazing</h2>
</a>
<p>If you find this library useful, help us grow our star graph!</p>
<p><img src="https://starchart.cc/sasjs/adapter.svg" alt=""></p>
<a href="#contributors-✨" id="contributors-✨" style="color: inherit; text-decoration: none;">
<h2>Contributors ✨</h2>
</a>
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
<p><a href="#contributors-"><img src="https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square" alt="All Contributors"></a></p>
<!-- ALL-CONTRIBUTORS-BADGE:END -->
<p>Thanks goes to these wonderful people (<a href="https://allcontributors.org/docs/en/emoji-key">emoji key</a>):</p>
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tr>
<td align="center"><a href="https://krishna-acondy.io/"><img src="https://avatars.githubusercontent.com/u/2980428?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Krishna Acondy</b></sub></a><br /><a href="https://github.com/sasjs/adapter/commits?author=krishna-acondy" title="Code">💻</a> <a href="#infra-krishna-acondy" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#blog-krishna-acondy" title="Blogposts">📝</a> <a href="#content-krishna-acondy" title="Content">🖋</a> <a href="#ideas-krishna-acondy" title="Ideas, Planning, & Feedback">🤔</a> <a href="#video-krishna-acondy" title="Videos">📹</a></td>
<td align="center"><a href="https://www.erudicat.com/"><img src="https://avatars.githubusercontent.com/u/25773492?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Yury Shkoda</b></sub></a><br /><a href="https://github.com/sasjs/adapter/commits?author=YuryShkoda" title="Code">💻</a> <a href="#infra-YuryShkoda" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#ideas-YuryShkoda" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/sasjs/adapter/commits?author=YuryShkoda" title="Tests">⚠️</a> <a href="#video-YuryShkoda" title="Videos">📹</a></td>
<td align="center"><a href="https://github.com/medjedovicm"><img src="https://avatars.githubusercontent.com/u/18329105?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Mihajlo Medjedovic</b></sub></a><br /><a href="https://github.com/sasjs/adapter/commits?author=medjedovicm" title="Code">💻</a> <a href="#infra-medjedovicm" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="https://github.com/sasjs/adapter/commits?author=medjedovicm" title="Tests">⚠️</a> <a href="https://github.com/sasjs/adapter/pulls?q=is%3Apr+reviewed-by%3Amedjedovicm" title="Reviewed Pull Requests">👀</a></td>
<td align="center"><a href="https://github.com/allanbowe"><img src="https://avatars.githubusercontent.com/u/4420615?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Allan Bowe</b></sub></a><br /><a href="https://github.com/sasjs/adapter/commits?author=allanbowe" title="Code">💻</a> <a href="https://github.com/sasjs/adapter/pulls?q=is%3Apr+reviewed-by%3Aallanbowe" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/sasjs/adapter/commits?author=allanbowe" title="Tests">⚠️</a> <a href="#mentoring-allanbowe" title="Mentoring">🧑‍🏫</a> <a href="#maintenance-allanbowe" title="Maintenance">🚧</a></td>
<td align="center"><a href="https://github.com/saadjutt01"><img src="https://avatars.githubusercontent.com/u/8914650?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Muhammad Saad </b></sub></a><br /><a href="https://github.com/sasjs/adapter/commits?author=saadjutt01" title="Code">💻</a> <a href="https://github.com/sasjs/adapter/pulls?q=is%3Apr+reviewed-by%3Asaadjutt01" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/sasjs/adapter/commits?author=saadjutt01" title="Tests">⚠️</a> <a href="#mentoring-saadjutt01" title="Mentoring">🧑‍🏫</a> <a href="#infra-saadjutt01" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>
<td align="center"><a href="https://github.com/sabhas"><img src="https://avatars.githubusercontent.com/u/82647447?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Sabir Hassan</b></sub></a><br /><a href="https://github.com/sasjs/adapter/commits?author=sabhas" title="Code">💻</a> <a href="https://github.com/sasjs/adapter/pulls?q=is%3Apr+reviewed-by%3Asabhas" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/sasjs/adapter/commits?author=sabhas" title="Tests">⚠️</a> <a href="#ideas-sabhas" title="Ideas, Planning, & Feedback">🤔</a></td>
<td align="center"><a href="https://github.com/VladislavParhomchik"><img src="https://avatars.githubusercontent.com/u/83717836?v=4?s=100" width="100px;" alt=""/><br /><sub><b>VladislavParhomchik</b></sub></a><br /><a href="https://github.com/sasjs/adapter/commits?author=VladislavParhomchik" title="Tests">⚠️</a> <a href="https://github.com/sasjs/adapter/pulls?q=is%3Apr+reviewed-by%3AVladislavParhomchik" title="Reviewed Pull Requests">👀</a></td>
</tr>
<tr>
<td align="center"><a href="http://rudvfaden.github.io/"><img src="https://avatars.githubusercontent.com/u/2445577?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Rud Faden</b></sub></a><br /><a href="#userTesting-rudvfaden" title="User Testing">📓</a> <a href="https://github.com/sasjs/adapter/commits?author=rudvfaden" title="Documentation">📖</a></td>
</tr>
</table>
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
<p>This project follows the <a href="https://github.com/all-contributors/all-contributors">all-contributors</a> specification. Contributions of any kind welcome!</p>
</div></div>
<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
<div class="tsd-navigation settings">
<details class="tsd-index-accordion"><summary class="tsd-accordion-summary">
<h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><path d="M4.93896 8.531L12 15.591L19.061 8.531L16.939 6.409L12 11.349L7.06098 6.409L4.93896 8.531Z" fill="var(--color-text)"></path></svg> Settings</h3></summary>
<div class="tsd-accordion-details">
<div class="tsd-filter-visibility">
<h4 class="uppercase">Member Visibility</h4><form>
<ul id="tsd-filter-options">
<li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li>
<li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></form></div>
<div class="tsd-theme-toggle">
<h4 class="uppercase">Theme</h4><select id="theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div>
<nav class="tsd-navigation primary">
<details class="tsd-index-accordion" open><summary class="tsd-accordion-summary">
<h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><path d="M4.93896 8.531L12 15.591L19.061 8.531L16.939 6.409L12 11.349L7.06098 6.409L4.93896 8.531Z" fill="var(--color-text)"></path></svg> Modules</h3></summary>
<div class="tsd-accordion-details">
<ul>
<li class="current selected"><a href="modules.html">@sasjs/adapter</a>
<ul>
<li class="tsd-kind-module"><a href="modules/SAS9ApiClient.html">SAS9<wbr/>Api<wbr/>Client</a></li>
<li class="tsd-kind-module"><a href="modules/SASViyaApiClient.html">SASViya<wbr/>Api<wbr/>Client</a></li>
<li class="tsd-kind-module"><a href="modules/SASjs.html">SASjs</a></li>
<li class="tsd-kind-module"><a href="modules/SASjsApiClient.html">SASjs<wbr/>Api<wbr/>Client</a></li>
<li class="tsd-kind-module"><a href="modules/types.html">types</a></li></ul></li></ul></div></details></nav></div></div>
<div class="container tsd-generator">
<p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></div>
<div class="overlay"></div><script src="assets/main.js"></script></body></html>
Reference in New Issue View Git Blame Copy Permalink