Exposing SAS Decision Manager Decision Flows as REST APIs in SAS Viya: A Step-by-Step Guide

SAS Viya is a modern, open analytics platform that supports analytical models and decision flows. With SAS Decision Manager or SAS Intelligent Decisioning, you can build complex decision flows that encapsulate business rules and analytics. Exposing these decision flows as RESTful APIs enables real-time decisioning in external applications, enhancing agility and integration capabilities.

This guide provides a detailed, verified walkthrough on how to expose your decision flows as REST APIs in SAS Viya, facilitating seamless integration with other systems and processes.

Prerequisites

Before you begin, ensure you have the following:

Access to SAS Viya: An operational SAS Viya environment (version 3.5 or later) with SAS Decision Manager or SAS Intelligent Decisioning installed and configured.
Decision Flow: A decision flow that has been created and validated within SAS Decision Manager or SAS Intelligent Decisioning.
Permissions: Sufficient privileges to publish decision flows and manage REST APIs within the SAS Viya environment.

Step 1: Access SAS Decision Manager

Log In to SAS Viya:
- Open your preferred web browser.
- Navigate to your SAS Viya login page (e.g., https://<your-viya-server>/SASDrive).
- Enter your username and password to authenticate.
Open SAS Decision Manager:
- After logging in, click on the Applications menu (often represented by a grid or menu icon).
- Select SAS Decision Manager or SAS Intelligent Decisioning from the list of available applications.

Step 2: Publish the Decision Flow

Open Your Decision Flow:
- In SAS Decision Manager, navigate to the Decisions or Decision Flows section.
- Locate your decision flow in the appropriate folder.
- Click on the decision flow to open it in the Decision Flow Designer.
Validate the Decision Flow:
- In the designer, click on the Validate button to ensure there are no errors or warnings.
- Address any issues that the validation process identifies.
Publish the Decision Flow:
- Click on the Publish button (usually found in the toolbar).
- In the Publish Decision dialog:
  - Name: Provide a unique name for the published decision flow.
  - Version: Assign a version number (e.g., 1.0).
  - Description: Optionally, add a description for future reference.
  - Publishing Destination: Choose Micro Analytic Service. This destination allows the decision flow to be executed as a REST API.
- Permissions:
  - Ensure that the decision flow is published to a folder that grants appropriate access permissions to users who will consume the API.
- Click Publish to deploy the decision flow.

Step 3: Retrieve the Published Service Information

Access the SAS Micro Analytic Service (MAS):
- Return to the SAS Drive or home page.
- Open the SAS Environment Manager from the Applications menu.
Locate the Deployed Module:
- In SAS Environment Manager, navigate to Micro Analytic Service under the Services tab.
- Find the module corresponding to your published decision flow.
- Note the Module Name and Module URI, which will be used to construct API calls.

Step 4: Understand the REST API Endpoint Structure

The REST API endpoint for your decision flow typically follows this structure:

POST https://<your-viya-server>/microanalyticScore/modules/<moduleName>/steps/execute

<your-viya-server>: The base URL of your SAS Viya environment.
<moduleName>: The name of your published decision flow module.

Step 5: Authenticate with SAS Viya

Obtain OAuth Client Credentials:
- Ensure you have the client ID and client secret needed for OAuth authentication. By default, SAS provides a client (sas.ec) for testing, but for production use, it's recommended to create a dedicated client.
Request an Access Token:
- Use the OAuth password grant type to obtain an access token.

Example curl command:

   curl -k -X POST "https://<your-viya-server>/SASLogon/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -u "<client_id>:<client_secret>" \
     -d "grant_type=password&username=<your_username>&password=<your_password>"

Replace placeholders with your actual client ID, client secret, username, and password.
The -k flag allows insecure server connections when using SSL (useful during testing).

Extract the Access Token:
- The response will be a JSON object containing the access_token, token_type, expires_in, and other fields.
- Copy the access_token value for use in subsequent API calls.

Step 6: Test the REST API Endpoint

Prepare the Input Payload:
- Create a JSON object that includes the inputs required by your decision flow.
- The structure should match the input schema defined in your decision flow.

Example:

   {
     "inputs": {
       "age": 30,
       "income": 60000
     }
   }

Make a POST Request to the API Endpoint:

Example using curl:

   curl -k -X POST "https://<your-viya-server>/microanalyticScore/modules/<moduleName>/steps/execute" \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
           "inputs": {
             "age": 30,
             "income": 60000
           }
         }'

Ensure that the Authorization header includes the Bearer token.
Replace <moduleName> with your module's name and update the input data as necessary.

Validate the Response:
- A successful response will contain the outputs defined by your decision flow in JSON format.
- Review the outputs to confirm that the decision flow is executing correctly.

Step 7: Secure the API

Set Up Access Controls:
- In SAS Environment Manager, you can manage permissions for the deployed module.
- Navigate to the module's details and adjust permissions under the Authorization tab.
- Grant or restrict access to users or groups as required.
Configure HTTPS and Certificates:
- Ensure that your SAS Viya environment uses HTTPS to encrypt data in transit.
- Install valid SSL certificates to avoid security warnings and to protect sensitive data.

Step 8: Integrate the API with External Systems

Choose a Programming Language:
- Select a language or framework that suits your application (e.g., Python, Java, .NET, JavaScript).
Example Integration in Python:

   import requests

   # Endpoint and credentials
   url = "https://<your-viya-server>/microanalyticScore/modules/<moduleName>/steps/execute"
   access_token = "<access_token>"

   # Headers
   headers = {
       "Authorization": f"Bearer {access_token}",
       "Content-Type": "application/json"
   }

   # Input data
   data = {
       "inputs": {
           "age": 30,
           "income": 60000
       }
   }

   # Make the request
   response = requests.post(url, json=data, headers=headers, verify=False)

   # Check the response
   if response.status_code == 200:
       print("Success:", response.json())
   else:
       print("Error:", response.status_code, response.text)

The verify=False parameter can be omitted if SSL certificates are properly configured.
Handle exceptions and errors appropriately in production code.

Step 9: Monitor and Manage the API

Monitor Usage:
- Use SAS Environment Manager to monitor the performance and usage statistics of your decision flow APIs.
- Check for metrics such as request counts, response times, and error rates.
Update Decision Flows:
- When making changes to the decision flow logic:
  - Update the decision flow in SAS Decision Manager.
  - Re-validate and re-publish the flow.
  - Existing API endpoints will reference the updated decision flow, assuming the module name remains the same.
Version Control:
- For significant changes, consider versioning your decision flows and APIs.
- Update the module name or use version numbers to distinguish between different iterations.

Troubleshooting Tips

Authentication Errors:
- Ensure the access token is valid and has not expired.
- Confirm that the client ID and secret are correct.
- Check user permissions in SAS Viya.
Input Schema Mismatch:
- Verify that the input JSON matches the expected structure and data types defined in your decision flow.
- Use the input/output schema information from the module details for reference.
HTTP Errors:
- 400 Bad Request: Indicates malformed input data.
- 401 Unauthorized: Authentication failure; check your access token.
- 403 Forbidden: Insufficient permissions to access the module.
- 404 Not Found: Incorrect endpoint URL or module name.
SSL Certificate Issues:
- If you receive SSL errors, ensure that your environment's SSL certificates are correctly installed.
- Avoid using verify=False in production due to security risks.

Documentation and Support

Official SAS Documentation:
- SAS Viya Administration
- SAS Micro Analytic Service Programming and Administration Guide
SAS Support:
- For technical assistance, visit SAS Technical Support and provide details about the issue you're encountering.

Conclusion

By following this guide, you can successfully expose your SAS Decision Manager or SAS Intelligent Decisioning decision flows as RESTful APIs in SAS Viya. This capability allows for real-time decisioning within external applications, enhancing your organization's agility and responsiveness to business needs.

Note: The information in this guide is accurate as of October 2023. Always refer to the latest SAS documentation and consult with your SAS administrator for environment-specific configurations.