Execute a task

post/tasks

This endpoint is used to execute a task, a program that executes within a few seconds and is safe to interrupt or re-submit. The request contains the program and arguments - variables used by the program or by the service to alter how the program is run. Submitting the request triggers the service to establish a session, submit the program to the session, wait for the program to complete, and return any requested output. The response contains the status of the task and any output requested.

Request Samples

Response Samples


1{
2  "id": "4c6775e3-50f3-4c72-80a3-a7e1069876dc",
3  "name": "Hello World",
4  "description": "This task creates html output which says Hello to the name stored in the MYNAME argument.",
5  "state": "completed",
6  "jobConditionCode": 0,
7  "creationTimeStamp": "2016-05-20T16:16:10Z",
8  "elapsedTime": 225,
9  "contextId": "ea0d3ee1-894f-4936-bc2b-f611a878a0dd",
10  "contextName": "MySampleContext",
11  "sessionId": "c1a108bb-6019-4876-807f-eeac467b9c0",
12  "jobId": "71fc2eae-272c-45b4-aaf7-76f6cf259400",
13  "variables": {
14    "GLOBAL_MYNAME": "John"
15  }
16}

Request Body

The request body contains the program to execute and any arguments that are needed by the program or by the service to alter how the program is executed. If using multipart/form-data the request can also include input files.

Provides an object that you use to execute a task.

Name Type Required Description

name

string

false

Specifies an optional name that is associated with this task.

description

string

false

Specifies an optional description for this task.

code

string

true

Specifies the program to be executed. Each line should be separated by a new line character (\n, \r, or \r\n). For example, "data _null_;\ncall sleep(1, 60);\nrun;".

arguments

object

true

Specifies a map of string keys and string values used as variables for the program or as instructions on how to execute the program.

Variables Usage: If your program expects a variable, you can provide it here. For example, if your program expects the variable myVar, you can provide it here as "myVar": "myValue".

Altering Program Execution: Arguments can also be used to alter how the service executes the task. For instance, what context to create the session on or what output to return. Make sure that an argument indicating what session or context the service should use is included. For example, if you have already created a session and want the task to execute on your session, you should provide the _sessionId argument where the value is the ID of your session. Alternatively, if you want to defer the process of creating the session to the service, you can indicate which context you would like the session to be created on by providing the _contextId argument where the value is the ID of the context or the _contextName argument where the value is the name of the context. When specifying a context, the context must be reusable.

For a full list of arguments available to alter the program's execution, refer to the table below.

Argument Name	Description
_contextName	The name of the context to create the session on (must be reusable).
_contextId	The id of the context to create the session on (must be reusable).
_sessionId	The id of an existing session to run the task within.
_addJesBeginEndMacros	If true, the service will add the `%JESBEGIN` and `%JESEND` macros to the beginning and end of the code.
_omitJsonListing	If true, the service will not return the JSON listing. Defaults to false.
_omitTextListing	If true, the service will not return the text listing. Defaults to false.
_omitJsonLog	If true, the service will not return the JSON log. Defaults to false.
_omitTextLog	If true, the service will not return the text log. Defaults to false.
_omitSessionResults	If true, the service will not return the session results. Defaults to true. The default can be configured in the deployment configuration.
_resultFilter	A filter that specifies which results to return. For example if you only want to return the result name '_webout', you can specify the filter as "eq(name,'_webout')".
_variableFilter	A filter that specifies which variables you want returned. For example, if you only want the variable named 'MYNAME', you can specify the filter as "eq(name,'MYNAME')". The value ALL returns all variables. Not specifying the argument returns no variables.

Responses

Status	Meaning	Description
200	OK	The task was executed successfully. The response contains the final status of the job as well as its condition code and any errors that were encountered during the execution.	Schema
400	Bad Request	The request was invalid. This can occur because the request body does not satisfy the schema for application/vnd.sas.compute.task.request. Ensure all the required properties are present and that the values are valid.	Schema
404	Not Found	A resource identified in the request does not exist. For example, the Compute Context or Session identified in the task request does not exist. Refer to the error message for more information.	Schema
415	Unsupported Media Type	The server does not support the media type specified in the Content-Type header. If sending a json body, ensure that the Content-Type header is set to application/vnd.sas.compute.task.request+json. If sending multipart/form-data, ensure that the taskRequest part is first and that its Content-Type header is set to application/vnd.sas.compute.task.request+json.	Schema
504	Gateway Timeout	The request timed out. This can occur if the task takes longer than the timeout value configured in the context or deployment configuration. If you experience this error, consider if the program should be executed using the Job Execution Service instead of this endpoint.	Schema