Calling Decision Builder Services via REST

[#1]

SAS Decision Builder brings SAS Decision Manager rule flows and predictive models together with conditional logic to build "Decision" services. For example, a Used Car Auction "Decision" might combine a car valuation model with an auto auction rule-flow to create a decision service that looks something like this:

The idea being that a bid decision is governed differently for automatic versus manual transmission cars. For manual cars, the bid decision is generated using a predictive model (DecisionTree) and for automatics, the decision is generated by a rule flow (AutoRuleFlow).

Decision Service Deployment

Decision Builder services can be deployed for batch execution but, often, work best as real time services. For example, in the auction setting proposed above, you would need to rapidly generate new bid decisions as bidding escalates. When published for real-time, decisions are deployed to the SAS MicroAnalytic Service as modules. Deployment is performed in the Decision Builder Web Application simply by pushing the "Publish" button.

.

Decision Service Execution

MAS modules are meant to be integrated into web applications and can easily be called via REST (simple HTTP commands). I can approximate this scenario using curl. A curl command calling one of the deployed services would look like this:

curl -H "Content-Type: application/json" --data-binary "@input.txt" -o "output.txt" http://sasdemo:Orion123@localhost/SASMicroAnalyticService/rest/modules/b45092bd-edd9-4c70-bea2-5bd725271fe6/steps/execute

This command is performing an HTTP POST method on the http://localhost/SASMicroAnalyticService/rest/modules/b45092bd-edd9-4c70-bea2-5bd725271fe6/steps/execute MAS module step using the local sasdemo user. The posted data comes from a local file, input.json which contains the following JSON. Each variable required for the conditional logic, predictive models, and rule flows must be included.

{"version":1, "inputs": [{ "name": "\"aucguart_\"", "value": "\"NULL\"" }, { "name": "\"auction_\"", "value": "\"ADESA\"" }, { "name": "\"byrno_\"", "value": 19638 }, { "name": "\"carscore_\"", "value": 0.1139443331 }, { "name": "\"color_\"", "value": "\"WHITE\"" }, { "name": "\"isonlinesale_\"", "value": 0 }, { "name": "\"make_\"", "value": "\"DODGE\"" }, { "name": "\"meanvehicaldelta_\"", "value": 869.0656738 }, { "name": "\"mmracquisitionauctionaveragepric_\"", "value": 6854 }, { "name": "\"mmracquisitionauctioncleanprice_\"", "value": 8383 }, { "name": "\"mmracquisitionretailaverageprice_\"", "value": 10987 }, { "name": "\"mmracquisitonretailcleanprice_\"", "value": 12572 }, { "name": "\"mmrcurrentauctionaverageprice_\"", "value": 7456 }, { "name": "\"mmrcurrentauctioncleanprice_\"", "value": 9222 }, { "name": "\"mmrcurrentretailaverageprice_\"", "value": 11374 }, { "name": "\"mmrcurrentretailcleanprice_\"", "value": 12791 }, { "name": "\"nationality_\"", "value": "\"AMERICAN\"" }, { "name": "\"primeunit_\"", "value": "\"NULL\"" }, { "name": "\"refid_\"", "value": 2 }, { "name": "\"size_\"", "value": "\"LARGE TRUCK\"" }, { "name": "\"topthreeamericanname_\"", "value": "\"OTHER\"" }, { "name": "\"transmission_\"", "value": "\"AUTO\"" }, { "name": "\"vehbcost_\"", "value": 10778 }, { "name": "\"vehicleage_\"", "value": 5 }, { "name": "\"VEHODO_\"", "value": 12934 }, { "name": "\"vehodometer_\"", "value": 12934 }, { "name": "\"vehyear_\"", "value": 2005 }, { "name": "\"vinstate_\"", "value": "\"FL\"" }, { "name": "\"VNZIP1_\"", "value": 33619 }, { "name": "\"warrantycost_\"", "value": 1113 }, { "name": "\"wheeltype_\"", "value": "\"Alloy\"" }, { "name": "\"wheeltypeid_\"", "value": "\"1\"" }] }

The response is directed to a file named output.json which, after successful completion, contains the following JSON. The response will contain all the variables returned by the decision service. Most notably here, the field, ISBADBUY = 0 so our bidder is free to bid:

{ "moduleId": "b45092bd-edd9-4c70-bea2-5bd725271fe6", "stepId": "execute", "version": 1, "output": [{ "name": "\"_NODE_\"", "value": 6.0 }, { "name": "\"_WARN_\"", "value": null }, { "name": "\"aucguart\"", "value": "\"NULL\"" }, { "name": "\"auction\"", "value": "\"ADESA\"" }, { "name": "\"BadCar\"", "value": 0.0 }, { "name": "\"BadMakeIndicator\"", "value": 0.0 }, { "name": "\"BadStateIndicator\"", "value": 0.0 }, { "name": "\"byrno\"", "value": 19638.0 }, { "name": "\"carscore\"", "value": 0.1139443331 }, { "name": "\"color\"", "value": "\"WHITE\"" }, { "name": "\"EM_CLASSIFICATION\"", "value": "0" }, { "name": "\"EM_EVENTPROBABILITY\"", "value": 0.15039190071848 }, { "name": "\"EM_PROBABILITY\"", "value": 0.84960809928151 }, { "name": "\"EM_SEGMENT\"", "value": 6.0 }, { "name": "\"I_ISBADBUY\"", "value": "0" }, { "name": "\"IMP_MMRACQUISITIONAUCTIONAVERAGE\"", "value": null }, { "name": "\"IMP_MMRACQUISITIONAUCTIONCLEANPR\"", "value": null }, { "name": "\"IMP_MMRACQUISITIONRETAILAVERAGEP\"", "value": null }, { "name": "\"IMP_MMRACQUISITONRETAILCLEANPRIC\"", "value": null }, { "name": "\"IMP_MMRCURRENTAUCTIONAVERAGEPRIC\"", "value": null }, { "name": "\"IMP_MMRCURRENTAUCTIONCLEANPRICE\"", "value": null }, { "name": "\"IMP_MMRCURRENTRETAILAVERAGEPRICE\"", "value": null }, { "name": "\"IMP_MMRCURRENTRETAILCLEANPRICE\"", "value": null }, { "name": "\"isonlinesale\"", "value": 0.0 }, { "name": "\"make\"", "value": "\"DODGE\"" }, { "name": "\"meanvehicaldelta\"", "value": 869.0656738 }, { "name": "\"mmracquisitionauctionaveragepric\"", "value": 6854.0 }, { "name": "\"mmracquisitionauctioncleanprice\"", "value": 8383.0 }, { "name": "\"mmracquisitionretailaverageprice\"", "value": 10987.0 }, { "name": "\"mmracquisitonretailcleanprice\"", "value": 12572.0 }, { "name": "\"mmrcurrentauctionaverageprice\"", "value": 7456.0 }, { "name": "\"mmrcurrentauctioncleanprice\"", "value": 9222.0 }, { "name": "\"mmrcurrentretailaverageprice\"", "value": 11374.0 }, { "name": "\"mmrcurrentretailcleanprice\"", "value": 12791.0 }, { "name": "\"nationality\"", "value": "\"AMERICAN\"" }, { "name": "\"P_ISBADBUY0\"", "value": 0.84960809928151 }, { "name": "\"P_ISBADBUY1\"", "value": 0.15039190071848 }, { "name": "\"primeunit\"", "value": "\"NULL\"" }, { "name": "\"Q_ISBADBUY0\"", "value": 0.84960809928151 }, { "name": "\"Q_ISBADBUY1\"", "value": 0.15039190071848 }, { "name": "\"refid\"", "value": 2.0 }, { "name": "\"size\"", "value": "\"LARGE TRUCK\"" }, { "name": "\"topthreeamericanname\"", "value": "\"OTHER\"" }, { "name": "\"transmission\"", "value": "\"AUTO\"" }, { "name": "\"U_ISBADBUY\"", "value": 0.0 }, { "name": "\"V_ISBADBUY0\"", "value": 0.85557232162103 }, { "name": "\"V_ISBADBUY1\"", "value": 0.14442767837896 }, { "name": "\"vehbcost\"", "value": 10778.0 }, { "name": "\"vehicleage\"", "value": 5.0 }, { "name": "\"VEHODO\"", "value": 12934.0 }, { "name": "\"vehodometer\"", "value": 12934.0 }, { "name": "\"vehyear\"", "value": 2005.0 }, { "name": "\"vinstate\"", "value": "\"FL\"" }, { "name": "\"VNZIP1\"", "value": 33619.0 }, { "name": "\"warrantycost\"", "value": 1113.0 }, { "name": "\"wheeltype\"", "value": "\"Alloy\"" }, { "name": "\"wheeltypeid\"", "value": "\"1\"" }] }

.

Decision Service Discovery

In order to see what MAS modules are available along with their input and output message structure, simply query the MAS with the following REST GET query, http://localhost/SASMicroAnalyticService/rest/modules/. It can be issued in any web browser.

When prototyping with test data, JSONLint or another JSON validator can help quickly format the returned JSON so it's easier to read.

 

Update: A few notes based on Comments I've received offline

This post was designed to convey understanding of Decision Builder services as quickly as possible. To that end it sacrificed best practices and security at the expense of brevity, convenience, and simplicity. However, if working with Decision Builder at a customer site, you should consider the following:

1. Instead of putting credentials in the curl URL, use curl’s support for basic authentication such as curl --user sasdemo: Orion123 … or curl --netrc ## The credentials are in the .netrc file or _netrc
2. All production deployments should access SAS’ REST APIs with TLS (https://)
3. While JSONLint is handy for test data, avoid pasting real data into external JSON formatters. Another good way to format JSON is with PYthon: python –mjson.tool < output.json

.

[SundareshS]

Hi Stephen / Anna,

Thanks a lot for this article. I found it useful in validating my steps (for which I am using the HMEQ based tutorial provided in the Decision manager help centre).  I also referred the paper 

http://support.sas.com/resources/papers/proceedings17/SAS0606-2017.pdf alongside.

However, I did notice a couple of differences between this article and what I see on my installation.

i) I am able to publish my model successfully, however the URL I obtain is <server>/microanalyticScore/modules/evaluate_loans1_0,

not /SASMicroAnalyticsService/rest/modules

Is the below the correct URL to use? (I am on Viya 3.3)

ii) I guess this is a result of (i) , but while I am able to successfully call this through cURL (ie. with above URL), I still get my "output" containing ALL variables - even though I went to Decision manager and just checked BAD/REJECT/REVIEW as output variables I wanted returned. Is there any other way to make the "output.text return only specific variables ?

thanks and regards

Sundar