Account Management

Invite Team Members

You can invite new team members by clicking the Copy to clipboard link, which will provide a url which can be used to join your team. Be aware that anyone who receives this link will be able to join your team.

You can also invite new team members by entering their email address in one of the provided boxes and clicking Add Teammates. If additional boxes are needed, click the + add more teammates link.

Click Accept Invitations to join other teams to which you have been invited.

Product Documentation

SaaSGlue Framework Overview

Cloud and Agents

The basic components of the SaaSGlue platform are the cloud service and Agents installed on machines. The machines can be physical, virtual or containers. And they can be located in many types of environments including corporate networks, private clouds and more.

When agents are installed they begin sending a heartbeat to the SaaSGlue cloud. They receive instructions to execute scripts and send the results back to the cloud.

Scripts and Jobs

Scripts can be tied together in Jobs with specific instructions on how they are to be run.

SaaSGlue can run any script and It can even run compiled code. The Agent doesn’t run the scripts. Instead it hands them off to the specified interpreter for execution and collects the output.

Scripts are contained in Steps which also include Arguments and Environment variables which can be passed to the script runtime environment.

Steps are contained in Tasks which can include one or more Steps. All Steps in a Task are executed sequentially on the same machine by the same Agent.

Jobs contain instructions for how a set of Tasks are to be run. They order the Tasks, direct them to the right Agent(s), pass in runtime variables and define conditions when there are alternate Task routes.

Jobs are the central feature that makes SaaSGlue a powerful automation engine. They can reach across all kinds of networks, devices, languages and applications, incorporating them into unified, well-orchestrated workflows.

The Structure of Jobs

Jobs are a hierarchical structure of sub-components, including Tasks, Steps and Scripts.

Job

The Job organizes Tasks into a flexible workflow. It contains instructions for how the Job is to be run and stores runtime variables to be consumed during Script execution.

Task

The Task collects steps into a logical unit that run on an Agent. It also stores qualifications for which Agent(s) can run the Task.

Route codes define how the Job moves from Task to Task and sets conditions for alternate routing.

Step

The Steps of a Task are executed in a set sequence. The Step object stores its order in the sequence and environment variables and command line arguments to be passed to Script execution. It can also store a specific command to use to execute the Script. This would override the default interpreter based on the Script type. For example, a command value of /usr/bin/python2.7 for a Step running a python Script would result in the Script being executed with the interpreter located at /usr/bin/python2.7 on the machine where the Step runs.

Script

The Script is a SaaSGlue object which contains the code that is to be executed by the interpreter and the type of interpreter to use to run the script.

Job Definition

Job Definitions (JobDefs) are structured workflow templates that coordinate the execution of one or more Tasks to accomplish a goal. For example, a JobDef could consist of a single Task that watches for new files in a specific location. When a new file is discovered, it could launch a new Job based on another JobDef with a series of Tasks that constitute a data pipeline for processing the file.

JobDefs are normally designed using the SaaSGlue web application. However, they can also be created dynamically using the SaaSGlue API.

JobDefs are used to create Jobs, which are runtime implementations of JobDefs. Creating a Job from a JobDef can be accomplished in three ways:

• Schedule a JobDef using the SaaSGlue web application or the SaaSGlue API. When the Schedule is triggered, the JobDef will be used as a template to create and run a Job. A scheduled Job may be triggered but not run immediately or at all based on certain JobDef attributes.
• A Job can be launched from a JobDef manually using the SaaSGlue API or using the SaaSGlue web application.
• A JobDef can be defined in JSON and sent to the SaaSGlue API in an Http POST.

Routes

The JobDef ties Tasks together with routes. Routes include two components, the task name and the route pattern. The route pattern can be any valid javascript regular expression. For example, a route pattern of ^(?!fail$).*$ would match any route code other than fail. For a route to be satisfied, a task must be completed with a route code matching the route pattern.

By default, tasks that complete successfully (all steps in the task complete with exit code 0) have a blank route code. Tasks that fail (a step in the task completes with non-zero exit code) have route code fail. Tasks that are interrupted (either by CTRL+C or canceled using SaaSGlue) have route code interrupt. To set a custom route code, print a string to stdout following the pattern @sgo{"route": "[route name]"} from a script. If multiple scripts within a task set a custom route code, the last one will be used.

SaaSGlue supports two types of task routing – inbound and outbound routes. Inbound routes require all routes to be satisfied before the target task is executed. For example, if we have inbound routes from task1 with route pattern .* and task2 with route pattern .* to task3, both routes must be satisfied for task3 to execute.

Outbound routes cause the target task to be executed every time the outbound route is satisfied. For example, if we have outbound routes from task1 with route pattern .* to task3 and from task2 with route pattern .* to task3, then every time the task1 route is satisfied, task3 will be executed, and every time the task2 route is satisfied, task3 will be executed. An example use case would be a general failed task handler. You could implement this by creating an outbound route from every other task in the job to a failed task handler task. This scenario is facilitated in the web application by the Route All To [task name] button in the Workflow Designer view.

• Max Instances – defines how many instances of a job can run concurrently.
• Misfire Grace Time – defines how long a job can wait past a scheduled start time before it is cancelled. This setting applies only to jobs executed by a schedule.
• Coalesce – directs SaaSGlue to skip all but one job when there are multiple jobs queued up. This setting is useful for scenarios where an agent has gone offline and missed the start time for several scheduled jobs. It may be desirable to run only one instance and skip the rest.
• Pause on Failed Job – if true, when a Job created from the JobDef fails, the JobDef will be paused until it is manually resumed (using the SaaSGlue cloud interface or the API) or all failed Tasks are either canceled or completed successfully. This facilitates certain workflow scenarios, for example where all Jobs created from a JobDef must complete in order.

Task Definition

Each Task can have one or more Steps that must be run in a set sequence.

Tasks can target one or multiple Agents. If a Task targets multiple Agents each Agent will run separate instances of the Task in parallel. Once an Agent begins processing a Task, all Steps in the Task will be completed on that Agent machine. If a Task fails or is interrupted it can be restarted, although it may not be restarted on the machine where it was previously running.

The Steps of a specific Task instance must all be completed by the same Agent because there are some sequences of events that cannot be shared across multiple machines. Here is an example.

1. Install Java
2. Run a Java application

If step 1 runs on one machine and step 2 runs on a different machine where Java has not been installed, step2 will fail.

The Job designer must understand the logical boundaries of each discrete part of the Job and design accordingly.

Dependencies on prior Task outcomes are stored in the Task definition inbound routes. They determine whether the Job route will route through a given Task or not. Downstream dependencies are stored in the Task definition outbound routes. They determine which Tasks will be started when this Task completes. See the JobDef routing description for details.

Task definitions store the qualifications for determining which Agent(s) can run the Task. Those qualifications are as follows:

• Any active Agent
• Any active Agent with tags as specified in the Task definition
• All active Agents
• All active Agents with tags as specified in the Task definition
• A specific Agent

Tags are user defined and must be formatted in key value pairs, such as Linux=True. Task Tags can be defined using the SaaSGlue web application or the SaaSGlue API.

If a Task needs to run on a specific agent, use the Job Designer in the SaaSGlue web application or the SaaSGlue API to specify which agent should run the Task. It is also possible to dynamically determine the target agent at runtime using runtime variables. Simply set the target agent to @sgg("[runtime variable key]") and the agent id referenced by [runtime variable key] will be used to execute the Task.

Step Definition

Steps are contained within a Task and must be run in a set sequence. The Step definition stores its order in the sequence.

Each Step can have only one Script object. The Step definition can store arguments or environment variables which are needed to run the script. Step arguments and environment variables can be set dynamically at runtime using Runtime Variables.

The command attribute can be used to specify the exact interpreter to use to execute the script for Steps created from this StepDef. It can also be used to set arguments that should be passed to that interpreter. For example, to pass a class path to the scala interpreter. If not specified, the default interpreter for the script type will be used to execute the script.

For example, if you have a script of type python and the command attribute is not set, then the default python interpreter on the machine where the Step runs will be used to execute the script. If the command attribute is set to /usr/bin/python2.7, then the interpreter in that location on the Agent machine will be used to run the script. The interpreter specified by the command attribute must exist on the machine on which the Step runs.

The designer can give the Step definition a name to make it more convenient to work with.

Script Definition

The Script object stores the Script code.

It also stores useful information about the Script including the Script language, the original author and who last edited it.

SaaSGlue can be used to execute any Script. The Script type attribute is added to the Script object to make it easier to work with common scripting languages. For example, the SaaSGlue cloud interface Script editor provides cues based on the script language. To use a script language not defined in SaaSGlue use SH if the Script will run on Linux, Linux based or Mac operating systems and CMD for Windows and then define the Command attribute either in the StepDef or when executing the Script from the Console.

The following script types are predefined in SaaSGlue:

• 0 = PYTHON
• 1 = NODE
• 2 = SH
• 3 = CMD
• 4 = RUBY
• 5 = LUA
• 6 = PERL
• 7 = PHP
• 8 = POWERSHELL

Script Injection

Scripts defined in SaaSGlue can be injected into other scripts using the following syntax @sgs("[script name]")

This line entered in a script will result in the script defined by [script name] being injected into the host script immediately before executing the script.

Scripts can be injected recursively meaning that script 1 can reference script 2 which can reference script 3, etc.

However, the [script name] itself cannot be a variable – it must be the name of a script defined in your SaaSGlue team.

Runtime Variables

Runtime Variables are key-value pairs. They provide a mechanism for dynamically injecting variable values in Script code, Arguments and Environment Variables of a Task Step when it is executed by a SaaSGlue Agent. Runtime variables can be defined at design time on the Team level and in JobDefs, and when a Job is created and they can also be generated dynamically during Script execution.

How to define

Team scoped runtime variables

Runtime Variables can be defined on the Team level using the SaaSGlue cloud interface or the SaaSGlue API.

JobDef scoped runtimes variables

Runtime Variables can be defined in JobDefs using the SaaSGlue cloud interface or the SaaSGlue API.

Job scoped runtime variables

Runtime Variables can be defined in a Job when the Job is created. When a Job is created using the SaaSGlue API the runtime variables can be included in the Http POST request. When a Job is created from a JobDef in the SaaSGlue cloud UI the runtime variables can be entered in the Job creation dialog.

Dynamically generated runtime variables

Runtime Variables can be generated dynamically during Script execution by printing a properly formatted string to stdout. The format is @sgo{"[variable name]": "[variable value]"}.

For example, the following line of python script code would dynamically create or modify a runtime variable with name myKey and value "myValue" when executed by a SaaSGlue Agent print '@sgg{"myKey": "myValue"}'.

The "myKey" runtime variable would now be defined as "myValue" for subsequent Steps in the Task being executed and for subsequent Tasks in the Job workflow.

SaaSGlue reserves the key word route to determine route-based pathing between Tasks in a Job workflow. So the following output @sgg{"route": "ok"} would not create a runtime variable named route. Instead it would be used for routing from the executing Task in the Job workflow.

If a runtime variable is defined on multiple levels, each successively granular level overrides the previous. For example, if we have a variable named key defined on the Team level with a value of team_value and in a JobDef with a value of jobdef_value, the JobDef value will override the Team value. If the variable is defined in a Job created from the JobDef with a value of job_value, the Job value will override the JobDef value. If within that Job a Script runs which prints the following string to stdout sgo{"key": "script_value"}, the Script value will override the Job value and any subsequent reference to key will have the value script_value. A subsequent Script could override the value again.

How to use

Runtime Variables values can be dynamically injected into the Script code, Arguments and Environment Variables of a Step. Immediately before running a Task Step, the Agent will search the Step Script code Arguments for strings following the pattern sgg("[key]") and will replace them with the current value of the runtime variable with the name [key]. If no runtime variable with the name [key] exists, null will be injected instead.

Step Script code runtime variable injection

For example, if we have a python script with the following line of code

print('the value of "myKey" is "@sgg("myKey")"')

and a runtime variable myKey with value myValue, the script will produce the following output

the value of "myKey" is "myValue".

Step Arguments runtime variable injection

If we have a Step Argument with value @sgg("myKey") -out myFile.txt" , and the runtime value of myKey is myValue the Script code for the Step will be called with arguments "myValue -out myFile.txt".

Step Environment Variables runtime variable injection

Runtime Variable injection for Step Environment Variables works slightly differently. Step Environment Variable keys are compared to the current runtime variables for matching keys. If a match is found, the runtime variable value will be used for the environment variable value when running the Script.

For example, if we have a Step Environment Variable myKey and a runtime variable myKey with value myValue, then the runtime script execution environment will have an environment variable myKey=myValue.

Design time configuration

A StepDef can be configured so that Steps created from the StepDef utilize runtime variables in arguments and/or environment variables using the SaaSGlue API or the SaaSGlue cloud interface.

Dynamically select Task target agent id

Runtime variables can be used to dynamically determine the target agent for Tasks that target a single specific agent at runtime. For example, if you have a runtime variable named agentId and the value is an actual agent id, and the Task target agent id is @sgg("agentId"), the task with the id matching the runtime variable value will be used to run the Task.

Save state with runtime variables

As Scripts are executing the corresponding stdout is monitored in real-time and searched for strings following the @sgo runtime variable generation pattern. When runtime variables are created/modified, the new values are sent to the SaaSGlue cloud. If a Task fails and is restarted, the most recent runtime variable values will be delivered with the Task to the Agent where the Task resumes execution. Consequently, Scripts can be designed to utilize the most recent value of the runtime variable.

For example, if a Script is designed to iterate through records in a file, the line number could be printed to stdout with a string like @sgo{"line_num": "10"} which would send the runtime variable line_num with a value of 10 to the SaaSGlue cloud. If the Task failed on line "11" and the Task is restarted, the Script could resume processing the file on the line after @sgg("line_num") which would now have a value of 10.

Job Schedule

Schedules can be created for Job Definitions (JobDefs) to automatically trigger Jobs to run. A JobDef can have more than one Schedule but a Schedule can be linked to only one JobDef.

There are three types of schedules.

• Date
• Cron
• Interval

RunDate

Date is the simplest schedule. It stores a single date and time for when the job will be triggered to run.

Cron

Cron resembles the Cron utility found in most UNIX-like operating systems. The following fields are available to define a cron schedule.

• Year 4-digit year
• Month 1-12
• Day day of the month (1-31)
• Week ISO week (1-53)
• Day of Week number or name of day (0-6 or mon, tue, wed, thu, fri, sat, sun)
• Hour 0-23
• Minute 0-59
• Second 0-59
• Start Date earliest possible date/time to trigger the job
• End Date latest possible date/time to trigger the job
• Jitter advance or delay the job execution by jitter seconds

A cron schedule will trigger when current time matches all specified time constraints. Unlike with crontab expressions, you can omit fields that you don’t need.

Interval

Interval specifies a set amount of time that must lapse before a job will be triggered. The following fields are available to define an interval schedule.

• Weeks integer for the total number of weeks
• Days integer for the total number of days
• Hours integer for the total number of hours
• Seconds integer for the total number of seconds
• Start Date earliest possible date/time to trigger the job
• End Date latest possible date/time to trigger the job
• Jitter advance or delay the job execution by jitter seconds

An interval schedule will trigger a job when the time interval has been reached from the previous trigger time.

The Is Active box must be checked to activate the schedule.

The designer can give the schedule a name to make it more convenient to work with. The designer displays the last run date and the next run date for active schedules.

Service Tasks

Have you written services for Windows? Linux? Mac? Then you know that it can be difficult and that the process works differently in each environment. Occasionally work-arounds are implemented for actual services such as cron or the Windows Task Scheduler. If the machine running the service shuts down, the service is stopped.

SaaSGlue makes it easy to create a service and deploy it to any operating system. To run a task as a service, simply set the autoRestart property of the task to true if using the SaaSGlue API. If using the SaaSGlue cloud UI, in the Job Designer -> Task editor view, check the Auto restart checkbox. The task can target any qualified agent or a specific agent. If the agent running an autoRestart task is stopped or is inactive for more than 65 seconds, the task will automatically be restarted on another qualified agent. If no qualified agent is available, the task status will be set to Failed. The containing job can be configured to send a notification if this occurs. If an agent running an autoRestart task goes offline and then comes back online and the task is still running on that agent and has also been restarted on a new agent, the instance on the agent that went offline will be canceled.

Auto restart tasks can have multiple steps. The script for the last step in the task should be coded so that it will not exit unless and until you want the service to be stopped. Auto restart tasks that exit normally or crash are not restarted automatically. However, if an auto restart task is interrupted by CTRL + C or a SIGTERM/SIGKILL signal it will be automatically restarted. Consequently if the machine running an auto restart task is shut down, the task will be automatically restarted.

Endpoint / Object Reference

Agent

The SaaSGlue Agent is the vehicle for executing Scripts received from the SaaSGlue cloud. The Agent can be installed on any supported operating system. When an Agent starts up it reports to the SaaSGlue cloud which tracks information about the Agent including the attributes described below. A few of the attributes can be modified by users.

Reference

Attribute Descriptions

id

SaaSGlue automatically assigns an Agent ID when a new agent is installed and calls back to the SaaSGlue cloud. Users can discover the ID in the Agent Monitor or through the API. Tasks can be routed to a specific machine using the Agent ID.

_teamId

The ID of the Org object where the TaskDef is.

machineId

The hostname of the physical or virtual machine or container where the Agent is running.

Every machine connected to a SaaSGlue account must have a host name that is unique to the Org. The machineId will be reported in every Agent heartbeat. If the hostname changes then the Agent will be assigned a new ID.

ipAddress

The ipAddress attribute stores the IP Address of the machine where the Agent is installed.

The IP Address will be reported with each heartbeat. If the IP address of the machine is changed the ipAddress attribute will be updated but the Agent will not be assigned a new ID.

createDate

The date and time an Agent first runs on a machine.

name

The name attribute defaults to the machineId (hostname). However, it can be modified to create a user-defined name.

tags

Tags assigned to an Agent. Up to ten tags can be assigned to an Agent.

Tags are user defined. They are used in the Job Designer and Console for Task routing.

numActiveTasks

The number of Tasks currently being executed by this Agent.

lastHeartbeatTime

The last date and time SaaSGlue received a heartbeat from the Agent.

offline

If SaaSGlue has not received a heartbeat from an Agent for more than 5 minutes the offline attribute is set to "true". If the Agent begins sending a heartbeat again the offline attribute will be reset to “false”.

sysInfo

System information pertaining to the machine where the Agent is installed. The following information (if available) will be reported.

Top 10 running processes (ordered by CPU usage):

• Installed OS details
• System date/time
• CPU current speed
• CPU temperature
• Current load information
• File system information
• File system performance statistics
• Installed user accounts
• Memory capacity/usage information
• Battery capacity/usage information
• Network connections
• Current internet latency
• Network statistics
• Disks IO

The Agent will report system information when it is first installed. It can be configured to report updated information with each heartbeat.

cron

Cron jobs that reside on the machine where the Agent is installed. These jobs can be uploaded to SaaSGlue where they can be centrally managed and orchestrated.

propertyOverrides

Agent settings that can be overridden by users including the following:

• maxActiveTasks limits the number of tasks an Agent can run in parallel. If more than maxActiveTasks are routed to an Agent, Tasks in excess of maxActiveTasks will be queued until running Tasks are completed. If a Task is queued for more than the Task TTL, the Task will be routed as “failed”.
• inactivePeriodWaitTime sets the max amount of time an Agent will remain idle before it runs a specified Task. This is useful for some Tasks, such as shutting down an idle EC2 instance.
• inactiveAgentTask is the Task that will be run if and when the inactivePeriodWait time is exceeded. The Task must be JSON formatted and adhere to the Task specification.
• handleGeneralTasks can exclude an Agent from running Tasks that are marked as "run on any machine" or "run on all machines" if this attribute is set to “false”.
• trackSysInfo reports updated system information to the SaaSGlue cloud with each heartbeat.

Actions

download

Download the Agent install from SaaSGlue - agentDownload/agentstub/:platform/:arch

:platform(required) - must be one of: linux, win, macos, alpine, freebsd

:arch(optional) - must be one of: x64, x86, armv6, armv7

Not all platform/arch combinations are valid.

Sample Code

Get all Agents objects in the Org

Request

curl --location --request GET 'https://saasglue.com/api/v0/agent' --header 'Content-Type: application/json' --header 'Auth: [auth token]' --header '_teamId: [teamId]' --data-raw ''

Response

{
    "statusCode":200,
    "data":{
        "numActiveTasks":0,
        "lastHeartbeatTime":1588863480826,
        "offline":false,
        "cron":"",
        "_teamId":"[teamId]",
        "machineId":"[Machine ID]",
        "ipAddress":"[IP Address]",
        "name":"[Agent Name]",
        "propertyOverrides":{
            "trackSysInfo":false,
            "maxActiveTasks":20
        },
        "sysInfo":{},
        "createDate":"[Date]",
        "tags":{},
        "id":"[Agent ID]",
        "version":0,
        "type":"Agent"
    }
}
                    

Update an Agent property

Request

curl --location --request PUT 'https://saasglue.com/api/v0/agent/properties/[agentId]' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]' --header 'Content-Type: text/plain' \ --data-raw '{ "trackSysInfo": true }'

Response

{
    "statusCode":200,
    "data":{
        "numActiveTasks":0,
        "lastHeartbeatTime":1588863480826,
        "offline":false,
        "cron":"",
        "_teamId":"[teamId]",
        "machineId":"[Machine ID]",
        "ipAddress":"[IP Address]",
        "name":"[Agent Name]",
        "propertyOverrides":{
            "trackSysInfo":true,
            "maxActiveTasks":20
        },
        "sysInfo":{},
        "createDate":"[Date]]",
        "tags":{},
        "id":"[Agent ID]",
        "version":0,
        "type":"Agent"
    }
}
                    

Artifact

Artifacts are files that can be uploaded to SaaSGlue to be used in the execution of Jobs and Tasks.

An Http GET request will return a secure URL which can be used to download an artifact. Http PUT and POST requests will return a secure URL which can be used to upload an artifact.

Reference

Attribute Descriptions

id

Unique ID assigned when a new Artifact object is created.

_teamId

The ID of the Org object where the TaskDef is created.

name

Artifact Name is the name of the file that is uploaded. The combination of Prefix and Name attributes for an Artifact must be unique within an Org.

prefix

Prefix is the path name where an artifact is stored in SaaSGlue. The path can include one or more / delimited folder names - e.g. prod/loader/.

Sample code

Upload an artifact

Request

curl --location --request POST 'https://saasglue.com/api/v0/artifact' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]' --header 'Content-Type: text/plain' \ --data-raw '{ "_teamId": "[teamId]]", "prefix": "[prefix]", "name": "[file name]" }'

Response

{
    "statusCode":201,
    "data":{
        "prefix":"[prefix]",
        "type":"Artifact",
        "url":"[secure url]",
        "_teamId":"[teamId]",
        "name":"[file name]",
        "id":"[Artifact ID]",
        "version":0
    }
}
                    

Now use the url returned from the previous call to upload the file to SaaSGlue

curl -v --upload-file [file name] [url] --header 'Content-Type: multipart/form-data'

Download an artifact

Request

curl --location --request GET 'https://saasglue.com/api/v0/artifact/[ArtifactID]' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]' --data-raw ''

Now use the “url” returned from the previous call to download the file

curl [url] > [file name]

Job

A Job is the runtime implementation of a JobDef. A Job can be created from an existing JobDef or from a properly formatted JSON document. Jobs are automatically submitted for execution when they are created.

Jobs can be created from a JobDef by

• scheduling the JobDef
• with the SaaSGlue web application
• by submitting a POST to the Job API endpoint

Jobs are created from a JSON document by submitting the JSON document to the Job API endpoint.

Reference

• 1 Required if Job is created from JobDef object
• 2 Required if Job is created from API call

Attribute Descriptions

id

Unique ID assigned when a new Job object is created.

_teamId

The ID of the Org object where the Job is created.

_jobDefId

The JobDef ID from which the Job was created. It only applies to Jobs created from a JobDef object.

runId

JobDefs have a counter that is incremented each time a Job is created from the JobDef object. The runId attribute is the value of that counter when the Job was created. It can be used to order Jobs created from the same JobDef sequentially. For example, if a given Job object is the third one ever created from a JobDef object, it will have a runId attribute of 3.

name

The Job name. If the Job is created from a JobDef, the Job name is copied from the JobDef name. If the Job is created from JSON, the name must be included in the JSON document.

createdBy

The id of the user who created the Job. For Jobs created from a JobDef it will be the user who created the JobDef object. For Jobs created from an API call it will be based on the auth token of the user submitting the JSON document.

dateCreated

The date and time the Job was created.

dateScheduled

The date and time a Job is scheduled to run. It only applies to Jobs created from JobDef objects with a Schedule.

dateStarted

The date and time the Job started.

dateCompleted

The date and time the Job completed.

status

The current Job status. Here are the possible values.

• 0 = NOT_STARTED
• 10 = RUNNING
• 14 = INTERRUPTING
• 15 = INTERRUPTED
• 17 = CANCELLING
• 20 = SUCCEEDED
• 21 = CANCELLED
• 22 = FAILED
• 23 = SKIPPED

error

The error message if any error occurred running the Job.

runtimeVarsx

Runtime variables for a Job are set when the Job is created manually (not by a schedule). If the Job is created from a JobDef and any Job runtime variables have the same name as the JobDef runtime variables, the Job values will override the JobDef values.

{"key1": "value1", "key2": "value2"}

If true the Job will run as a service.

runAsService

runAsService Jobs can contain only one Task. The script in the last step of the Task must be written in such a way as to prevent the script from exiting, for example with a while loop. If the script exits (either naturally or by a crash) the Job will not be restarted.

If the Agent on which the Job is running fails to send a heartbeat for 30 minutes, the Job will be republished to another qualified Agent. If the original Agent subsequently connects and the Job is still running on that Agent, it will be CANCELLED on that Agent.

A runAsService Job will stop if it is in a SUCCEEDED, CANCELLED or FAILED state.

Actions

interrupt

Interrupt a job. Job status must be RUNNING.

jobaction/interrupt/:jobId

restart

Restart a job. Job status must be INTERRUPTED or FAILED.

jobaction/restart/:jobId

cancel

Cancel a job. Job status must be NOT_STARTED, RUNNING, INTERRUPTING or INTERRUPTED.

jobaction/cancel/:jobId

Sample Code

Create and run an ad hoc job

Request

curl --location --request POST 'https://saasglue.com/api/v0/job' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]' --header 'Content-Type: text/plain' --data '{ "job": { "name": "Job Name", "dateCreated": "[date]", "tasks": [ { "_teamId": "[teamId]", "name": "Task1", "requiredTags": , "requiredTags": {"tag": "value"}, "dependsOn": [], "steps": [ { "name": "Step1", "script": { "scriptType": "SH", "code": "bHMgLWx0cgo=" }, "order": 0, "arguments": "", "variables": "" } ] } ] } }'

Response

{
    "statusCode":201,
    "data":{
        "dateCreated":"[date]",
        "runAsService":false,
        "name":"Job Name",
        "_teamId":"[teamId]",
        "createdBy":"[userId]",
        "dateStarted":"[date]",
        "status":10,
        "runtimeVars":{},
        "id":"[Job id]",
        "version":0,
        "type":"Job"
    }
}
                    

Create and run a job based on a JobDef template

Request

curl --location --request POST 'https://saasglue.com/api/v0/job' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]’ --header '_jobDefId: [jobDefId]' --data-raw ''

Response

{
    "statusCode":201,
    "data":{
        "dateCreated":"[date]",
        "runAsService":false,
        "_teamId":"[date]",
        "_jobDefId":"[date]",
        "runId":14,
        "name":"[name]",
        "createdBy":"[userId]",
        "status":0,
        "runtimeVars":{},
        "id":"[jobId]",
        "version":0,
        "type":"Job"
    }
}
                    

Get a job using the job id

Request

'https://saasglue.com/api/v0/job/[jobId]' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]'

Response

{
    "statusCode":200,
    "data":{
        "dateCreated":"[date]",
        "runAsService":false,
        "name":"Job Name",
        "_teamId":"[teamId]",
        "createdBy":"[userId]",
        "dateStarted":"[date]",
        "status":10,
        "runtimeVars":{},
        "id":"[Job id]",
        "version":0,
        "type":"Job"
    }
}
                    

JobDef

A JobDef object is a template used to create and run a job. Typically a job template is created with the Job Designer and stored in a SaaSGlue account.

Jobs can also be created by submitting a JobDef object in JSON format to the API. In this way, ad hoc jobs can be created and executed dynamically.

Reference

Attribute Descriptions

id

Unique ID assigned when a new JobDef object is created.

_teamId

The ID of the Org object where the JobDef is created.

name

This attribute stores a user created name for the JobDef object. The name should be descriptive but does not have to be unique.

status

This attribute records the current status of the JobDef object. Here are the possible statuses.

• 10 = RUNNING - indicates that new Jobs can be created and run using this JobDef.
• 15 = PAUSED - indicates that new Jobs from this JobDef can be created but will not run until the JobDef status is RUNNING.

lastRunId

Set to 0 for new JobDef objects and is incremented for each Job created from a given JobDef.

maxInstances

The maximum number of parallel running Jobs created from the JobDef. For instance, if set to 1, only one Job will run at a time. Any additional Jobs created will be queued to run when the current Job is finished.

misfireGraceTime

The amount of time a Job can be queued past the scheduled start time before it is cancelled. This attribute can only be used with scheduled JobDefs. It is useful for situations when time is a critical factor in running a Job.

coalesce

The coalesce attribute helps job designers determine how to handle situations where a JobDef object has multiple queued Jobs. This could occur if multiple Jobs are created but maxInstances is set to 1 or if Jobs are created when a JobDef is PAUSED. The next time SaaSGlue is able to run Jobs for the given JobDef, it may not be practical or desirable to run all the queued Jobs. If coalesce is set to TRUE, the first queued Job will run and the rest will be SKIPPED with the error message Job skipped due to coalesce. Otherwise all Jobs will run in parallel.

createdBy

The ID of the User who created the JobDef object.

dateCreated

The date/time the JobDef object was created.

runtimeVars

A list of key/value pairs that can be dynamically injected into Job Scripts, Script arguments or environment variables at runtime.

{"key1": "value1", "key2": "value2"}

pauseOnFailedJob

This attribute can be used for example for JobDef objects with recurring Job executions that must complete in order. If a Job created from a JobDef is interrupted or fails and the JobDef pauseOnFailedJob attribute is TRUE, the JobDef Status will be updated to PAUSED. This will prevent all future Job executions until the Job is completed with status SUCCEEDED, CANCELLED or SKIPPED and there are no other INTERRUPTED or FAILED Jobs for this JobDef. Users can also manually pause or resume JobDefs.

Sample Code

Create a JobDef

Request

curl --location --request POST 'http://saasglue.com/api/v0/jobdef' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]' --header 'Content-Type: text/plain' \ --data '{ "_teamId" : "[teamId]", "name" : "Job Name" }'

Response

{
    "statusCode":201,
    "data":{
        "status":10,
        "lastRunId":0,
        "maxInstances":1,
        "dateCreated":"[date]",
        "pauseOnFailedJob":false,
        "_teamId":"[teamId]",
        "name":"Job Name",
        "createdBy":"[userId]",
        "id":"[id of new JobDef]",
        "version":0,
        "type":"JobDef"
    }
}
                    

Get a JobDef using the jobDefId

Request

curl --location --request GET 'http://saasglue.com/api/v0/jobdef/[JobDef id]' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]'

Response

{
    "statusCode":200,
    "data":{
        "status":10,
        "lastRunId":0,
        "maxInstances":1,
        "dateCreated":"[date]",
        "pauseOnFailedJob":false,
        "_teamId":"[teamId]",
        "name":"Job Name",
        "createdBy":"[userId]",
        "id":"[JobDef id]",
        "version":0,
        "type":"JobDef"
    }
}
                    

Schedule

A Schedule defines when a JobDef runs. A JobDef can have multiple Schedules but a Schedule can only be assigned to a single JobDef.

General Schedule Reference

• 1 Required only for date type Schedules
• 2 Consists of key value pairs defined in the Cron Schedule Reference – required for cron type Schedules
• 3 Consists of key value pairs defined in the Interval Schedule Reference – required for interval type Schedules

Cron Schedule Reference

This reference is to be used in connection with the General Schedule Reference above.

Interval Schedule Reference

This reference is to be used in connection with the General Schedule Reference above.

General Schedule Attribute Descriptions

id

Unique ID assigned when a new Schedule object is created.

_teamId

The ID of the Org object where the TaskDef is created.

createdBy

The ID of the user that created the Schedule.

lastUpdatedBy

The ID of the last user to modify the Schedule.

lastScheduledRunDate

The next date/time when the Schedule will be triggered.

nextScheduledRunDate

The last date/time when the Schedule was triggered.

name

The user created name for a Schedule.

isActive

If the isActive attribute is set to false no events for this Schedule will be triggered. If it is true future events will be triggered according to the Schedule but past skipped events will not be triggered.

TriggerType

The type of trigger that kicks off a schedule, including date, cron or interval.

RunDated

This object stores the date and time when a Schedule will execute if it has a date type Trigger.

Cron Schedule Attribute Descriptions

Year

The year in a cron TriggerType.

Month

The month in a cron TriggerType.

Day

The day in a cron TriggerType.

Week

The week in a cron TriggerType.

Day_Of_Week

The day of the week in a cron TriggerType.

Hour

The hour in a cron TriggerType.

Minute

The minute in a cron TriggerType.

Second

The second in a cron TriggerType.

Start_Date

The earliest date/time a Schedule can be triggered for a cron TriggerType.

End_Date

The latest date/time a Schedule can be triggered for a cron TriggerType.

Jitter

Will randomly advance or delay the scheduled start time for an event by jitter seconds for a cron TriggerType.

Interval Schedule Attribute Descriptions

Weeks

The weeks in an interval TriggerType.

Days

The days in an interval TriggerType.

Hours

The hours in an interval TriggerType.

Minutes

The minutes in an interval TriggerType.

Seconds

The seconds in an interval TriggerType.

Start_Date

The earliest date/time a Schedule can be triggered for an interval TriggerType.

End_Date

The latest date/time a Schedule can be triggered for an interval TriggerType.

Jitter

Will randomly advance or delay the scheduled start time for an event by jitter seconds for an interval TriggerType.

Sample Code

Create a Schedule

Request

curl --location --request POST 'https://saasglue.com/api/v0/schedule' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]' --header 'Content-Type: text/plain' \ --data-raw '{ "_teamId": "[teamId]]", "_jobDefId": "{jobDefId}", "name": "Schedule_1", "isActive": false, "TriggerType": "interval", "interval": { "Seconds": 5 } }'

Response

{
    "statusCode":201,
    "data":{
        "isActive":false,
        "_teamId":"[teamId]",
        "_jobDefId":"[jobDefId]",
        "name":"[Schedule name]",
        "TriggerType":"interval",
        "interval":{
            "Seconds":5
        },
        "createdBy":"[userId]",
        "lastUpdatedBy":"[userId]",
        "cron":{},
        "id":"[Schedule ID]",
        "version":0,
        "type":"Schedule"
    }
}
                    

Get Schedules for a JobDef

Request

curl --location --request GET 'https://saasglue.com/api/v0/schedule/?filter=_jobDefId%3D%3D[jobDefId]' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]' --data-raw ''

Response

{
    "statusCode":200,
    "data":[
        {
            "isActive":false,
            "_teamId":"[teamId]",
            "_jobDefId":"[jobDefId]",
            "name":"Schedule_1",
            "TriggerType":"interval",
            "interval":{
                "Seconds":5
            },
            "createdBy":"[userId]",
            "lastUpdatedBy":"[userId]",
            "cron":{},
            "id":"[Schedule ID]",
            "version":0,
            "type":"Schedule"
        }
    ],
    "meta":{
        "count":1
    }
}
                    

Script

The Script object stores the script code and information associated with the script file to make it usable in the saas glue environment.

Reference

Attribute Descriptions

id

Unique ID assigned when a new Script object is created.

_teamId

The ID of the Org object where the Script is created.

name

The Script name must be unique.

scriptType

SaaSGlue can be used to execute any script type. This attribute is added to the Script object to make it easier to work with common scripting languages. For example, the SaaSGlue cloud interface Script editor provides cues based on the script language. To use a script language not defined in SaaSGlue use type SH if the Script will run on Linux, Linux based or Mac operating systems and type CMD for Windows and then define the Command attribute either in the StepDef or when executing the Script from the Console.

The following script types are defined in SaaSGlue.

• 0 = PYTHON
• 1 = NODE
• 2 = SH
• 3 = CMD
• 4 = RUBY
• 5 = LUA
• 6 = PERL
• 7 = PHP
• 8 = POWERSHELL

code

The code of the script encoded with Base64.

_originalAuthorUserId

The ID of the user who first created the script.

_lastEditedUserId

The ID of the user who last edited a script

teamEditable

If set to TRUE anyone in the organization can edit the script.

lastEditedDate

The date and time the Script was last edited.

Sample Code

Create a new Script object

Request

curl --location --request POST 'https://saasglue.com/api/v0/script' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]' --header 'Content-Type: text/plain' \ --data-raw '{ "_teamId": "[teamId]", "name": "[Script name]", "scriptType": "[Script type]", "code": "[Base64 encoded code]", "lastEditedDate": "[Date]" }'

Response

{
    "statusCode":201,
    "data":{
        "teamUsable":true,
        "teamEditable":false,
        "_teamId":"[teamId]",
        "name":"[Script name]",
        "scriptType":2,
        "code":"[Base64 encoded code]",
        "_originalAuthorUserId":"[userId]",
        "_lastEditedUserId":"[userId]",
        "lastEditedDate":"[Date]",
        "shadowCopyCode":"[Base64 encoded code (copy)]",
        "id":"[Script id]",
        "version":0,
        "type":"Script"
    }
}
                    

Step

A Job consists of one or more Tasks, and a Task consists of one or more Steps.

A Step is the runtime implementation of a StepDef. Steps are only created when a containing Job is created. If a Job is created from a JobDef, a Step will be created in the Job for each StepDef in the JobDef. If a Job is created from a JSON template, a Step will be created in the Job for each StepDef embedded in the JSON.

Reference

Attribute Descriptions

id

Unique ID assigned when a new Step object is created.

_teamId

The ID of the Org object where the Step is created.

_jobId

The ID of the Job containing the Step.

_taskId

The ID of the Task containing the Step.

name

The Step name. Is inherited from the associated StepDef object or from a StepDef embedded in a JSON formatted Job template.

order

The order in which the Step will run in relation to other Steps in the same Task.

script

The ID of the Script the Step will execute.

command

This attribute can be used to specify the exact interpreter to use to execute the Step script. It can also be used to set arguments that should be passed to that interpreter. For example, to pass a class path to the scala interpreter. If not specified, the default interpreter for the script type will be used to execute the script.

For example, if you have a script of type python and the command attribute is not set, then the default python interpreter on the machine where the Step runs will be used to execute the script. If the command attribute is set to /usr/bin/python2.7, then the interpreter in that location on the Agent machine will be used to run the script. The interpreter specified by the command attribute must exist on the machine on which the Step runs.

arguments

A space delimited list of arguments which will be passed to the script upon execution. Syntax follows normal command line arguments, e.g. a single argument with spaces should be enclosed in quotes.

variables

Environment variables to set in the script runtime environment. Use this attribute to set environment variables required by the script which may not exist on the target machine(s) or which you want to override.

Sample Code

Get all Step objects in a Task

Request

curl --location --request GET 'https://saasglue.com/api/v0/step?filter=_taskId%3D%3D[taskId]' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]'

Response

{
    "statusCode":200,
    "data":[
        {
            "command":"",
            "arguments":"",
            "_teamId":"[teamId]",
            "_jobId":"[jobId]",
            "_taskId":"[taskId]",
            "name":"step1",
            "order":0,
            "script":{
                "id":"[scriptId",
                "name":"echo hello",
                "scriptType":2,
                "code":"ZWNobyAiSGVsbG8gV29ybGQi"
            },
            "id":"[Step id]",
            "version":0,
            "type":"Step"
        }
    ],
    "meta":{
        "count":1
    }
}
                    

StepDef

The StepDef object defines how a Step is to be Run within a Task.

Reference

Attribute Descriptions

id

Unique ID assigned when a new StepDef object is created.

_teamId

The ID of the Org object where the StepDef is created.

_taskDefId

The ID of the TaskDef object containing the StepDef.

name

The StepDef name. Must be unique among StepDefs within the TaskDef to which it belongs.

_scriptId

The ID of the script which Steps created from this StepDef will execute.

order

The order in which Steps created from the StepDef will run.

command

This attribute can be used to specify the exact interpreter to use to execute the script for Steps created from this StepDef. It can also be used to set arguments that should be passed to that interpreter. For example, to pass a class path to the scala interpreter. If not specified, the default interpreter for the script type will be used to execute the script.

For example, if you have a script of type python and the command attribute is not set, then the default python interpreter on the machine where the Step runs will be used to execute the script. If the command attribute is set to /usr/bin/python2.7, then the interpreter in that location on the Agent machine will be used to run the script. The interpreter specified by the command attribute must exist on the machine on which the Step runs.

arguments

A space delimited list of command line arguments which will be passed to the script upon execution. Syntax follows normal command line arguments, e.g. a single argument with spaces should be enclosed in quotes.

variables

Environment variables to set in the script runtime environment. Use this attribute to set environment variables required by the script which may not exist on the target machine(s) or which you want to override.

Sample Code

Create a StepDef object

Request

curl --location --request POST 'https://saasglue.com/api/v0/stepdef' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]' --header 'Content-Type: text/plain' \ --data-raw '{ "_teamId": "[teamId]", "_taskDefId": "[taskDefId]", "name": "[Step name]", "_scriptId": "[scriptId]", "order": "0", "arguments": "", "variables": "" }'

Response

{
    "statusCode":201,
    "data":{
        "_scriptId":"[scriptId]",
        "command":"",
        "arguments":"",
        "variables":{},
        "_teamId":"[teamId]",
        "_taskDefId":"[taskDefId]",
        "name":"step1",
        "order":0,
        "id":"[StepDef id]",
        "version":0,
        "type":"StepDef"
    }
}
                    

Get a single StepDef object

Request

curl --location --request GET 'https://saasglue.com/api/v0/stepdef/[stepDefId]' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]'

Response

{
    "statusCode":200,
    "data":{
        "_scriptId":"[ScriptId]",
        "command":"",
        "arguments":"",
        "variables":{},
        "_teamId":"[teamId]",
        "_taskDefId":"[TaskDefId]",
        "name":"step1",
        "order":0,
        "id":"[StepDef id]",
        "version":0,
        "type":"StepDef"
    }
}
                    

StepOutcome

The StepOutcome object stores the output of a Step execution. A Step can be executed at most once for each execution of the Task to which it belongs. Steps in a Task are executed in order until they all complete successfully or one fails. A Step is considered to have failed if it completes with a non-zero exit code.

Reference

Attribute Descriptions

id

Unique ID assigned when a new StepOutcome object is created.

_teamId

The ID of the Org object where the StepOutcome is created.

_jobId

The ID of the Job containing the Step.

_stepId

The Step ID from which the StepOutcome is derived.

_taskOutcomeId

The TaskOutcome object associated with the StepOutcome.

_invoiceId

The ID of the Invoice where the StepOutcome was billed.

machineId

The Machine ID where the Step executed.

ipAddress

The local IP address of the Machine where the Step executed.

name

The name of the step. This is inherited from the Step Object from which the StepOutcome is derived.

runCode

The script code that was executed in the Step. The code is encoded with Base64.

runtimeVars

A list of key-value pair “runtime variables” generated by this Step. These variables can be consumed/modified by subsequent Steps in the same Task and by subsequent Tasks in the same Job workflow.

stdout

The standard output generated by the Script execution.

stderr

Any errors generated by the Script execution.

exitCode

The Script exit code.

signal

The signal used to stop the Script execution If it was stopped externally. For example SIGTERM or SIGKILL.

status

The current status of the Script execution. Here are the possible values.

• 0 = NOT_STARTED
• 10 = RUNNING
• 15 = INTERRUPTED
• 20 = SUCCEEDED
• 21 = CANCELLED
• 22 = FAILED

dateStarted

The date and time the Script was started.

dateCompleted

The date and time the Script completed.

tail

The last five lines of the standard output. It will be updated as the Script creates additional stdout.

If the user configures the Script to pipe stdout to a file the tail attribute will not be updated during Script execution. However, any runtime variable values will be extracted from the file to which stdout is piped.

Sample Code

Get all StepOutcome objects for a TaskOutcome

Request

curl --location --request GET 'https://saasglue.com/api/v0/stepOutcome?filter=_taskOutcomeId%3D%3D[taskOutcomeId]' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]'

Response

{
    "statusCode":200,
    "data":[
        {
            "tail":[
                "start",
                "@kpo{\"outVal\": \"val\"}",
                "done"
            ],
            "lastUpdateId":2,
            "archived":false,
            "_teamId":"[teamId]",
            "_jobId":"[jobId]",
            "_stepId":"[stepId]",
            "_taskOutcomeId":"[taskOutcomeId]",
            "name":"[Step Name]",
            "machineId":"[Agent MachineId]",
            "ipAddress":"[Agent IP Address]",
            "runCode":"[Base64 encoded script code]",
            "status":20,
            "dateStarted":"[Date]",
            "dateCompleted":"[Date]",
            "exitCode":0,
            "runtimeVars":{
                "outVal":"val"
            },
            "signal":null,
            "stderr":"",
            "stdout":"start\n@kpo{\"outVal\": \"val\"}\ndone\n",
            "id":"[StepOutcome id]",
            "version":0,
            "type":"StepOutcome"
        }
    ],
    "meta":{
        "count":1
    }
}
                    

Task

A Job consists of one or more Tasks.

A Task is the runtime implementation of a TaskDef. Tasks are only created when a containing Job is created. If a Job is created from a JobDef, a Task will be created in the Job for each TaskDef in the JobDef. If a Job is created from a JSON template, a Task will be created in the Job for each TaskDef embedded in the JSON.

Reference

Attribute Descriptions

id

Unique ID assigned when a new TaskDef object is created.

_teamId

The ID of the Org object where the TaskDef is created.

_jobId

The ID of the Job containing the Task.

target

Defines which Agent(s) are qualified to run the Task.

• ALL_AGENTS - The Task will be routed to all Agents within the Org.
• SINGLE_AGENT - The Task will be routed to any single Agent in the Org.
• ALL_AGENTS_WITH_TAGS - The Task will be routed to all Agents with all tags in the requiredTags field for this Task.
• SINGLE_AGENT_WITH_TAGS - The Task will be routed to any single Agent with all tags in the requiredTags field for this Task.
• SINGLE_SPECIFIC_AGENT - The Task will be routed to a single specific Agent. The Agent ID must be listed in the targetAgentId attribute of the TaskDef object.

name

The Task name. Is inherited from the associated TaskDef object or from a TaskDef embedded in a JSON formatted Job template.

targetAgentId

The ID of the Agent where the Task will run. This attribute is only relevant if the target attribute is set to SINGLE_AGENT.

requiredTags

Executing Agents must have tags matching all tags in this attribute if the target attribute is set to SINGLE_AGENT_WITH_TAGS or ALL_AGENTS_WITH_TAGS.

For example if requiredTags is "[{'os': 'linux'}, {'java_installed': 'true'}]" then only Agents with matching tags will be considered to run the Task. The Agents may have additional tags not in the list of requiredTags and still be qualified.

fromRoutes

The names and optional route codes of preceding Tasks which must ALL be completed before the Task will be executed. For example "[ ['Task1'], ['Task2', 'ok'] ]" indicates that Task1 must be completed with any route (other than fail) and Task2 must be complete with route ok for the Task to execute.

Route codes are generated by Scripts within a Task by printing a formatted message to standard output. For example "print '@sgg{"route", "ok"}'" in a python script will generate the route ok for routing to downstream Tasks.

If a Task cannot be routed to based on prior route code dependencies it's status will be set to SKIPPED.

toRoutes

The names of Tasks to launch when the Task completes. This is different from the fromRoutes attribute in that every time the current Task completes every Task in toRoutes with a matching route will be launched. For example a toRoute value of "[ ['Task1'], ['Task2', 'ok'] ]" would result in Task1 and Task2 getting launched if the current task completes with route ok.

If the current Task targets multiple agents (target = ALL_AGENTS or ALL_AGENTS_WITH_TAGS) and the current Task completes multiple times, the matching toRoute Tasks will be launched for each successful completion of the current Task.

sourceTaskRoute

For Tasks that were routed to with a to route, the Task id and route that preceded this Task, eg { sourceTaskOutcomeId: [id], sourceRoute: [route] }

artifacts

A list of Artifact IDs to be used to execute the Task. Artifacts can include configuration files, compiled java, .net or native code, datafiles, or any other file required to execute the Scripts in a Task. Artifacts are saved on the Org level and can be uploaded via the API or the web console.

status

The current Task status.

• NOT_STARTED = 0
• PUBLISHED = 5
• RUNNING = 10
• INTERRUPTING = 14
• INTERRUPTED = 15
• CANCELING = 17
• SUCCEEDED = 20
• CANCELLED = 21
• FAILED = 22
• SKIPPED = 23

error

Text of any error that occurred running the Task.

failureCode

The failure code for a Task with FAILED status.

• AGENT_CRASHED_OR_LOST_CONNECTIVITY = 0
• NO_AGENT_AVAILABLE = 1
• AGENT_EXEC_ERROR = 2
• QUEUED_TASK_EXPIRED = 3
• TARGET_AGENT_NOT_SPECIFIED = 4
• MISSING_TARGET_TAGS = 5

runtimeVars

A list of key-value pair runtime variables which will be used to execute scripts in the Steps for this Task. These variables can be dynamically injected at runtime in script arguments, environment variables or in scripts themselves.

Strings formatted as sgg("[variable name]") in script arguments, environment variables or scripts will be replaced with the most recent value of the runtime variable named [variable name]. If a runtime variable with that name does not exist, it will be replaced with null.

Runtime variable values can be set at design time on the Org or JobDef level. They can be set at runtime when Jobs are created and they can be dynamically generated/modified during script execution by printing correctly formatted strings to stdout. The format is @sgo{"[key]": "[value]"}, e.g. the following line in a python script would set the value of "my_key" to "my_value": print('@sgo{"my_key": "my_value"}').

TTL

The time (in milliseconds) to wait for a task to be picked up by an Agent for processing before routing the task with status fail.

Code Sample

Get all Task objects in a Job

Request

curl --location --request GET 'https://saasglue.com/api/v0/task?filter=_jobId%3D%3D[teamId]' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]'

Response

{
    "statusCode":200,
    "data":[
        {
            "fromRoutes":[],
            "toRoutes":[],
            "artifacts":[],
            "status":22,
            "_teamId":"[teamId]",
            "_jobId":"[jobId]",
            "name":"[Task name]",
            "targetAgentId":null,
            "requiredTags":{
                "numchucks":"true"
            },
            "target":4,
            "runtimeVars":{},
            "TTL":null,
            "failureCode":1,
            "id":"[Task id]",
            "version":0,
            "type":"Task"
        }
    ],
    "meta":{
        "count":1
    }
}
                    

TaskDef

The TaskDef object defines how a Task is to be run within a Job.

Reference

Attribute Descriptions

id

Unique ID assigned when a new TaskDef object is created.

_teamId

The ID of the Org object where the TaskDef is created.

_jobDefId

The ID of the JobDef containing the TaskDef.

target

Defines which Agent(s) are qualified to run Tasks created from this TaskDef.

• ALL_AGENTS - The Task will be routed to all Agents within the Org.
• SINGLE_AGENT - The Task will be routed to any single Agent in the Org.
• ALL_AGENTS_WITH_TAGS - The Task will be routed to all Agents with all tags in the requiredTags field for this Task.
• SINGLE_AGENT_WITH_TAGS - The Task will be routed to any single Agent with all tags in the requiredTags field for this Task.
• SINGLE_SPECIFIC_AGENT - The Task will be routed to a single specific Agent. The Agent ID must be listed in the targetAgentId attribute of the TaskDef object.

name

The TaskDef name. Must be unique among TaskDefs within the JobDef to which it belongs.

targetAgentId

The ID of the Agent where Tasks created from the TaskDef will run. This attribute is only relevant if the target attribute is set to SINGLE_AGENT.

requiredTags

Executing Agents must have tags matching all tags in this attribute if the target attribute is set to SINGLE_AGENT_WITH_TAGS or ALL_AGENTS_WITH_TAGS.

For example if requiredTags is [{'os': 'linux'}, {'java_installed': 'true'}] then only Agents with matching tags will be considered to run Tasks created from the TaskDef. The Agents may have additional tags not in the list of requiredTags and still be qualified.

fromRoutes

The names and optional route codes of preceding Tasks which must ALL be completed before a Task created from this TaskDef will be executed. For example [ ['Task1'], ['Task2', 'ok'] ] indicates that Task1 must be completed with any route (other than fail) and Task2 must be complete with route ok for the Task to execute.

Route codes are generated by Scripts within a Task by printing a formatted message to standard output. For example print '@sgg{"route", "ok"}' in a python script will generate the route ok for routing to downstream Tasks.

If a Task cannot be routed to based on prior route code dependencies it's status will be set to SKIPPED.

toRoutes

The names of Tasks to launch when the Task completes. This is different from the fromRoutes attribute in that every time the current Task completes every Task in toRoutes with a matching route will be launched. For example a toRoute value of [ ['Task1'], ['Task2', 'ok'] ] would result in Task1 and Task2 getting launched if the current task completes with route ok.

If the current Task targets multiple agents (target = ALL_AGENTS or ALL_AGENTS_WITH_TAGS) and the current Task completes multiple times, the matching toRoute Tasks will be launched for each successful completion of the current Task.

artifacts

A list of Artifact IDs to be used to execute a Task created from the TaskDef. Artifacts can include configuration files, compiled java, .net or native code, datafiles, or any other file required to execute the Scripts in a Task. Artifacts are saved on the Org level and can be uploaded via the API or the web console.

TTL

The time (in milliseconds) to wait for a task to be picked up by an Agent for processing before routing the task with status fail.

Code Sample

Create a TaskDef object

Request

curl --location --request POST 'https://saasglue.com/api/v0/taskdef' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]' --header 'Content-Type: text/plain' \ --data-raw '{ "name": "[Task name]", "_teamId": "[teamId]", "_jobDefId": "[jobDefId]]", "requiredTags": [], "runOnAllAgents": "false", "fromRoutes": [], "target": 0 }'

Response

{
    "statusCode":201,
    "data":{
        "fromRoutes":[],
        "toRoutes":[],
        "artifacts":[],
        "name":"[Task name]",
        "_teamId":"[teamId]",
        "_jobDefId":"[jobDefId]",
        "requiredTags":[],
        "target":0,
        "id":"[TaskDef id]",
        "version":0,
        "type":"TaskDef"
    }
}
                    

Get a single TaskDef object

Request

curl --location --request GET 'http://saasglue.com/api/v0/taskdef/[TaskDef id]]' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]]'

Response

{
    "statusCode":200,
    "data":{
        "fromRoutes":[],
        "toRoutes":[],
        "artifacts":[],
        "name":"[Task name]",
        "_teamId":"[teamId]",
        "_jobDefId":"[jobDefId]",
        "requiredTags":[],
        "target":0,
        "id":"[TaskDef id]",
        "version":0,
        "type":"TaskDef"
    }
}
                    

TaskOutcome

The TaskOutcome object stores the output of a Task execution. Since a single Task can be executed multiple times in a Job, a Task can have multiple TaskOutcomes.

Reference

Attribute Descriptions

id

Unique ID assigned when a new TaskOutcome object is created.

_teamId

The ID of the Org object where the TaskOutcome is created.

_jobId

The ID of the Job containing the TaskOutcome.

_taskId

The Task ID from which the TaskOutcome is derived.

_agentId

The ID of the Agent that executed the Task.

sourceTaskRoute

For Tasks that were routed to with a to route, the Task id and route that preceded this Task, eg { sourceTaskOutcomeId: [id], sourceRoute: [route] }

target

Defines which Agent(s) are qualified to run the Task.

• ALL_AGENTS - The Task will be routed to all Agents within the Org.
• SINGLE_AGENT - The Task will be routed to any single Agent in the Org.
• ALL_AGENTS_WITH_TAGS - The Task will be routed to all Agents with all tags in the requiredTags field for this Task.
• SINGLE_AGENT_WITH_TAGS - The Task will be routed to any single Agent with all tags in the requiredTags field for this Task.
• SINGLE_SPECIFIC_AGENT - The Task will be routed to a single specific Agent. The Agent ID must be listed in the targetAgentId attribute of the TaskDef object.

status

This attribute stores the current status of the Task execution.

• NOT_STARTED = 0
• PUBLISHED = 5
• RUNNING = 10
• INTERRUPTING = 14
• INTERRUPTED = 15
• CANCELING = 17
• SUCCEEDED = 20
• CANCELLED = 21
• FAILED = 22
• SKIPPED = 23

route

The route used to determine the conditional path for Tasks subsequent to the TaskOutcome.

The default route code is blank if a Task completes successfully, fail if a Task does not complete successfully and interrupt if a Task is interrupted intentionally. A Task can be interrupted by sending a SIGTERM/SIGKILL signal to the Agent process (equivalent to CTRL+C), which interrupts all running processes, or via the API or Web application.

Routes can also be set during script execution by printing a correctly formatted string to stdout. The format is @sgo{"route": "[route]"}, e.g. the following line in a python script would set the route to "ok": print('@sgo{"route": "ok"}').

failureCode

The failure code for a TaskOutcome with FAILED status.

• AGENT_CRASHED_OR_LOST_CONNECTIVITY = 0
• NO_AGENT_AVAILABLE = 1
• AGENT_EXEC_ERROR = 2
• QUEUED_TASK_EXPIRED = 3
• TARGET_AGENT_NOT_SPECIFIED = 4
• MISSING_TARGET_TAGS = 5

dateStarted

The date and time when the Task started.

dateCompleted

The date and time when the Task completed.

ipAddress

The IP address of the Machine where the Task was executed.

machineId

The ID of the Machine where the Task was executed.

artifactsDownloadedSize

The total size of the Artifacts downloaded for this task, measured in bytes.

runtimeVars

A list of key-value pair runtime variables generated by this Task. These variables can be consumed/modified by subsequent Tasks in the same Job workflow.

Actions

interrupt

Interrupt a running Task. Task status must be RUNNING. taskoutcomeaction/interrupt/:taskOutcomeId

restart

Restart a Task. Task status must be INTERRUPTED or FAILED. taskoutcomeaction/restart/:taskOutcomeId

cancel

Cancel a Task. Task status must be RUNNING or INTERRUPTED. taskoutcomeaction/cancel/:taskOutcomeId

Sample Code

Get all TaskOutcome objects from a Task

Request

curl --location --request GET 'https://saasglue.com/api/v0/taskOutcome?filter=_taskId%3D%3D[taskId]' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]'

Response

{
    "statusCode":200,
    "data":[
        {
            "_teamId":"[teamId]",
            "_jobId":"[jobId]",
            "_taskId":"[taskId]",
            "dateStarted":"[date]",
            "ipAddress":"",
            "machineId":"",
            "artifactsDownloadedSize":0,
            "target":4,
            "runtimeVars":{},
            "failureCode":1,
            "status":22,
            "id":"[TaskOutcome id]",
            "version":0,
            "type":"TaskOutcome"
        }
    ],
    "meta":{
        "count":1
    }
}
                    

TeamVariable

TeamVariables have team-wide scope. They are useful for storing variables needed in Jobs across the team.

Reference

Attribute Descriptions

id

Unique ID assigned when a new TeamVariable object is created.

_teamId

The ID of the Team object where the TeamVariable is created.

name

The TeamVariable key.

value

The TeamVariable value.

Sample Code

Create a new TeamVariable

Request

curl --location --request POST 'https://saasglue.com/api/v0/teamvar' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]' --header 'Content-Type: text/plain' \ --data-raw '{ "name" : "[key]]", "value" : "[value]]" }'

Response

{
    "statusCode":201,
    "data":{
        "name":"[key]",
        "value":"[value]",
        "_teamId":"[teamId]",
        "id":"[TeamVariable ID]",
        "version":0,
        "type":"TeamVariable"
    }
}
                    

Get all TeamVariables

Request

curl --location --request GET 'https://saasglue.com/api/v0/teamvar' --header 'Content-Type: application/json' --header 'Auth: [auth token]' --header '_teamId: [teamId]' --data-raw ''

Response

{
    "statusCode":200,
    "data":[
        {
            "_teamId":"[teamId]",
            "name":"[name]",
            "value":"[value]",
            "id":"[TeamVariable ID]",
            "version":0,
            "type":"TeamVariable"
        }
    ],
    "meta":{
        "count":1
    }
}
                    

Delete an TeamVariable

Request

curl --location --request DELETE 'https://saasglue.com/api/v0/teamvar/[teamVariableId]' --header 'Content-Type: application/json' --header 'auth: [auth token]' --header '_teamId: [teamId]' --data-raw ''

Response

{
    "statusCode":200,
    "data":{
        "n":1,
        "ok":1,
        "deletedCount":1
    }
}