Introduction

The REST API allows programmatic access to Situate™ automation software server. To use the REST API, you will need a login and password just as if you were logging into the Situate Viewer. Use of SSL is supported and strongly encouraged as communications into Situate can be configured to initiate outside corporate firewalls. The REST API uses cookies to establish session management. Each part of a request and response is meaningful, including the request method (GET/POST, etc.), the individual headers (Location, Content-Type, Accept, etc.), and the response status code (200, 400, 404, etc.). Use of this API assumes a working knowledge of these HTTP components, and general use of RESTful web APIs.

Authentication

The REST API uses a basic authentication scheme based a login and password. User of the API must first authenticate or successfully login, which will return a valid HTTP session is created. The session will contain an authenticated Situate security context, if the login and password are valid. To avoid having to authenticate with every call, the client interface using the REST api must implement the use of cookies. Here is an example using curl:

curl -k -v -H "Content-Type: application/json" -X POST -c cookies.txt -d '{"user":"mylogin","password":"mypassword"}' https://localhost/situate/auth/login

Response Codes

The following response codes apply to all requests. Check each request type in the list below for more response codes specific to that request.

REST api response codes
Status Code Meaning Description
200 OK The request was processed successfully
201 OK Resource was created and processed successfully
204 OK The request was processed successfully, but no data returned. E.g., deleting an object.
400 Bad Request Your request contained invalid or missing data
401 Unauthorized Authentication failed or the authenticated session was not provided
404 Not Found The URI does not match any of the recognized resources, or, if you are asking for a specific resource with an ID, that resource does not exist
415 Unsupported Media Type The Content-Type header is not supported by the REST API
422 Unsupported Media Type The request is well-formed but the content is invalid
500 Internal Server Error The server was unable to process request or downstream system failed

Request and Response Formats

You can specify the formats you want to use for request and response data.

Supported Request Formats

Use the Content-Type header to specify the format your data is in.
  • JSON:application/json
  • XML:application/xml

Supported Response Formats

Use the Accept header to specify the output desired format. Not all resources will support all formats. Please review specific resource for more information.
  • JSON:application/json

Resources

The following resources are available via the REST API. The allowed request methods for each resource are listed below.

Workflow

Description

Returns the list of workflow resources for the given state and queue specified by the query parameters described below. If no query parameters are specified then all workflow resources found in the server will be returned.

Query Parameters
Parameter Data Type Description
state String Can be either submitted or approved
queue String Defines which workflow queue to use. Default is all.

Example Request

curl -k -v -H "Content-Type: application/json" -X GET -b cookies.txt https://localhost/situate/workflows

Description

Returns a workflow resource as specified by the path parameter id. A query parameter can be specified to filter the a submitted or approved version.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflow resource
Query Parameters
Parameter Data Type Description
state String Can be either submitted or approved

Description

Executes a specific workflow resource using the specified trigger name id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflow resource
Query Parameters
Parameter Data Type Description
trigger String The trigger name that will be used to initiate workflow.
Data Parameters
Data Data Type Description
{'item1':'first-item','item2':'second-item'} application/json If executing a workfow that requires parameters passed by the Trigger, a json data structure should be used as the payload.

Example Request

curl -k -v -H "Content-Type: application/json" -X POST -b cookies.txt https://localhost/situate/workflows/m107f6fe-64e5-11e7-80cb-14109fe12bfb?trigger=Trigger_1 -d '{"item1":"first_one","item2":"second_one"}'

Description

Creates and submits a new workflow resource to Situate id.

Description

Approves a workflow resource that is in the submitted state. id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflow resource

Description

Deletes a specified workflow resource in the specified state. id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflow resource
Query Parameters
Parameter Data Type Description
state String Can be either submitted or approved

Workflow Instance

Description

Returns the list of workflowInstance resources for the given state and queue specified by the query parameters described below. If no query parameters are specified then all workflowInstance resources found in the server will be returned.

Query Parameters
Parameter Data Type Description
state String Can be one of running, canceling or unconfirmed
queue String Defines which workflow queue to use. Default is all.

Description

Returns a workflowInstance resource as specified by the path parameter id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflowInstance resource

Description

Cancels a workflowInstance resource that is in the running state. id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflowInstance resource

Description

Deletes a specified workflowInstance resource in the specified state. id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflowInstance resource

Workflow Log

This resource represents the log of a workflow that has completed. Through this resource, you can retrieve a list of all workflows that run to completion.

You can also use it to get the play-by-play of a specific past workflow. This allows you to see exactly what occurred during the executiong of the workflow.

Description

Retrieves a list of workflow logs for a given time period, e.g., today, yesterday, past 4 hours. The default = today.

Query Parameters
Parameter Data Type Description
queryType Number Defines the time period for the query. Default is today. Other queryType values:
today = Today, e.g., 12:00:01 - current time.
yesterday = Yesterday, previous day.
L24 = Last 24 hours from current time.
L1 = Last 1 hour from current time.
L4 = Last 4 hours from current time.
L8 = Last 8 hours from current time.
L12 = Last 12 hours from current time.
L48 = Last 48 hours from current time.
LW = Last week from current time.
LM = Last month.
L60 = Last 60 days from current time.
custom = Custom dates. See Attributes for more information on additional filters.

Example Request

curl --insecure -v -H "Content-Type: application/json" -X GET -b /tmp/cookies.txt https://localhost/situate/workflowLogs?queryType=today

Additional or custom filters can also be passed to allow for more specific or fine grained queries. These filters are passed via an Attributes JSON object that comes across in the calls payload.

Attributes
Attribute Data Type Required Description
caseSensitive Boolean NO Should search be case sensitive. true | false Default is true.
exactMatch Boolean NO Should search match workflow name exactly? true | false Default is true.

Description

Returns the list of workflow log entries for the given workflow instance specified by the query parameters described below. If no query parameters are specified then the workflow log entries start at index 0.

Query Parameters
Parameter Data Type Description
start String Defines the offset index to start getting workflow log entries. Default is 0, i.e., the beginning of log.

Example Request

curl --insecure -v -H "Content-Type: application/json" -X GET -b /tmp/cookies.txt https://localhost/situate/workflowLogs/j898301e-fae8-11e7-a3c5-14109fe12bfb/89gd66ia-faef-11e7-95c4-14109fe12bfb

Workflow Groups

Description

Returns the list of workflow groups. The returned list can be filtered by passing one or more of the objects attributes and matchings value as parameters. All workflow groups are returned by default.

Query Parameters
NONE

Example Request

curl --insecure -v -H "Content-Type: application/json" -X GET -b /tmp/cookies.txt https://localhost/situate/workflowGroups

Description

Returns a specified group and its attributes.

Query Parameters
NONE

Example Request

curl --insecure -v -H "Content-Type: application/json" -X GET -b /tmp/cookies.txt https://localhost/situate/workflowGroups/

Description

Create a group.

Attributes
Attribute Data Type Required Description
id String NO Defines the globally unique id for the workflow group.
name String YES Defines the logical name of the group.
description String NO Adds a description for the group
parentId String NO Defines the parent group. If not defined, the new group is added to the root Master
Query Parameters
NONE

Example Request

curl --insecure -v -H "Content-Type: application/json" -X POST -b /tmp/cookies.txt https://localhost/situate/workflowGroups/

Description

Deletes a specified group and its attributes. Note deleting a group will also delete its contents, i.e., workflows.

Query Parameters
NONE

Example Request

curl --insecure -v -H "Content-Type: application/json" -X DELETE -b /tmp/cookies.txt https://localhost/situate/workflowGroups/

Workflow Trigger

This is a sub-resource and represents the trigger of a workflow resource. The trigger resource can only exist within the context of a workflow resource. It can be used to enable or disable the way a workflow can be exectued.

Description

Enables or disables trigger resource for a given workflow.

Path Parameters
Parameter Data Type Description
id String Defines the unique name for the trigger resource
Query Parameters
NONE

The payload carries the set of properties that will either enable or disable a trigger resource.

Attributes
Attribute Data Type Required Description
action String YES enable
enable Boolean YES Can be either true or false

Example Request

curl --insecure -v -H "Content-Type: application/json" -X PATCH -b /tmp/cookies.txt https://localhost/situate/workflows/676fsb98-5850-11e8-bf16-14109fe12bfb/triggers/myTriggerName -d '{"action":"enable", "enable":true}'

Workflow Queue

This resource represents the scheduling queue of the workflow engine. The schedule queue makes sure that workflows with schedule triggers are properly executed a the precise date, times and rules. With the REST endpoint this resource retrieve queue information and can be used to enable or disable the schedule queue.

Description

Returns the list of workflow queue resources.

Query Parameters
NONE

Example Request

curl -k -v -H "Content-Type: application/json" -X GET -b cookies.txt https://localhost/situate/workflowQueues

Description

Pause or enable queue specific queue in the workflow manager.

Path Parameters
Parameter Data Type Description
name String Defines the unique name for the queue resource, e.g., Master
Query Parameters
NONE

The payload carries the set of properties that will either pause or enable a queue.

Attributes
Attribute Data Type Required Description
paused Boolean YES Can be either true or false

Example Request

curl --insecure -v -H "Content-Type: application/json" -X PATCH -b /tmp/cookies.txt https://localhost/situate/workflowQueues/Master -d '{"paused":true}'

Language Integration

REST API's by nature are language neutral. However, we have included examples here to help developers get started quickly and with ease.

Example

curl -k -v -H "Content-Type: application/json" -X POST -b cookies.txt https://localhost/situate/workflows/m107f6fe-64e5-11e7-80cb-14109fe12bfb?trigger=Trigger_1 -d '{"item1":"first_one","item2":"second_one"}'

Example


import requests

# This is required because request does not always properly set Content-Type
headers = {'Content-type': 'application/json', 'Accept': 'application/json'}


# This performs a login. The resulting cookies are passed to all subsequent calls
r1 = requests.post('https://localhost/situate/auth/login', verify=False, headers=headers, json={"user":"dave","password":"x"});

# This fetches the workflow queue -- all workflows
r2 = requests.get('https://localhost/situate/workflows', verify=False, headers=headers, cookies=r1.cookies);

result = r2.json();

# Print workflow names and id's
for wf in result['workflows']:
       print(wf['attrs']['name'] + ' ' + wf['attrs']['id']);


# This execute a workflow, passing variables 'key1' assigned to 'value1'
# The workflow id (asfe8a9a-1328-11e8-af6a-f766c4d068b2) needs to be replaced with your id and trigger must match
# your trigger

r3 = requests.post('https://localhost/situate/workflows/asfe8a9a-1328-11e8-af6a-f766c4d068b2?trigger=Trigger_1', verify=False, headers=headers, cookies=r1.cookies, json={'key1':'value1'});

result = r3.json();
print(result)
                                

Example

                                ___ COMING ___
                            

Example

                                ___ COMING ___
                            

Example

                                ___ COMING ___