Search Objects

A search must be performed in two steps. First a SearchReplace object is submitted. This stores and validates the search. Second, the search can be executed returning a SearchResults.

The SearchReplace Object

Example:

{
  "returnOptions": 2,
  "approvedList": ["nolgtvh8-5701-11ea-a2b4-186590ccb76d"],
  "submittedList": ["x129vvh8-5701-11ea-a2b4-186590ccb76d"],
  "searchCriteria": [
    {
      "objectType": 1,
      "value": "test",
      "searchOptions": 1
    }
  ]
}

Member	Description
returnOptions	Specifies what needs to be returned. See the table below.
searchCriteria	An array of SearchCriteria objects that limit the search. See the object definition below.
approvedList	The list of approved workflows to search. If empty, null or not supplied, all submitted and approved workflows will be searched.
submittedList	The list of submitted workflows to search. If empty, null or not supplied, all submitted and approved workflows will be searched.

returnOptions

The returnOptions are a bitmask of the following.

Value	Description
1	Include the entire workflow in the results. Otherwise, the workflow object will be omitted.
2	Include only submitted workflows.
4	Include only approved workflows.
8	Include application state info.
16	If the result is a system, include all applications that are contained by it.
32	Include the dependency objects that caused the search to match.
64	Include all expanded dependencies.

approvedList and submittedList

The list of approved or submitted workflows to search. If neither are supplied, all submitted and approved workflows are searched. If present and searchCriteria is empty or null, all workflows present in these lists are matched.

The SearchCriteria Object

When supplied, the search criteria limit the result set to those workflows that match ALL of the specified criteria.

Example:

{
  "objectType": 1,
  "value": "test",
  "key": "hostname",
  "searchOptions": 1
}

Member	Description
objectType	Specifies the kind of object within the workflow that is being searched.
value	Specifies the value of the object. searchOptions describe the matching method.
key	The key must be present for some searches depending on the objectType.
searchOptions	Describes how the search should be performed.

objectType

The following are the possible values for objectType.

Value	Description
1	Workflow. Search for workflows that reference the workflow specified in value.
2	User. Search for workflows that reference the user specified in value.
3	Calendar. Search for workflows that reference the calendar specified in value.
4	Asset. Search for workflows that reference the asset specified in value.
7	Endpoint. Search for workflows that reference the endpoint specified in value.
8	Group. Search for workflows that reference the situate group specified in value.
10	Timezone. Search for workflows that reference the timezone specified in value.
11	Editor type. Search for workflows of a particular editor type matching value. This allows you to find only applications or only process workflows, etc.
12	Workflow Group. Search for workflows contained in the workflow group specified in value.
13	Tags. Search for workflows having certain tags and/or tag values. See below.
14	Command. Search for workflows having remote command tasks with commands matching value.
15	Trigger Variables. Search for workflows having a trigger variable matching key with a value matching value.
16	Workflow Name. Find workflows whose id or name matches value.
17	File or Directory Name. Find workflows whose file or directory path matches value.
18	Other Expanded. Find workflows that contain an expanded field not otherwise categorized that matches value.
19	Parameters. Find workflows that have passed parameters to a child workflow matching value.
20	Windows Service. Find workflows whose id or name matches a windows service indicated by value.

value

The value is a string to search for. The searchOptions describes how the value is used to match parts of workflow objects.

key

Sometimes there are multiple workflow elements of the same objectType. For example, there may be many trigger variables and you may want to specify which specific trigger variable you want to search. In this case, the key will be used to match the variable name.

searchOptions

The following are the possible values for searchOptions.

Value	Description
0	ID EXACT. value is a string that must exactly match the object's id.
1	NAME EXACT. value is a string that must exactly match the object's name.
2	NAME SUBSTRING. value is a string that must be contained in the object's name.
3	REGEX. value is a regular expression that must match the object's name.

Special Searching of Tags

The tags field normally contains simple words like ABC, DEF. When matching these, one can specify a criteria of objectType 13 and searchOptions to match ABC or DEF. However, often it is desired to treat the tags as key/value pairs. If you specify a tag that contains an '=' sign, it is assumed the left of the '=' is a key and the right is a value. For example, X=Y. When searching for this, one can specify an objectType of 13 and specify the optional key in the SearchCriteria. value will then only match against values where key matches the key. In this case, value would match against "Y".

---

The SearchResults Object

The results of a search are a search results object.

{
  "results": [
    {
      "id": "abcdefghi-abce-abcd-abadfasdfefa1",
      "queueState": 1,
      "workflow": "..."
    },
    {
      "id": "xyzabcghi-abce-abcd-abadfasdfefa1",
      "queueState": 1,
      "workflow": "...",
      "applicationState": "...",
      "dependencies": "...",
      "extendedDependencies": "...",
      "applicationData": "..."
    }
  ],
  "nApprovedFound": 2,
  "nApprovedSearched": 1321,
  "nSubmittedFound": 0,
  "nSubmittedSearched": 95,
  "nReplaced": 0
}

Member	Description
id	The id of the workflow
queueState	The queue state. 0 = submitted, 1 = approved
workflow	If '1' is among the bitmap in returnOptions, workflow will be included and set to the body of the entire workflow.
applicationState	If '8' is among the bitmap in returnOptions, the application state object below is also returned if the matching workflow is an application.
applications	If '1' is NOT among the bitmap in returnOptions and the matched workflow is an application, an ApplicationData object is also returned in the applicationData field. If '1' is among the bitmap in returnOptions, the ApplicationData object will be part of the returned workflow.
dependencies	If '32' is among the bitmap in returnOptions the set of DependencyObjects that caused the workflow to match the search criteria are returned.
extendedDependencies	If '64' is among the bitmap in returnOptions the entire set of DependencyObjects for each matched workflow is returned. These dependencies may or may not have played a role in the workflow matching the search criteria.

The statistics in the results show how many submitted and approved workflows were searched and how many results were returned.

---

The ApplicationState Object

{
  "applicationState": {
    "clazz": "com.xona.situate.Attributes",
    "sysdStarted": 1581102025000,
    "sysdStarted_mts": 13,
    "sysdExited": 1581102146000,
    "sysdExited_mts": 13,
    "sysdActiveActions": "",
    "sysdExitSignal": 0,
    "sysdLogDir": "/opt/situate/logs/tasklogs/8hnhipn6-ig66-1hea-8a5e-dbb62a45ddc3",
    "sysdAssetId": "nrrolh4s-1dd9-11ea-9387-bf14fcc5c1f8",
    "sysdCanManuallyRun": true,
    "sysdCannotStartWhy": "",
    "sysdAssetName": "testsrv7",
    "sysdExpectedState": 1,
    "sysdExitStatus": 0,
    "sysdActualState": 2,
    "sysdPid": 89916,
    "sysdCondition": 2
  }
}

The sysdExpectedState is the expected state of the application. The sysdActualState is the actual state of the application. When the expected state does not equal the actual state, something is wrong.

State Values

State	Description
-1	Not established. The application has just been created.
0	Unknown. Situate is trying to establish the state of the application
1	Running
2	Stopped
3	Failed. The application was running but has failed.
4	Not Implemented. The asset does not support applications and systems.

sysdSubState Values (since Situate 2.0.1)

State	Description
1	Initializing. The application is running but has not met the monitoring requirements to be declared available.
2	Available. The application is running and has met monitoring requirements to be declared fully available and ready.
3	Unavailable. The application is running but has failed to meet monitoring requirements.

---

The ApplicationData Object

{
  "applicationData": {
    "clazz": "com.xona.wf.AppAuxData",
    "logDir": "...",
    "assetId": "XonaServer",
    "assetName": "XonaServer",
    "parameters": [
      {
        "variable": "a value",
        "value": "value of a"
      }
    ]
  }
}

Application data provides information about the application, including where its logfile is, what asset it runs on and the parameters that were last passed to it on startup.

---

The DependencyObject

Dependencies record what parts of a workflow match the criteria supplied.

{
  "objType": 6,
  "entity": 1,
  "workflowObjectClass": "com.xona.wf.task.ApplicationTask",
  "workflowObjectName": "Task_3",
  "objectId": "7encltss-a4e6-11e9-aa39-186590ccb76d",
  "objectName": "A2"
}

Field	Description
objType	The objType field contains the same values as objectType in the search criteria. It describes the kind of thing, such as a remote command, an application, user or asset that is being reported about.
entity	The entity is the thing that contains or references the item in objType.
workflowObjectClass	The specific kind of workflow object from entity. This is an internal Situate classname
workflowObjectName	The name of the workflow object that contains or references the item.
objectId	The ID of the matched object.
objectName	The name of the matched object.
unexpandedValue	The unexpanded objectName.

Entity Values

Entity Value	Description
1	Task
2	Triggers
3	Edge
4	Annotation
5	Refiner
6	Workflow
7	The notification part of the workflow