Skip to content

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

bash
curl -k -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/workflows

Table of Contents


Workflow

GET /workflows

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

ParameterData TypeDescription
stateStringCan be either submitted or approved
queueStringDefines which workflow queue to use. Default is all.

Example Request

bash
curl -k -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/workflows

GET /workflows/{id}

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

Path Parameters

ParameterData TypeDescription
idStringDefines the globally unique id for the workflow resource

Query Parameters

ParameterData TypeDescription
stateStringCan be either submitted or approved

Response Format

The response format is determined by the Accept header:

Accept HeaderResponse Format
application/json (default)JSON object containing link and workflow properties
application/xmlNative workflow XML document

If no Accept header is specified, JSON is returned by default.

Example Request (JSON)

bash
curl -k -v -H "Accept: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X GET https://<server>/situate/workflows/<workflow-id>

Example Request (XML)

bash
curl -k -v -H "Accept: application/xml" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X GET https://<server>/situate/workflows/<workflow-id>

POST /workflows/{id}

Executes the workflow specified by id using the trigger provided in the query parameter.

Path Parameters

ParameterData TypeDescription
idStringDefines the globally unique id for the workflow resource

Query Parameters

ParameterData TypeDescription
triggerStringThe trigger name that will be used to initiate workflow.

Data Parameters

DataData TypeDescription
{'item1':'first-item','item2':'second-item'}application/jsonIf executing a workflow that requires parameters passed by the Trigger, a JSON data structure should be used as the payload.

Example Request

bash
curl -k -v -H "Content-Type: application/json" -X POST -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/workflows/m107f6fe-64e5-11e7-80cb-14109fe12bfb?trigger=Trigger_1 \
  -d '{"item1":"first_one","item2":"second_one"}'

POST /workflows

Creates and submits a new workflow resource to Situate.

Query Parameters

ParameterData TypeDescription
preserveAcl-When present, the ACL should be preserved on submit. This will fail if the user is not an administrator

Data Parameters

DataData TypeDescription
@/tmp/workflow_name.xmlapplication/xmlA submit takes a payload in the form of a workflow document, i.e., a file

Example Request

bash
curl -k -v -H "Content-Type: application/xml" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X POST -d @/tmp/workflow_name \
  https://<server>/situate/workflows

PUT /workflows/{id}

Updates an existing workflow resource. Use this endpoint to submit changes to a workflow that already exists in the system. The workflow will be placed in the submitted state and must be approved before it can be executed.

Note

The workflow ID in the request body must match the {id} in the URL path.

Path Parameters

ParameterData TypeDescription
idStringDefines the globally unique id for the workflow resource

Data Parameters

DataData TypeDescription
Workflowapplication/xml or application/jsonThe complete workflow document with changes

Example Request (XML)

bash
curl -k -v -H "Content-Type: application/xml" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X PUT -d @/tmp/updated_workflow.xml \
  https://<server>/situate/workflows/m107f6fe-64e5-11e7-80cb-14109fe12bfb

Example Request (JSON)

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X PUT -d @/tmp/updated_workflow.json \
  https://<server>/situate/workflows/m107f6fe-64e5-11e7-80cb-14109fe12bfb

DELETE /workflows/{id}

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

Path Parameters

ParameterData TypeDescription
idStringDefines the globally unique id for the workflow resource

Query Parameters

ParameterData TypeDescription
stateStringCan be either submitted or approved

Example Request

bash
curl -k -v -H "Content-Type: application/xml" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X DELETE https://<server>/situate/workflows/m107f6fe-64e5-11e7-80cb-14109fe12bfb

PATCH /workflows/{id}

Approves or enables a workflow that is in the submitted state. After using POST (create) or PUT (update) to submit a workflow, use PATCH to approve it for execution.

Path Parameters

ParameterData TypeDescription
idStringDefines the globally unique id for the workflow resource

Data Parameters

DataData TypeDescription
WorkflowApproveOptionsapplication/jsonJSON object with approval settings

WorkflowApproveOptions

PropertyData TypeDescription
approveWorkflowBooleanSet to true to approve the workflow
enableWorkflowBooleanSet to true to enable the workflow for execution

Example Request

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X PATCH -d '{ "approveWorkflow": true, "enableWorkflow": true }' \
  https://<server>/situate/workflows/m107f6fe-64e5-11e7-80cb-14109fe12bfb

Workflow Instance

GET /workflowInstances

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

ParameterData TypeDescription
stateStringCan be one of running, canceling or unconfirmed
queueStringDefines which workflow queue to use. Default is all.

GET /workflowInstances/{id}

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

Path Parameters

ParameterData TypeDescription
idStringDefines the globally unique id for the workflowInstance resource

PUT /workflowInstances/{id}

Cancels a workflowInstance resource that is in the running state.

Path Parameters

ParameterData TypeDescription
idStringDefines the globally unique id for the workflowInstance resource

DELETE /workflowInstances/{id}

Deletes a specified workflowInstance resource in the specified state.

Path Parameters

ParameterData TypeDescription
idStringDefines 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 execution of the workflow.

GET /workflowLogs

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

Query Parameters

ParameterData TypeDescription
queryTypeNumberDefines the time period for the query. Default is today.

queryType Values

ValueDescription
todayToday, e.g., 12:00:01 - current time
yesterdayYesterday, previous day
L24Last 24 hours from current time
L1Last 1 hour from current time
L4Last 4 hours from current time
L8Last 8 hours from current time
L12Last 12 hours from current time
L48Last 48 hours from current time
LWLast week from current time
LMLast month
L60Last 60 days from current time
customCustom dates. See Attributes for more information on additional filters.

Example Request

bash
curl --insecure -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/workflowLogs?queryType=today

Attributes (Additional Filters)

AttributeData TypeRequiredDescription
caseSensitiveBooleanNOShould search be case sensitive. true or false. Default is true.
exactMatchBooleanNOShould search match workflow name exactly? true or false. Default is true.

GET /workflowLogs/{workflowId}/

Returns the list of workflow log entries for the given workflow instance specified by the path parameters. The optional start query parameter controls the offset index; if not specified, entries start at index 0.

Query Parameters

ParameterData TypeDescription
startStringDefines the offset index to start getting workflow log entries. Default is 0, i.e., the beginning of log.

Example Request

bash
curl --insecure -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/workflowLogs/j898301e-fae8-11e7-a3c5-14109fe12bfb/89gd66ia-faef-11e7-95c4-14109fe12bfb

Workflow Groups

GET /workflowGroups

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

Example Request

bash
curl --insecure -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/workflowGroups

GET /workflowGroups/{groupId}

Returns a specified group and its attributes.

Example Request

bash
curl --insecure -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/workflowGroups/{groupId}

POST /workflowGroups

Create a group.

Attributes

AttributeData TypeRequiredDescription
idStringNODefines the globally unique id for the workflow group.
nameStringYESDefines the logical name of the group.
descriptionStringNOAdds a description for the group
parentIdStringNODefines the parent group. If not defined, the new group is added to the root Master

Example Request

bash
curl --insecure -v -H "Content-Type: application/json" -X POST -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/workflowGroups/

DELETE /workflowGroups/{groupId}

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

Example Request

bash
curl --insecure -v -H "Content-Type: application/json" -X DELETE -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/workflowGroups/{groupId}

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 executed.

PATCH /workflows/{id}/triggers

Enables or disables a trigger resource for a given workflow.

Path Parameters

ParameterData TypeDescription
idStringThe unique identifier for the workflow

Attributes

AttributeData TypeRequiredDescription
actionStringYESenable
enableBooleanYESCan be either true or false

Example Request

bash
curl --insecure -v -H "Content-Type: application/json" -X PATCH -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/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 at the precise date, times and rules. With the REST endpoint this resource retrieves queue information and can be used to enable or disable the schedule queue.

GET /workflowQueues

Returns the list of workflow queue resources.

Example Request

bash
curl -k -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/workflowQueues

PATCH /workflowQueues/{name}

Pause or enable a specific queue in the workflow manager.

Path Parameters

ParameterData TypeDescription
nameStringDefines the unique name for the queue resource, e.g., Master

Attributes

AttributeData TypeRequiredDescription
pausedBooleanYESCan be either true or false

Example Request

bash
curl --insecure -v -H "Content-Type: application/json" -X PATCH -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/workflowQueues/Master \
  -d '{"paused":true}'

Audit Log

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

GET /auditlog

Returns the list of audit log entries.

Example Request

bash
curl -k -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/auditlog

Asset

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

GET /assets

Returns the list of asset resources managed by Situate.

Query Parameters

ParameterData TypeDescription
groupNameStringIf supplied, limits the search to members of the supplied asset group name. A path such as dev/chicago may be supplied.
groupIdStringIf supplied, limits the search to members of the supplied asset group id.

Example Request

bash
curl -k -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/assets

# OR with groupName filter
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X GET https://<server>/situate/assets?groupName=dev/chicago

GET /assets/{id}

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

Path Parameters

ParameterData TypeDescription
idStringThe unique id of the asset.

Example Request

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X GET https://<server>/situate/assets/{id}

POST /assets

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.

Data Parameters

DataData TypeDescription
AssetDataapplication/jsonAdding an Asset takes a payload in the form of a JSON string

Example Request

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{payload}' -X POST https://<server>/situate/assets

DELETE /assets/{assetId}

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

ParameterData TypeDescription
idStringThe unique id of the asset.

Example Request

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X DELETE https://<server>/situate/assets/tllppct2-ku0e-11ea-a73e-6f7bf2de1dcb

The Asset Object

Attributes

Parameter NameDescription
distroThe operating system distribution version
agentBuildThe Situate agent versions build instance
agentIdThe unique id that defines the agent
agentUpdateThe Situate agent update/patch version number
releaseThe asset's kernel version
ipAddressThe asset's IP address
descriptionThe asset's user-defined description
archTagThe asset's architecture type as discovered by Situate
hostnameThe asset's hostname
portThe tcp port that Situate uses to send events
machineThe architecture type for the asset
sysnameThe OS type: E.g., Linux, Windows
ftPortThe tcp port that Situate uses to send data
nameThe asset's user-defined name
agentVersionThe Situate software version
idThe unique id that represents this asset in Situate

JSON Response Example

json
{
  "link": {
    "clazz": "com.xona.web.model.Link",
    "rel": "self",
    "href": "https://<server>/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",
        "release": "3.10.0-123.el7.x86_64",
        "ipAddress": "10.2.5.48",
        "description": "xonalocal11",
        "archTag": "Linux-RedHat-2.6-x86_64-64",
        "hostname": "xonalocal11",
        "port": 14000,
        "machine": "x86_64",
        "sysname": "Linux",
        "ftPort": 14001,
        "name": "xonalocal11",
        "agentVersion": "situate-2.0.0",
        "id": "6h0ooo42-259c-11ea-b86c-14109fe12bfb"
      }
    }
  ]
}

Calendar

This resource represents the calendar information for Situate. 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 update an existing calendar.

GET /calendars

Returns the list of calendar resources managed by Situate.

Example Request

bash
curl -k -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: YOUR_API_KEY' \
  https://<server>/situate/calendars

GET /calendars/{id}

Returns the calendar resource specified by {id}.

Path Parameters

ParameterData TypeDescription
idStringThe unique id of the calendar.

Example Request

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X GET https://<server>/situate/calendars/{id}

POST /calendars

Add or update a calendar resource.

Data Parameters

DataData TypeDescription
TraditionalCalendarapplication/jsonAdding a calendar takes a payload in the form of a JSON-encoded TraditionalCalendar

PUT /calendars/{id}

Update a calendar resource.

Path Parameters

ParameterData TypeDescription
idStringThe unique id of the calendar.

Data Parameters

DataData TypeDescription
TraditionalCalendarapplication/jsonUpdating a calendar takes a payload in the form of a JSON-encoded TraditionalCalendar

Example Request

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{payload}' -X PUT https://<server>/situate/calendars/{calendarId}

DELETE /calendars/{id}

Delete a calendar resource.

Note

Removing calendars will send an event to all scheduled workflows to regenerate schedules.

Path Parameters

ParameterData TypeDescription
idStringThe unique id of the calendar.

Example Request

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X DELETE https://<server>/situate/calendars/{calendarId}

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

Step 1: Submit Search Query

In step 1, the query is stored on the Situate server and validated.

POST /searches

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

DataData TypeDescription
SearchReplaceapplication/jsonCreating a search takes a payload that contains search criteria

Example Request

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{payload}' -X POST https://<server>/situate/searches

Step 2: Execute Search Query

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

POST /searches/{id}

Perform a query that was previously submitted.

Path Parameters

ParameterData TypeDescription
idStringDefines the unique name for the search resource.

Example Request

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

For detailed information about the SearchReplace object, SearchCriteria, and SearchResults, see Search Objects.


System

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

GET /system/statistics

Get the system's statistics.

Properties

PropertyDescription
activeNumber of currently active workflows.
approvedNumber of currently approved workflows that can be executed.
assetsNumber of currently registered assets being managed in Situate.
daysOfLogsToKeepThe number of default days that logs are kept. NOTE: This parameter is not specified by workflow and task
domainThe name of the Situate domain.
executedThe number of workflows executed since last system startup.
startDateTimeRepresents the time the Situate server was last started. Value is represented in milliseconds
submittedThe number of workflows submitted and waiting to be approved for execution.
unconfirmedThe number of workflows executed that require attention/confirmation.
usersThe number of users registered within Situate
versionThe Situate server version.

Example Request

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X GET https://<server>/situate/system/statistics

GET /system/situate-properties

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

Example Request

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X GET https://<server>/situate/system/situate-properties

PUT /system/alert-integration-reset

Resets all alerts - removing any active alerts.

Example Request

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X PUT https://<server>/situate/system/alert-integration-reset

POST /system/help-report

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

Example Request

bash
curl -k -v -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -X POST https://<server>/situate/system/help-report

Language Integration

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

Python Example

python
import requests

# Set up headers with API key authentication
headers = {
    'Content-type': 'application/json',
    'Accept': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
}

# Fetch all workflows
r1 = requests.get('https://<server>/situate/workflows',
                  verify=False, headers=headers)

result = r1.json()

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

# Execute a workflow, passing variables 'key1' assigned to 'value1'
# The workflow id needs to be replaced with your id and trigger must match your trigger
r2 = requests.post('https://<server>/situate/workflows/asfe8a9a-1328-11e8-af6a-f766c4d068b2?trigger=Trigger_1',
                   verify=False, headers=headers,
                   json={'key1':'value1'})

result = r2.json()
print(result)

Workload Automation and Orchestration