Appearance
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/workflowsTable of Contents
- Workflow
- Workflow Instance
- Workflow Log
- Workflow Groups
- Workflow Trigger
- Workflow Queue
- Audit Log
- Asset
- Calendar
- Search
- System
- Language Integration
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
| 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
bash
curl -k -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: YOUR_API_KEY' \
https://<server>/situate/workflowsGET /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
| 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 |
Response Format
The response format is determined by the Accept header:
| Accept Header | Response Format |
|---|---|
application/json (default) | JSON object containing link and workflow properties |
application/xml | Native 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
| 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 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
| Parameter | Data Type | Description |
|---|---|---|
| preserveAcl | - | 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 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/workflowsPUT /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
| Parameter | Data Type | Description |
|---|---|---|
| id | String | Defines the globally unique id for the workflow resource |
Data Parameters
| Data | Data Type | Description |
|---|---|---|
| Workflow | application/xml or application/json | The 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-14109fe12bfbExample 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-14109fe12bfbDELETE /workflows/{id}
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
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-14109fe12bfbPATCH /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
| Parameter | Data Type | Description |
|---|---|---|
| id | String | Defines the globally unique id for the workflow resource |
Data Parameters
| Data | Data Type | Description |
|---|---|---|
| WorkflowApproveOptions | application/json | JSON object with approval settings |
WorkflowApproveOptions
| Property | Data Type | Description |
|---|---|---|
| approveWorkflow | Boolean | Set to true to approve the workflow |
| enableWorkflow | Boolean | Set 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-14109fe12bfbWorkflow 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
| 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. |
GET /workflowInstances/{id}
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 |
PUT /workflowInstances/{id}
Cancels a workflowInstance resource that is in the running state.
Path Parameters
| Parameter | Data Type | Description |
|---|---|---|
| id | String | Defines the globally unique id for the workflowInstance resource |
DELETE /workflowInstances/{id}
Deletes a specified workflowInstance resource in the specified state.
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 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
| Parameter | Data Type | Description |
|---|---|---|
| queryType | Number | Defines the time period for the query. Default is today. |
queryType Values
| Value | Description |
|---|---|
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
bash
curl --insecure -v -H "Content-Type: application/json" -X GET -H 'X-API-Key: YOUR_API_KEY' \
https://<server>/situate/workflowLogs?queryType=todayAttributes (Additional Filters)
| Attribute | Data Type | Required | Description |
|---|---|---|---|
| caseSensitive | Boolean | NO | Should search be case sensitive. true or false. Default is true. |
| exactMatch | Boolean | NO | Should 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
| 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
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-14109fe12bfbWorkflow 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/workflowGroupsGET /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
| 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 |
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
| Parameter | Data Type | Description |
|---|---|---|
| id | String | The unique identifier for the workflow |
Attributes
| Attribute | Data Type | Required | Description |
|---|---|---|---|
| action | String | YES | enable |
| enable | Boolean | YES | Can 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/workflowQueuesPATCH /workflowQueues/{name}
Pause or enable a 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 |
Attributes
| Attribute | Data Type | Required | Description |
|---|---|---|---|
| paused | Boolean | YES | Can 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/auditlogAsset
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
| 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 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/chicagoGET /assets/{id}
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
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
| Data | Data Type | Description |
|---|---|---|
| AssetData | application/json | Adding 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/assetsDELETE /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
| Parameter | Data Type | Description |
|---|---|---|
| id | String | The 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-6f7bf2de1dcbThe Asset Object
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 asset's kernel version |
| ipAddress | The asset's IP address |
| description | The asset's user-defined description |
| archTag | The asset's architecture type as discovered by Situate |
| hostname | The asset's 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 asset's user-defined name |
| agentVersion | The Situate software version |
| id | The 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/calendarsGET /calendars/{id}
Returns the calendar resource specified by {id}.
Path Parameters
| Parameter | Data Type | Description |
|---|---|---|
| id | String | The 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
| Data | Data Type | Description |
|---|---|---|
| TraditionalCalendar | application/json | Adding a calendar takes a payload in the form of a JSON-encoded TraditionalCalendar |
PUT /calendars/{id}
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 | Updating 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
| Parameter | Data Type | Description |
|---|---|---|
| id | String | The 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}Search
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
| Data | Data Type | Description |
|---|---|---|
| SearchReplace | application/json | Creating 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/searchesStep 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
| Parameter | Data Type | Description |
|---|---|---|
| id | String | Defines 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
| Property | Description |
|---|---|
| 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 of workflows executed since last system startup. |
| startDateTime | Represents the time the Situate server was last started. Value is represented in milliseconds |
| submitted | The number of workflows submitted and waiting to be approved for execution. |
| unconfirmed | The number of workflows executed that require attention/confirmation. |
| users | The number of users registered within Situate |
| version | The 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/statisticsGET /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-propertiesPUT /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-resetPOST /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-reportLanguage 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)