Skip to content

Task System

Tasks for remote command execution

Our platform uses a task system to communicate with the Host Agents installed on all your hosts (BM and VM). A Task as such is a wrapper for one or more commands sent to a Host Agent. This wrapper keeps track of which command is currently being executed and its execution status. A Task can also contain a schedule time, allowing Tasks to be performed somewhere in the future. You can find an API example below.

Task Actions

Tasks are made up of TaskAction elements, each describing a single command to be executed by a host agent. A Task consists of one or more TaskActions. Each TaskAction has a status field to inform you about the result of command execution.

Task Action Examples

Here are some examples of TaskAction types, to give you an idea:

  • Download a build archive (e.g. your game server build, or a sidecar build)
  • Extract a build archive
  • Stop an instance
  • Deploy a build [to an instance]
  • Start an instance

These are the most frequently used actions and are also basic building blocks with which we can can deploy / update / control your instances. These actions also exactly describe an instance deployment task. So whenever any type of instance is deployed for you, we create a task containing the actions described above. These 6 actions are combined into 1 Task.

Here is a more thorough example of the actions of an instance deployment Task. These also contain the parameters that each action requires in order to operate properly: 

[
    {
        "idx": 0,
        "actionType": "Download software build",
        "requiredParams": {
            "buildId": "The ID of the applicationBuild. Its build archive will be downloaded."
        }
    },
    {
        "idx": 1,
        "actionType": "Extract software build",
        "requiredParams": {
            "buildId": "The ID of the applicationBuild. This action will extract the build archive that has been downloaded."
        }
    },
    {
        "idx": 2,
        "actionType": "Stop instance",
        "requiredParams": {
            "methodId": "The ID of the stop-method, indicating how you want to stop the application instance.",
            "timeout": "If the stop-method is graceful, you can indicate a maximum time to wait here, before the application instance is forcefully terminated."
        }
    },
    {
        "idx": 3,
        "actionType": "Deploy software build to instance",
        "requiredParams": {
            "buildId": "The ID of the applicationBuild. This action expects the build archive to already have been downloaded and extracted onto the host."
        }
    },
    {
        "idx": 4,
        "actionType": "Start instance",
        "requiredParams": null
    }
]

Task Status (API example)

When you create a Task, you will be given a Task ID. With this ID you can at any time check the status of the task. when doing that via the API you will get something like this:

HTTP request

GET /v3/applicationInstance/task/12278257

Request body

none

Response body

[
    {
        "id": 12278257,
        "batchId": 0,
        "categoryId": 2,
        "entityId": 2897954287466354361,
        "currentActionIdx": 6,
        "executeAt": 1563469175,
        "lastActivityAt": 1563469176,
        "finishedAt": 1563469176,
        "resultCode": 127,
        "resultText": "Done"
    }
]

Property Description
id The Task ID
batchId The TaskBatch ID, in case this Task was part of a larger batch
categoryId Task category. Normally 2, meaning ApplicationInstance
entityId The ID of the entity (application instance) this Task was performed on
currentActionIdx Index of the TaskAction currently being executed. If the Task itself is yet to be performed, this will be -1
executeAt If 0, the Task will be executed as soon as possible. Otherwise it contains the unix timestamp of when the Task has been or will be executed
lastActivityAt Unix timestamp of when the system received a sign of life for this Task
finishedAt Unix timestamp of when this task finished processing
resultCode The result of the Task in numerical form
resultText The result of the Task in human readable form
Table 1: Task element structure

Task Result Codes

A Task will reflect its status through the resultCode property. It will be one of the following values:

  • 0: Pending Task execution
  • 1: In progress
  • 2: Paused
  • 124: Cancelled
  • 125: Timed out
  • 126: Done, with error (the error can be found in the resultText field
  • 127: Done

Task Batch

When executing the same command for multiple application instances, we create a task per instance and collect them all within a TaskBatch. When a TaskBatch is submitted, you will be given a TaskBatch ID. This allows you to easily track the execution result of all tasks within a batch.

HTTP request

GET /v3/applicationInstance/taskBatch/9

Request body

none

Response body

[
    {
        "id": 9,
        "createdAt": 1559829929,
        "executeAt": 1559829929,
        "finishedAt": 1559829934,
        "numTasks": 8,
        "numTasksOk": 8,
        "numTasksFailed": 0,
        "numTasksCancelled": 0,
        "taskIds": {
            "11238257": 127,
            "11238258": 127,
            "11238259": 127,
            "11238260": 127,
            "11238261": 127,
            "11238262": 127,
            "11238263": 127,
            "11238264": 127
        }
    }
]

Property Value type Description
id int A unique TaskBatch identifier
createdAt int Unix timestamp of creation time
executeAt int Unix timestamp of execution time
finishedAt int Unix timestamp of when the last Tasks was finished executing
numTasks int Total number of Tasks in this TaskBatch
numTasksOk int Number of successfully executed Tasks
numTasksFailed int Number of failed Tasks
numTasksCancelled int Number of cancelled Tasks
taskIds [int] Array of key-value pairs indicating Task ID vs Task Result Code
Table 2: TaskBatch element structure

Cancelling a Task

You can cancel a (scheduled) Task by calling DELETE /v3/applicationInstance/task/{taskId}.

The Task's result code will then be set to 124 (Cancelled).

Note

At this time, there is no roll-back mechanism for already performed actions.

Pausing a Task

You can pause a (running) task by calling PUT /v3/applicationInstance/task/{taskId}.

To un-pause a paused Task, call the same endpoint.

Note that when a Task is paused, no other Tasks for the same ApplicationInstance can be run, until the paused Task is un-paused and finished again.