Introduction

The JavaScript workflow API is available to workflows at runtime to provide a rich set of data workflow developers can use to perform various tasks.

Objects

Global

Global objects can be referenced without a containing class.

Description

Run the input string containing javascript, executing it as it would any javascript code.

Return value

undefined

Parameters

Parameter Type Description
Input String The input string.

Description

Returns true if all the variables in all the expressions passed are defined.

Return value

true if all variables used in the expression are defined, false if not.

Parameters

Parameter Type Description
input any One or more expressions

Description

Returns true if all the variables in all the expressions passed are defined.

Return value

true if all variables used in the expression are defined, false if not.

Parameters

Parameter Type Description
input any One or more expressions

Description

A value representing infinity.

Description

A value "not a number"

Description

A value representing an undefined value. For example, int "var x;" x becomes set to 'undefined'.

Asset

An asset is a structure used to track a computer upon which situate can operate. An Asset has an ID that is used to uniquely identify it and a name that is used to as a conventient display name. It also has other data that can be used to identfy the operating system and version as well as other interesting pieces of information.

Description

Returns the public key used to communicate with this asset.

Return value

String

Description

Returns the sysname of this asset. The sysname is the value of "uname -s" on Unix or "Windows" for windows.

Return value

String

Description

Returns OS release. This will be "uname -r" on Unix boxes and the build and patch level on Windows boxes.

Return value

String

Description

Returns the version of the operating system.

Return value

String

Description

Returns the architecture type of this asset. This will be something like x86_64 or i686.

Return value

String

Description

Returns the Distribution name for this asset. On Linux, this will be the specific linux distribution name. On Windows this may be a value like "Windows 2003 R2".

Return value

String

Description

Returns the version of the situate agent running on this asset.

Return value

String

Description

Returns list of authentication services supported by the asset.

Return value

Array

Description

Returns the IP address the asset used to connect.

Return value

String

Description

Returns true if the asset is configured as a "call home" asset.

Return value

bool

Description

Returns the ID of the asset.

Return value

String

Description

Returns the ID of the Asset. This represents a unique ID stored on the computer and is not the same as the asset id returned by getId().

Return value

bool

Description

Returns the asset matching the given asset id.

Return value

Asset

The asset or null if the asset is not found.

Parameters

Parameter Type Description
id String The id of the agent to search for.

Description

Returns the all the assets matching the given name.

Return value

Array

An array of Asset objects, each representing an asset with the given name.

Parameters

Parameter Type Description
id String The name of the agent to search for.

AssetGroup

Extends Group. An asset group extends Group to provide more asset specific capabilities.

Description

Returns an array of Asset objects that are members of this group.

Return value

Array

Description

Returns an asset group given a path. A path must start with a "/" and contain one or more group names separated by "/" characters. For example, "/production/acme" identifies the "acme" group in the "production" group.

Return value

Array

Parameters

Parameter Type Description
path String A path as described above.

Description

Returns an asset group given its id. If no group exists with this id, null is returned.

Return value

Group

Parameters

Parameter Type Description
id String The group's id.

Group

Many things in situate may exist in a group folder as a way of introducing some kind of order. The Group object describes one of these groups. Groups are identified by an id. The name may change over time. A group may also have a parent id. In this case, the parent id describes the containing folder. If a group's parent id is null, then it is a top-level group.

Description

Returns the name of the group

Return value

String

Description

Returns the id of the group

Return value

String

Description

Returns the parent id of the group or null if there is no parent.

Return value

String

Description

Returns an array of strings. Each string is the id of objects contained within it, excluding other groups.

Return value

Array

Nofity

A "Notify" contains data passed to notify workflows they use to build a notification email or other form of notification

Description

Returns the value of thw "who" field from the workflow

Return value

String

RemoteExecAssetStatus

Provides detail on a single target of a remote execution task.

Description

Returns the asset upon which the command was run

Return value

Asset

Description

Returns the asset id of the asset upon which the command was run. It also may return an asset name if a variable expansion took place.

Return value

Asset

Description

The number of retries that took place

Return value

Asset

Description

The exit condition. One of the following values:

0The inital state (Nothing has started yet)
1Running
2Exited normally
3Terminated with a signal
4Terminated with a core dump
5Unable to create logfile
6The user was not valid or the principal did not contain a user valid for this host.
7The user/password were not valid
8The fork() or CreateProcess() system call failed
9The process cannot start because of some kind of failure. See the agent log.
10The process cannot start because of some kind of failure. See the agent log.
11Could not start an interactive process
12Waiting of authenticaion
13There was a failure in the win32 subsystem. See the agent log.

Return value

int

Description

A textual name corresponding to the exit condition.

Return value

String

Description

The id of the task.

Return value

String

Description

The expanded command to execute

Return value

String

Description

The task log for this command

Return value

TaskLog

Description

Returns true if situate will wait for the process to complete.

Return value

TaskLog

Description

Returns the id of the child process

Return value

int

Description

Returns the start time of the process

Return value

Date

Description

Returns the time the process exited

Return value

Date

Description

If the process exited normally (getCondition() returned 2), then this is the exit status of the child process.

Return value

int

Description

If the process exited with a signal, this returns the specific signal.

Return value

int

Description

If the process could not be started and getCondition() returned 9, then this string will provide more detail. of the child process.

Return value

int

RemoteExecStatus

Extends TaskStatus to report additional detail about remote exec tasks

Description

Returns an array of AssetStatus objects, one for each asset upon which the remote exec task executed a command.

Return value

Array

Sit

The Sit object holds information about the situate instance.

Description

Returns the value of a domain setting set in the UI

Return value

String

Description

Returns the value of system settings from /etc/situate.conf

Return value

String

Description

Returns the value of a domain setting.

Return value

String

Status

A Status object describes the status of a workfow, task, trigger, group, edge or sequence. A workflow log is a collection of Status objects.

Description

Returns a description, if any, associated with this status

Return value

String

Description

Get the thread name associated with this status

Return value

String

Description

Get the task, edge, trigger or group name this status is about.

Return value

String

Description

Get the time this status was reported

Return value

Date

Description

returns true if a subsequence had a path to a join.

Return value

Date

Description

returns true if this status is marked "Strategy Final" meaning it will cause a sequence to terminate.

Return value

Date

Description

Sometimes an object fails because of something another object does. In this case, the status causing this event is return by this function.

Return value

Status

Description

If the failure was due to a JavaScript error, this function will return the JavaScript Error class that describes the failure.

Return value

Error

Description

Return a textual name that describes this status

Return value

Error

Description

If the task has a simple task log (one task log), then this returns the task log. For file transfer and remote exec tasks, this returns the first task log, but each of these tasks can run against many targets. See RemoteExecStatus for more details.

Return value

Error

String

Represents a string in JavaScript -- A set of characters.

Description

Create a string from a char code

Return value

String

A string of length N consisting of the N specified UTF-16 code units.

Parameters

Parameter Type Description
code int The character code

Description

Returns the character at the given location.

Return value

String

Parameters

Parameter Type Description
index int The location from zero to length of string-1

Description

Returns a number representing the UTF-8 character code at the given location

Return value

int

Parameters

Parameter Type Description
index int The location from zero to length of string-1

TaskLog

Some tasks (like the remote command task) can produce a text-based log file. This object provides access to these files.

Description

Returns the entire contents of the file.

Return value

String

Description

Returns the last N lines of the file

Return value

String

Parameters

Parameter Type Description
n int The number of lines to return.

Description

Returns the first N lines of the file

Return value

String

Parameters

Parameter Type Description
n int The number of lines to return.

W

A "W" or workflow is an object that completely describes a workflow. A workflow consists of tasks, triggers, edges, groups and many other entities.

Description

Returns the name of the workflow

Return value

String

Description

Returns the id that uniquely identifies the workflow within situate.

Return value

String

Description

Returns default timezone.

Return value

String

Description

Returns protection delay for this workflow. (Not implemented as of 1.11)

Return value

int

Description

Returns the number of days of logs to keep or a negative value indicating the number of runs to keep.

Return value

int

Description

The user who approved the workflow

Return value

String

Description

The time the workflow was approved

Return value

Date

Description

The user that submitted the workflow (new or changes)

Return value

String

Description

The time the workflow was last submitted for approval.

Return value

Date

Description

The time the workflow was last executed.

Return value

Date

Description

If scheduled, the time the workflow will run next, assuming nothing interferes with its current scheule and configuration.

Return value

Date

Description

The user who last exeucted the workflow

Return value

String

Description

The number of days this workflow will remain in the unconfirmed state before situate automatically confirms it.

Return value

int

Description

When a workflow exits, it must be confirmed or it will stay in the queue. This function returns how auto-confirmation is configured for the workflow.

Return value

int

One of the values (1 = ON_SUCCESS, 2 = ALWAYS, 3 = NEVER, 4 = ON_FAILURE)

Description

Returns when the workflow will execute a notification workflow.

Return value

int

One of the values (1 = ON_SUCCESS, 2 = ALWAYS, 3 = NEVER, 4 = ON_FAILURE)

Description

The value of the variable notify.who passed to a child notification workflow.

Return value

int

Description

The workflow to run to perform notification.

Return value

int

Description

The name of the trigger within the notification workflow to call when a notification is performed.

Return value

int

Description

An array of strings representing all the keywords associated with this workflow.

Return value

Array

Description

The version of the workflow document. From time to time new features are added. Each time a feature changes the structure of the workflow document, this value is increased. This value can be useful for determining what level, if any, of backward compatability should be employed.

Return value

int

Description

The description field from the workflow

Return value

String

Description

Returns true if the workflow is to be deleted after it runs.

Return value

int

Wi

A "Wi" or workflow instance is an object that holds information about a workflow that has run or is running. The workflow instance contains all the data about the status of each task, trigger, edge and other entities as the workflow ran and can be used to reconstruct what happened as the workflow ran.

Description

Returns the name of the workflow

Return value

String

Description

Returns instance id of this workflow's execution.

Return value

String

Description

Returns the time this workflow started

Return value

Date

Description

Returns the time this workflow stopped running. It may have completed or was canceled.

Return value

Date

Description

Returns the last task status reported by this workflow instance. If complete or canceled, this will be a workflow status.

Return value

Status

Description

Returns the task status of the last exeuction of the named object.

Return value

Status

A Status object or null if no object was found.

Parameters

Parameter Type Description
objectName String The name of the object (task, trigger, edge, etc.) of the status you are looking for.

Description

Returns the task status of the named object and instance. The instance is incremented each time an object runs within a thread. Therefore, the instance distingueshes the specific execution of the object if it has run more than once.

Return value

Status

A Status object or null if no object was found.

Parameters

Parameter Type Description
objectName String The name of the object (task, trigger, edge, etc.) of the status you are looking for.
instance int The run number you are looking for. This number should be 1 or more.

Description

Returns the task status of the named object and instance. The instance is incremented each time an object runs within a thread. Therefore, the instance distingueshes the specific execution of the object if it has run more than once. It is also possible an object runs in a different thread. The thread argument describes which thread you are looking for.

Return value

Status

A Status object or null if no object was found.

Parameters

Parameter Type Description
objectName String The name of the object (task, trigger, edge, etc.) of the status you are looking for.
thread String The specific thread.
instance int The run number you are looking for. This number should be 1 or more.

Description

Returns the status of the trigger used to start this workflow instance.

Return value

Status

Description

Returns the status of the workflow.

Return value

Status

Description

Returns the instance of a prior workflow run.

Return value

Status

Parameters

Parameter Type Description
run int The run number. This value should be 1 or more.

Description

Returns the instance of the prior workflow run.

Return value

Wi

The prior run or null if one does not exist.

Description

Get the number of runs of this worklfow. This will be 1 plus the number of times the workflow was restarted. Calling this function in a prior run will only return the number of runs of that instance not including ones started after it.

Return value

int

Description

returns the workflow associated with this instance.

Return value

W

Wm

A "Wm" or workflow manager manages one or more queues of workflows. Currently, there is no public API available.

WorkflowExecStatus

Extends Status to provide detailed information about a workflow exec task's status.

Description

Returns the name of the workflow started by the workflow exec task

Return value

String

Description

Returns the id of the workflow instance started by the workflow exec task

Return value

String

Description

Returns the id of the workflow started by the workflow exec task. The id can also be a name if variable expansion took place.

Return value

String

X

A collection of utility functions.

Description

Create a new list from an existing list where each member matches the specified regular expression.

Return value

Array

An array of elements matching the given regex

Parameters

Parameter Type Description
The Array input array
A Regex regular expression used to filter the list

Description

Return an object by executing a search inside a larger object. The

Return value

Object

The first matching object.

Parameters

Parameter Type Description
The Object object to search.
The String base of the search. This should point to an array inside the target object
Inside String part. This is the path inside the object that should be matched against the supplied value
A Function function that returns true when the object is matched. the input to the function will be the base element in the list being iterated.
an Object optional default value.

Description

Return a situate version number from a version number string. For example, situate-1.11.1 will return 11101

Return value

int

A version number

Parameters

Parameter Type Description
The String input string

Description

Return a list of integer elements from the staring number up to and including the ending number

Return value

Array

The Array of numbers

Parameters

Parameter Type Description
The int starting number
The int ending number