Introduction

The REST API allows programmatic access to Situate™ automation software server. To use the REST API, you will need a login and password or an API key. 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

There are two ways you can authenticate with situate to perform REST operations.

API Keys (since 1.11)

An API key is the easiest way to perform authentication. To setup an API key, from the UI, edit the service account of the user whose security context is to be used. Select "+" under the Principal Identities table to add a new identity. In the "Source" field, select "API Key". A new key will be generated and displayed. Save this key as it is not possible to recover they key the dialog closes. Save the changes. Then, in your REST calls, pass the key as the value of the "X-API-Key" header.

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X GET https://localhost/situate/workflows

Login/Password (Basic Authentication)

The REST API cause use 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.

NOTE: All resources are configured under the web application context path of situate. Therefore, all URI paths should include the context path as follows.

Example

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

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

Example Request

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X GET https://localhost/situate/workflows/<workflow-id>

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.

preserveAcl
Path Parameters
Data Data Type Description
application/xml When present, the ACL should be preserved on submit. This will fail if the user is not an administrator
Data Parameters
Data Data Type Description
@/tmp/workflow_name.xml application/xml A submit takes a payload in the form of an workflow document, i.e., a file

Example Request

curl -k -v -H "Content-Type: application/xml" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X POST -d @/tmp/workflow_name https://localhost/situate/workflows

Description

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

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

Example Request

curl -k -v -H "Content-Type: application/xml" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X PUT https://localhost/situate/workflows/m107f6fe-64e5-11e7-80cb-14109fe12bfb

Description

Deletes a specified workflow resource in the specified state with the given 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

Example Request

curl -k -v -H "Content-Type: application/xml" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X DELETE https://localhost/situate/workflows/m107f6fe-64e5-11e7-80cb-14109fe12bfb

Description

Approves the specified workflow specified by id.

Path Parameters
Parameter Data Type Description
id String Defines the globally unique id for the workflow resource
Data Parameters
Data Data Type Description
WorkflowApproveOptions String A WorkflowApproveObject { "approveWorkflow": false }

Example Request

curl -k -v -H "Content-Type: application/xml" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X PATCH -d '{ "approveWorkflow": true }' https://localhost/situate/workflows/m107f6fe-64e5-11e7-80cb-14109fe12bfb

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}'

Audit Log

This resource represents the auditing information for Situate Workflow Intelligence. The audit service tracks all events that occur. Use this REST endpoint resource to query and retrieve any audit records.

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

Asset

This resource represents the asset information for Situate Workflow Intelligence. The asset service contains all meta-data on an asset. Use this REST endpoint resource to query and retrieve any asset records.

Description

Returns the list of asset resources managed by Situate.

Query Parameters
Parameter Data Type Description
groupName String If supplied, limits the search to members of the supplied asset group name. A path such as dev/chicago may be supplied.
groupId String If supplied, limits the search to members of the supplied asset asset group id.

Example Request

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

OR

curl -k -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' https://localhost/situate/assets?groupName=dev/chicago

OR

curl -k -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' https://localhost/situate/assets?groupId=hn8jj5fe-k8kj-11ea-bfed-8bf277411205

Description

Returns the asset resource indicated by the asset id specified as {id}.

Path Parameters
Parameter Data Type Description
id String The unique id of the asset.

Example Request

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X GET https://localhost/situate/assets/<id>

Description

Add an asset resource to the All group. NOTE: This operation will only work, if the agent software is already installed on the Asset and its security keys have been prepositioned.

Path Parameters
NONE
Query Parameters
NONE
Data Parameters
Data Data Type Description
AssetData application/json Adding an Asset takes a payload in the form of a JSON string

Example Request

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -d {payload} -X POST https://localhost/situate/assets

Description

Delete an asset resource from the All group. NOTE: Removing an asset from the All group will also remove it from any sub-groups

Path Parameters
Parameter Data Type Description
id String The unique id of the asset.

Example Request

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X DELETE https://localhost/situate/assets/tllppct2-ku0e-11ea-a73e-6f7bf2de1dcb

Attributes
Parameter Name Description
distro The operating system distribution version
agentBuild The Situate agent versions build instance
agentId The unique id that defines the agent
agentUpdate The Situate agent update/patch version number
release The assets kernel version
ipAddress The assets ip address
description The assets user defined description
archTag The assets architecture type as discovered by Situate
hostname The assets given hostname
port The tcp port that Situate uses to send events
machine The architecture type for the asset
sysname The OS type: E.g., Linux, Windows
ftPort The tcp port that Situate uses to send data
name The assets user defined name
agentVersion The Situate software version
id The unique id that represents this asset in Situate
JSON Response

                                          { 
   "link":{ 
      "clazz":"com.xona.web.model.Link",
      "rel":"self",
      "href":"https://localhost/situate/assets/xrtest"
   },
   "assets":[ 
      { 
         "clazz":"com.xona.web.api.model.WorkflowResponse",
         "attrs":{ 
            "clazz":"com.xona.situate.Attributes",
            "masq":false,
            "distro":"CentOS Linux release 7.0.1406 (Core)",
            "agentBuild":"22289",
            "agentId":"d6959066-1db6-11ea-a51f-6be415b28b7f",
            "agentUpdate":"4",
            "auth":"PAM-local,H-xonalocal11,H-d6959066-1db6-11ea-a51f-6be415b28b7f",
            "release":"3.10.0-123.el7.x86_64",
            "ipAddress":"10.2.5.48",
            "description":"xonalocal11",
            "archTag":"Linux-RedHat-2.6-x86_64-64",
            "version":"#1 SMP Mon Jun 30 12:09:22 UTC 2014",
            "hostname":"xonalocal11",
            "port":14000,
            "machine":"x86_64",
            "sysname":"Linux",
            "ftPort":14001,
            "name":"xonalocal11",
            "alias":false,
            "agentVersion":"situate-2.0.0",
            "id":"6h0ooo42-259c-11ea-b86c-14109fe12bfb"
         },
         "acl":{ 
            "clazz":"com.xona.situate.Acl",
            "content":"s`Administrator@sit-sit-xona/u`AssetManagers@sit-sit-xona/g```A,owner@BUILTIN/g,Read,Write,Execute`A,groupowner@BUILTIN/u,Read,Write,Execute`A,everyone@BUILTIN/g,Read,Write,Execute"
         },
         "link":{ 
            "clazz":"com.xona.web.model.Link",
            "rel":"xonalocal11",
            "href":"https://localhost/situate/assets/xrtest/6h0ooo42-259c-11ea-b86c-14109fe12bfb"
         }
      }
   ]
}
                                            

Calendar

This resource represents the calendar information for Situate Workflow Intelligence. The calendar service contains the meta-data that represents calendar dates, which can be used in schedules. Use this REST endpoint resource to query and retrieve a list of calendars, a specific calendar or updating an existing calendar.

Description

Returns the list of calendar resources managed by Situate.

Query Parameters
NONE

Example Request

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

OR

curl -k -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' https://localhost/situate/calendars/<id>

Description

Returns the calendar resources specified by {id}.

Path Parameters
Parameter Data Type Description
id String The unique id of the calendar.

Example Request

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

OR

curl -k -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' https://localhost/situate/calendars

Description

Add or update a calendar resource.

Path Parameters
NONE
Query Parameters
NONE
Data Parameters
Data Data Type Description
TraditionalCalendar application/json Adding an Asset takes a payload in the form of a JSON-encoded TraditionalCalendar

Description

Update a calendar resource.

Path Parameters
Parameter Data Type Description
id String The unique id of the calendar.
Data Parameters
Data Data Type Description
TraditionalCalendar application/json Adding an Asset takes a payload in the form of a JSON-encoded TraditionalCalendar

Example Request

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -d {payload} -X PUT https://localhost/situate/calendars/{calendarId}

Description

Delete a calendar resource. NOTE: Removing calendars will send an event to all scheduled workflows to regenerate schedules.

Path Parameters
Parameter Data Type Description
id String The unique id of the calendar.

Example Request

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X DELETE https://localhost/situate/assets/tllppct2-ku0e-11ea-a73e-6f7bf2de1dcb

Search

This resource represents a search utility to perform searches against the Situate Workflow Intelligence server. Performing a search is a two step process:

In step 1, the query is stored on the Situate server and validated. Then in Step 2, the query is executed and the results returned.

Description

Submit a new query to the system. The query is stored and validated. The returned link can be used to perform the search in step 2.

Data Parameters
Data Data Type Description
SearchReplace application/json Creating a search takes a payload that contains search criteria
Query Parameters
NONE

Example Request

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -d {payload} -X POST https://localhost/situate/searches

 

In step 2, the query is executed and the results returned as a QueryResults object.

Description

Perform a query that was previously submitted.

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

Example Request

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -d {payload} -X POST https://localhost/situate/searches/<id>

System

This resource represents a the actual Situate Workflow Intelligence server. It provides functionality to do general maintenance and/or administrative functions to the system.

Description

Get the system's statistics including the following items:

Functions
PropertyDescription
active Number of currently active workflows.
approved Number of currently approved workflows that can be executed.
assets Number of currently registered assets being managed in Situate.
daysOfLogsToKeep The number of default days that logs are kept. NOTE: This parameter is not specified by workflow and task
domain The name of the Situate domain.
executed The number workflows executed since last system startup.
startDateTime Represents the time the Situate server was last started. Value is represented in millisecods
submitted The number workflows submitted and waiting to be approved for execution.
unconfirmed The number workflows executed that require attention/confirmation.
users The number users registered within Situate
version The Situate server version.

Example Request

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X GET https://localhost/situate/system/statistics

Description

Return the set of Situate properties defined on the Situate server. I.e., the file /opt/situate/situate.properties

Path Parameters
NONE
Query Parameters
NONE

Example Request

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X GET https://localhost/situate/system/situate-properties

Description

Resets all alerts - removing any active alerts.

Path Parameters
NONE
Query Parameters
NONE

Example Request

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X PUT https://localhost/situate/system/alert-integration-reset

Description

Submits a help report to XonaSoftware - automatically opening a new ticket.

Path Parameters
NONE
Query Parameters
NONE

Example Request

curl -k -v -H "Content-Type: application/json" -H 'X-API-Key: iJBEar7CakPTa29Zax5CaZVNaYxBaJtNantCa9CWaZQ' -X POST https://localhost/situate/system/help-report