# HTML5 Data Adapter for SAS® (H54S) [![npm version](https://badge.fury.io/js/h54s.svg)](https://badge.fury.io/js/h54s) [![install size](https://packagephobia.now.sh/badge?p=h54s)](https://packagephobia.now.sh/result?p=h54s) [![npm downloads](https://img.shields.io/npm/dm/h54s.svg?style=flat-square)](https://img.shields.io/npm/dm/h54s) [![gitter chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/Boemska/h54s?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ## What is H54S? H54S facilitates and manages bi-directional communication between JavaScript based HTML5 Web Applications (Single Page Web Applications, Progressive Web Apps) and back-end services written in SAS that execute on either SAS Viya or SAS v9. The library aims to facilitate communication between Javascript-based UI developers and SAS developers, enabling them to build and deploy secure, production ready Web Applications with as little friction as possible. ## Quick Start This repository contains the **core H54S JavaScript library**. If you understand what this does and just want to start creating an App, we highly recommend that you head over to our our **[Create SAS App repository](https://github.com/boemska/create-sas-app)** for a choice of pre-integrated Create React App-based template applications that will make your development much, much easier. #### Server Requirements An instance of either: - SAS Viya (3.4 or later, full deployment); or - SAS v9 Platform (v9.4) with Integration Technologies and a SAS Web Tier #### Client Requirements - A modern Web Browser (Chrome, Firefox, Safari, IE11+) Google Chrome or Firefox are strongly recommended. For development, having Git and Node installed is also very useful. ## Why is it called H54S? It started out as an abbreviation of 'HTML5 4 SAS'. Marketing isn't our strong point. We know it sounds like a strain of Bird Flu, but the project has been active under this name for a few years now so we're sticking to it. It's _almost_ memorable now. ## Great. How do I get started? Using [git](https://git-scm.com/), clone this repository to somewhere local: ``` git clone https://github.com/Boemska/h54s ``` Then if you're a SAS developer, put your SAS hat on, and follow the instructions according which flavour of SAS you're working with. ## SAS Back End _Note: You may notice that while the process differs, the code is exactly the same for both SAS Viya and SAS v9. **The design of H54S ensures that all applications built with it are portable between SAS v9 and SAS Viya, with no changes in code required to deploy or promote applications across the two platforms**_ 1. Copy the `sasautos` directory to your SAS server. **On Viya** this is your Compute Server node, **on SAS v9** this is your Application Server context (e.g. SASApp) compute node. In this example we copied it to `/pub/apps/h54s/sasautos` on the compute node filesystem. 2. Register a new back-end code object. **On Viya** this is a File of type Job Definition, and can be registered through the SASJobExecution WebApp (`https://[yourViyaServer]/SASJobExecution/`). **On SAS v9** this is a Stored Process and can be registered through SAS Management Console or Enterprise Guide. In both cases you'll be registering the code object to a SAS folder that you have permission to write to. In both Viya and v9, I created mine in my user's `My Folder` location ("chris") and called it `myFirstService`: 3. Edit the code for the newly registered code object, and register the following code: ```sas * get H54s (from wherever you placed it in step 1) ; %include '/pub/apps/h54s/sasautos/h54s.sas'; * Process and receive datasets from the client ; %bafgetdatasets(); * Do some SAS. Can be Anything. Just get some data; data mydata; set sashelp.class; run; proc sort data=mydata; by name; run; * Return a resulting dataset to the client ; %bafheader() %bafOutDataset(processed, work, myData) %bafFooter() ``` 4. Configure the output type for your newly registered code object. **On Viya**, right click on the job name and select properties. From the properties menu select "Parameters". Add the following parameter and then click save: * Name: `_output_type` * Default value: `html` * Field type: `Character` * Required: `false` **On SAS v9**, make sure you enable Streaming Output as the output type. If you are using Enterprise Guide to do this, also be sure to check "Global Macro Variables" and uncheck "Include STP Macros" under the "Include code for" dropdown. 5. Execute the newly registered code. **On Viya** do this through the same SASJobExecution WebApp, by right clicking on the Job and selecting "Submit job". **On SAS v9** do this through the Stored Process WebApp, by logging on to [yourserver]/SASStoredProcess/, locating the job in the UI and clicking on it. In both cases, you should see output similar to the following: ```json { "processed" : [{"Name":"Alfred","Sex":"M","Age":14,"Height":69,"Weight":112.5},{"Name":"Alice","Sex":"F","Age":13,"Height":56.5,"Weight":84},{"Name":"Barbara","Sex":"F","Age":13,"Height":65.3,"Weight":98},{"Name":"Carol","Sex":"F","Age":14,"Height":62.8,"Weight":102.5},{"Name":"Henry","Sex":"M","Age":14,"Height":63.5,"Weight":102.5},{"Name":"James","Sex":"M","Age":12,"Height":57.3,"Weight":83},{"Name":"Jane","Sex":"F","Age":12,"Height":59.8,"Weight":84.5},{"Name":"Janet","Sex":"F","Age":15,"Height":62.5,"Weight":112.5},{"Name":"Jeffrey","Sex":"M","Age":13,"Height":62.5,"Weight":84},{"Name":"John","Sex":"M","Age":12,"Height":59,"Weight":99.5},{"Name":"Joyce","Sex":"F","Age":11,"Height":51.3,"Weight":50.5},{"Name":"Judy","Sex":"F","Age":14,"Height":64.3,"Weight":90},{"Name":"Louise","Sex":"F","Age":12,"Height":56.3,"Weight":77},{"Name":"Mary","Sex":"F","Age":15,"Height":66.5,"Weight":112},{"Name":"Philip","Sex":"M","Age":16,"Height":72,"Weight":150},{"Name":"Robert","Sex":"M","Age":12,"Height":64.8,"Weight":128},{"Name":"Ronald","Sex":"M","Age":15,"Height":67,"Weight":133},{"Name":"Thomas","Sex":"M","Age":11,"Height":57.5,"Weight":85},{"Name":"William","Sex":"M","Age":15,"Height":66.5,"Weight":112}], "usermessage" : "blank", "logmessage" : "blank", "requestingUser" : "chris", "requestingPerson" : "Chris", "executingPid" : 1054, "sasDatetime" : 1906323243.9 , "status" : "success"} ``` This is good enough for now. Time for some Front End Development. ## HTML5 Front End ### Vanilla Javascript This is the most basic approach. Assuming that you have a local Web Server installed for development: 1. Create an `index.html` or start a new project in your chosen IDE. 2. Copy the `/dist/h54s.js` file to your project and include it. Your `index.html` might look like this: ```html