Using the REST-Based Service to Manage Orchestration Jobs :: SAS(R) Visual Process Orchestration 2.1: User's Guide

Overview of the REST-Based Service

Representational State Transfer (REST) is a set of architectural principles for designing web services that access a system's resources. A resource is accessed with a Uniform Resource Identifier (URI).

When SAS Visual Process Orchestration is installed, a REST-based service is installed on the web server. You can formulate a URI that invokes the service and specifies options for the service. You can then include this URI in a command-line tool in order to run orchestration jobs in batch mode and perform other tasks.

A typical usage scenario for the REST-based service is as follows:

Identify the path to the orchestration job to be run. One way to do this is to navigate to the orchestration job in the SAS Folders tree, and then note the path to the job. Example path: SAS Folders/Shared Data/Subfolder1/Orch Job1
Formulate the URI that is required to run the job. Example URI:
```
http://POWebServer.com/SASProcessOrchestration/rest/executions/run?path=
/Shared%20Data/Subfolder1/Orch%20Job1
```
For more information about the format of this URI, see Example URI to Run an Orchestration Job.
Add the URI that you formulated in Step 2 to a command that can be executed in batch or from the command line. Example cURL command:
```
cURL -v -b --location-trusted -u "ETLGuest:pw1" 
-H "Accept:application/json" -H "Content-Type:application/json"
--url "http://POWebServer.com/SASProcessOrchestration/rest/executions/run?path=
/Shared%20Data/Subfolder1/Orch%20Job1" -X POST 
```
For more information about this cURL command, see Example Command Line to Run an Orchestration Job.
Run the command from Step 3. A response is returned in XML or JSON format.

A response to a REST request is a snapshot of the job’s status when the response was made. To find out what happened with the job after a response is made, you must request the status of the job, as described in the next steps.
Parse the response to obtain the ID of the job. Look for the “id” label in the response. The job ID includes the user name that was used in the command from Step 3. The next display shows a job ID in the context of a response.

Job ID (“id”) in the Context of a Response
Use the job ID from Step 5 to formulate a URI that receives the status of the job while it is running. Example URI:
```
http://POWebServer.com/SASProcessOrchestration/rest/
executions/1375318231:1419:ETLGuest
```
For more information and the executions/{id} command, see Overview of the REST API .
Add the URI that you formulated in Step 6 to a command that can be executed in batch or from the command line. Example cURL command:
```
cURL -v -b --location-trusted -u "ETLGuest:pw1" 
-H "Accept:application/json" -H "Content-Type:application/json"
--url "http://POWebServer.com/SASProcessOrchestration/rest/
executions/1375318231:1419:ETLGuest"
```
In cURL, GET is the default method if there is no specified method. Accordingly, there is no need to specify -X GET for the command above.

Example URI to Run an Orchestration Job

Suppose that you want to execute the orchestration job Orch Job 1 that is shown in the next display.

Orchestration Jobs in a Subfolder of the SAS Folders Tree

The URI to run Orch Job1 would be similar to the following:

http://POWebServer.com/SASProcessOrchestration/rest/executions/run?path=
/Shared%20Data/Subfolder1/Orch%20Job1

The components of the example URI are as follows:

Example URI Components
Component	Description
POWebServer.com	Name of the web server for SAS Visual Process Orchestration. The default port for the web server is port 80. Port 80 is used unless the default port for the web server was changed during installation. If you changed the default web server port, specify that port, like so: POWebServer.com:7880.
/SASProcessOrchestration/rest/	Default path to the folder on the web host that contains the REST-based service.
executions/run?	The executions/run command is used to run orchestration jobs. For a description of the main commands that are used to manage jobs, see Overview of the REST API .
path=	Path to the orchestration job to be executed. Jobs can be stored in any convenient folder in the SAS Folders tree on the SAS Visual Process Orchestration Design Server.
Shared%20Data	The Shared Data folder in the SAS Folders tree. The “%20” characters in this example are used to encode a space in the context of a URI.
Subfolder1	Example subfolder where orchestration jobs are stored. The person who runs the job must have access to the folder.
Orch%20Job1	Name of the orchestration job to be executed.

Example Command Line to Run an Orchestration Job

After you have formulated the URI to execute an orchestration job, you can use a command-line tool to execute it. The tool must be able to handle URIs. cURL (command-line URL) is an open-source tool that can handle URIs. The cURL command to execute Orch Job1 would be similar to the following:

cURL -v -b --location-trusted -u "ETLGuest:pw1" 
-H "Accept:application/json" -H "Content-Type:application/json"
--url "http://POWebServer.com/SASProcessOrchestration/rest/executions/run?path=
/Shared%20Data/Subfolder1/Orch%20Job1" -X POST

Options Used in the Example cURL Command
Option	Purpose
-v	Verbose logging. Used to log as much information as possible if debugging is necessary.
-b	Passes data to the HTTP server as a cookie.
--location-trusted	Sends the user's information to all of the hosts that the site might redirect to. Note: cURL option names that are two or more characters long must be preceded by two hyphens (--). This enables cURL to distinguish between a one-character option name (such as -u) from a multiple character option name (such as --location-trusted).
-u	The user ID and password that are required to run the orchestration job. The user ID that executes an orchestration job must have the RunJobs capability.
-H	An extra header used when retrieving your job. This option enables you to add as many headers as needed. You are also allowed to use this option to overwrite any internal headers that are defaulted if you do not add your own. Note: The response from the job is in XML format unless you specify JSON in the header, as shown in the example cURL command.
--url	The URL to the web service that executes an orchestration job. The `path` is the folder path to the orchestration job on the SAS Visual Process Orchestration Design Server. Note: cURL option names that are two or more characters long must be preceded by two hyphens (--).
-X POST	Specifies which request method you want to use. The POST method is used to execute jobs. GET is the default method if there is no specified method.

For more information about cURL, see their website at http://curl.haxx.se/.

Overview of the REST API

The next table lists the main REST API commands used to manage orchestration jobs.

REST API Commands for Managing Orchestration Jobs
Task	REST API Commands	Method	Optional Parameters
Run orchestration jobs.	"/executions/run"	POST	status - True/false. If true, a status file for this job is kept during execution. Default is false. timeout - Length of time for the client to wait for the run request to respond. served - ID of the SAS Visual Process Orchestration Run-time Server that should run the jobs. If null, then the first run-time server found in the deployment is used. id - The orchestration job ID to execute. path - A SAS Folder path to a job or to a subfolder that contains jobs to be executed. recursive - True/false. If true and the path is a SAS Folder, then all the subfolders are searched. Note: The user ID that executes an orchestration job must have the RunJobs capability. For information about capabilities for orchestration jobs, see Default Groups, Roles, and Capabilities.
Stop an orchestration job that is running.	"/executions/{id}/stop"	POST	timeout - Length of time for the client to wait for the stop request to respond. killprocess - True/false. If true, then a request to immediately terminate the job is issued. If false, then the job is allowed to stop gracefully. waittime - The amount of time (in seconds) for the server to wait for the job to end gracefully before sending back an error. Pass null to use the default. serverid - ID of the SAS Visual Process Orchestration Run-time Server that is running the job. If null, then the first run-time server found in the deployment is used.
Get the status for a single job run, identified by ID.	"/executions/{id}"	GET	path - A path to a SAS Folder or to an orchestration job. If a path is not provided, then the root folder of the SAS Folders tree is assumed. recursive -True/False. If true, then subfolders are also searched. timeout - Length of time for the client to wait for the status request to respond. serverid - ID of the SAS Visual Process Orchestration Run-time Server that should run the jobs. If null, then the first run-time server found in the deployment is used. The following job status codes are returned by the "/executions/{id}" command: COMPLETE, CRASHED, ERROR_UNSPECIFIED, QUEUED, RUNNING, SUBMITTED, UNKNOWN_JOB_STATUS_CODE, USER_TERMINATED.
Get the log for a job identified by ID.	"/executions/{id}/log"	GET	id - ID of the job for which you want the log. timeout - Length of time for the client to wait for the log request to respond. serverid - ID of the SAS Visual Process Orchestration Run-time Server that ran the job. If null, then the first run-time server found in the deployment is used

The IDs that are mentioned in the previous table, such as the orchestration job ID, are returned in XML or JSON format when you issue the "/executions/run" command. You must parse the response to obtain these IDs.