Calling Intelligent Decisioning from ESP
If you are streaming data using SAS ESP and your data stream involves making decisions, you can build Rulesets and Decisions in SAS Intelligent Decisioning and use these in your data stream.
ESP can invoke the code that is generated by SAS Intelligent Decisioning and execute the code in its Micro Analytic Service (MAS) engine.
In this blog I discuss the steps required to use Rulesets and Decisions in an ESP data stream.
Receiving code for Rulesets & Decisions
If you have a Ruleset or Decision in Intelligent Decisioning that you’d like to use within a data stream in ESP you need to export the DS2 code that is generated by Intelligent Decisioning and point ESP towards the code to execute it. The steps to export the code are very similar for Rulesets and Decisions.
To export code from Intelligent Decisioning we are going to use the Viya REST API to:
- Obtain an access token to SAS Viya
- Receive the ID for the required Ruleset or Decision
- Receive the Intelligent Decisioning DS2 code for the Ruleset or Decision
Obtain an access token to SAS Viya
Before you can start using SAS Viya APIs, you must have your SAS administrator register a client identifier. The SAS Logon OAuth API uses OAuth2 to securely identify your application before it connects to the SAS Viya platform. See Registering clients for information on how clients are registered. Once a client is successfully registered, the SAS administrator provides you with the client identifier and client secret to authenticate an API request.
To obtain an access token call:
http://{{ViyaServer}}/SASLogon/oauth/token
|
|
Value |
Setting |
Comment |
|
Method |
POST |
|
|
|
|
|
|
|
|
Authorization |
Username |
Set to <Client Identifier> |
Use Basic Authorization |
|
|
Password |
Set to <Client Secret> |
Use Basic Authorization |
|
|
|
|
|
|
Header |
Content-Type |
application/x-www-form-urlencoded |
|
|
|
|
|
|
|
Body |
grant_type |
password |
x-www-form-urlencoded |
|
|
username |
Set to <Viya username> |
x-www-form-urlencoded |
|
|
password |
Set to <Viya password> |
x-www-form-urlencoded |
If successfully executed, you will get an access token which is to be used for all other REST calls.
 |
Receive the Ruleset or Decision ID
We need to get the ID for the Ruleset or Decision that we want to use in ESP. The ID is required for the REST Endpoint to receive the DS2 code.
To get the ID, call the appropriate Endpoint for Ruleset or Decision:
Ruleset:
http://{{ViyaServer}}/businessRules/ruleSets
Decision:
http://{{ViyaServer}}/decisions/flows
|
|
Value |
Setting |
Comment |
|
Method |
GET |
|
|
|
|
|
|
|
|
Parameters |
filter |
eq(name,"<Ruleset Name>") |
Set <Ruleset Name> to the name of the Ruleset you want to look up. |
|
|
|
|
|
|
Header |
Authorization |
Bearer <Access Token> |
Unsure to have a space Bearer and the access token. |
|
|
Content-Type |
application/json |
|
If successfully executed, you will receive the Ruleset/Decision ID in the field “id” in the “items” list.
 |
Receive Intelligent Decisioning code
With the just received ID we are going to export the DS2 code for the Ruleset or Decision.
To get the code call the appropriate Endpoint for Ruleset or Decision:
Ruleset:
http://{{ViyaServer}}/businessRules/ruleSets/<ID>/code
Decision:
http://{{ViyaServer}}/decisions/flows/<ID>/code
Set <ID> to the value of the Ruleset or Decision ID we just received.
|
|
Value |
Setting |
Comment |
|
Method |
GET |
|
|
|
|
|
|
|
|
Parameters |
codeTarget |
MICROANALYTICSERVICE |
|
|
|
lookupMode |
inline |
|
|
|
isGeneratingRuleFiredColumn |
false |
|
|
|
|
|
|
|
Header |
Authorization |
Bearer <Access Token> |
Unsure to have a space Bearer and the access token |
|
|
Content-Type |
text/vnd.sas.source.ds2 |
|
If executed successfully, you will receive the DS2 code for the Ruleset or Decision.
 |
Preparing the code
The steps for getting the code for Rulesets or Decisions are very similar. But for Decisions we need to do some extra steps.
Ruleset Code
For Rulesets we copy the DS2 code from the REST call into a file, save the file with a descriptive name, i.e. the name of the Ruleset, and move it to a location where ESP can access it.
Decision Code
For Decisions, the code usually consists of several DS2 packages. One DS2 package for each node in the decision flow. We need to split the code that we received from Intelligent Decisioning by saving each package in a separate file. When naming the files, good practice is prefixing the files with the decision name and suffix it with the appropriate node name like <decision name>_<node name>.ds2. To know which package belongs to which node in the decision flow you find a comment above each DS2 package statement with the appropriate information. The last package in the Intelligent Decisioning code is the decision flow entry point. Usually I give this file the name of the decision like <decision name>.ds2.
When you have split the DS code into several files, you move the files to a location where ESP can access them.
Invoke Intelligent Decisioning Code in ESP
As we have saved the code into files and moved them to a location that ESP can access, we can now invoke the code from our ESP project.
For Rulesets we need to register the ruleset code file we saved and for Decisions we need to register all files that we saved, the file form the decision flow as well as the files for the decision nodes.
In ESP we open the project and go to Micro Analytic Service Modules at the project level. We add a new Micro Analytic Service Module for each file and fill in all required fields.
|
Field |
Value |
Comment |
|
Name |
<Set a descriptive name> |
I.e. name of the ruleset, decision or decision node *** See comment Note below! *** |
|
Language |
DS2 |
|
|
Function names |
execute |
This must be set to ‘execute’. The entry point method into each DS2 package is called ‘execute’. |
|
Code source |
External file |
|
|
External file |
<DS2 code file> |
The name of the DS2 code to register including the directory where the file is stored. It is good practice to use a Token to point to the directory where the code file resides. |
|
Note: ESP will load the DS2 code files in alphabetical order. Therefore, you must ensure that the main package of a decision flow is the first in the Micro Analytic Service Modules list in ESP. You can best achieve this by adding a number prefix to the Name like 01_, 02_,etc. |
 |
Add a Calculate Window to the data stream to invoke the RuleSet or Decision. At Settings choose Calculation = User-specified. At Handlers select the Ruleset source or the main module for the Decision flow and make sure the field values are set correctly.
|
Field |
Value |
|
|
Handler type |
SAS Micro Analytic Service |
|
|
Module |
<Ruleset Name> or |
Choose the name that you’ve set for the Decision Ruleset. |
|
Function |
execute |
|
 |
Save the project and you are ready to run it in Test mode to check if it works as desired.
Conclusion
Intelligent Decisioning is a great place to build and maintain rules and decision logic.
Executing decision flows in an ESP project is a great way to split decision logic from the more technical part of the ESP project. This gives people with less technical knowledge the opportunity to concentrate on the more logical part of the project. Decisions can be built and tested independent from the rest of the ESP project and once ready they can be integrated into the ESP project.
