Task

Task is a general definition of a job that should be further defined and scheduled by using schedule resource. Task is identified by it’s id, name, description and type. Based on a type of a task, different definitions are given to its command and args fields.

Scheme:

{
  "id": "UUID",
  "name": "String",
  "description": "String",
  "type": "String",
  "command": "JSON",
  "args": "JSON"
}

Example:

{
  "id": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
  "name": "fetch defects by part",
  "description": "use to fetch defects from Defects BB",
  "type": "WebRequest",
  "command": {
    "method": "get",
    "uri": "https://defects.hid.facts4.work/api/defects",
    "params": {
      "access_token": "${f4w_access_token}",
      "part_id": "${part_id}"
    }
    "body": {}
  }
  "args": {
    "part_id": "used for filtering, define it in Schedule"
  }
}

Task Types

Every task has to have a type that defines what fields can be passed in the command object and how the task is executed.

Currently the only type supported is “WebRequest” (case-sensitive) that will execute a web request when scheduled. The allowed fields for command are following:

{
  "method": "String",
  "uri": "String",
  "params": "JSON",
  "body": "JSON"
}

WebRequest field are used for defining the HTTP request type (method) and defining the endpoint for the action (uri). params field can be used to define an HTTP query string (see examples) and body field is the HTTP payload (see examples).

Command Escaping

You can include values from other resources in the definition of a task to make it reusable for different schedules. The special character sequence for escaping values starts with ${ and ends with }. Based on the key inside these symbols a value will be inserted following this order:

  • Authentications: ${f4w_access_token} is substituted with Authentication resource with provider == 'f4w'. For other providers (not supported now) you could insert ${provider-name_access_token}
  • Schedule.args: for every ${arg_key} found in the Task.command we search for a Task.args field with the key == arg_key. If it is found, value inserted is the one defined in the Schedule.args.arg_key
  • EnvironmentVariables: All the remaining ${arg_key} found in Task.command are confronted with EnvironmentVariables. If an EnvironmentVariable with key == arg_key is found the its value is inserted in the Task.

If the ${arg_key} is not found anywhere among Authentications, Schedules and EnvironmentVariables, then it is left as is.

In order to insert special symbol ${ without risk of escaping unwanted values, it is recommended to prepend it with $. For example, ${shake} be or not $${shake} be would be escaped as to be or not ${shake} be if there is somewhere a Schedule or EnvironmentVariable with "shake": "to".

GET methods

GET /api/v1/tasks

Returns all tasks with their relative information if at least one resource exists, otherwise returns an empty collection. Request can contain a page parameter that returns a specific page, additionally total number of pages, next page, previous page and other information are described in the response header.

Example request:

GET /api/v1/tasks HTTP/1.1
Host: https://scheduler.hid.facts4.work

Example response:

HTTP/1.1 200 OK
Content-type: application/json

[
  {
    "id": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
    "name": "fetch defects by part",
    "description": "use to fetch defects from Defects BB",
    "type": "WebRequest",
    "command": {
      "method": "get",
      "uri": "https://defects.hid.facts4.work/api/defects",
      "params": {
        "access_token": "${f4w_access_token}",
        "part_id": "${part_id}"
      }
      "body": {}
    }
    "args": {
      "part_id": "used for filtering, define it in Schedule"
    }
  }
]
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Response JSON Array of Objects:
 
  • id (string) – id of the task
  • name (string) – name of the task
  • description (string) – description of the task
  • type (string) – type of the task
  • command (json) – command hash with needed field per type
  • args (json) – argument descriptions that should be defined in Schedule
Status Codes:
GET /api/v1/tasks/:id

Returns a specific tas with :id and the rest of its parameters if it exists, otherwise returns 404 error.

Example request:

GET /api/v1/task/5880f2f1-e548-4db5-9ef3-3e23954689f4 HTTP/1.1
Host: https://scheduler.hid.facts4.work

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
  "name": "fetch defects by part",
  "description": "use to fetch defects from Defects BB",
  "type": "WebRequest",
  "command": {
    "method": "get",
    "uri": "https://defects.hid.facts4.work/api/defects",
    "params": {
      "access_token": "${f4w_access_token}",
      "part_id": "${part_id}"
    }
    "body": {}
  }
  "args": {
    "part_id": "used for filtering, define it in Schedule"
  }
}
Parameters:
  • id (string) – task’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Response JSON Object:
 
  • id (string) – id of the task
  • name (string) – name of the task
  • description (string) – description of the task
  • type (string) – type of the task
  • command (json) – command hash with needed field per type
  • args (json) – argument descriptions that should be defined in Schedule
Status Codes:

POST methods

POST /api/v1/tasks

Adds a new task. id is generated server-side. Returns the new resource or error message.

Note: Do not execute twice the same POST request for it will create two resources with the same information.

Example request:

POST /api/v1/tasks HTTP/1.1
Host: https://scheduler.hid.facts4.work
Content-Type: application/json

{
  "name": "fetch defects by part",
  "description": "use to fetch defects from Defects BB",
  "type": "WebRequest",
  "command": {
    "method": "get",
    "uri": "https://defects.hid.facts4.work/api/defects",
    "params": {
      "access_token": "${f4w_access_token}",
      "part_id": "${part_id}"
    }
    "body": {}
  }
  "args": {
    "part_id": "used for filtering, define it in Schedule"
  }
}

Example response:

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
  "name": "fetch defects by part",
  "description": "use to fetch defects from Defects BB",
  "type": "WebRequest",
  "command": {
    "method": "get",
    "uri": "https://defects.hid.facts4.work/api/defects",
    "params": {
      "access_token": "${f4w_access_token}",
      "part_id": "${part_id}"
    }
    "body": {}
  }
  "args": {
    "part_id": "used for filtering, define it in Schedule"
  }
}
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Object:
 
  • name (string) – name of the task
  • description (string) – description of the task
  • type (string) – type of the task
  • command (json) – command hash with needed field per type
  • args (json) – argument descriptions that should be defined in Schedule
Response JSON Object:
 
  • id (string) – id of the task
  • name (string) – name of the task
  • description (string) – description of the task
  • type (string) – type of the task
  • command (json) – command hash with needed field per type
  • args (json) – argument descriptions that should be defined in Schedule
Status Codes:

PUT methods

PUT /api/v1/tasks/:id

Updates an existing task with new information. Returns the new resource or error message.

Note: All parameters must be defined with the PUT request, ie. PUT request replaces the existing resource with the modified one if it exists, or creates a new one.

Example request:

PUT /api/v1/tasks/5880f2f1-e548-4db5-9ef3-3e23954689f4 HTTP/1.1
Host: https://scheduler.hid.facts4.work
Content-Type: application/json

{
  "name": "fetch defects by part",
  "description": "change the description",
  "type": "WebRequest",
  "command": {
    "method": "get",
    "uri": "https://defects.hid.facts4.work/api/defects",
    "params": {
      "access_token": "${f4w_access_token}",
      "part_id": "${part_id}"
    }
    "body": {}
  }
  "args": {
    "part_id": "used for filtering, define it in Schedule"
  }
}

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "5880f2f1-e548-4db5-9ef3-3e23954689f4",
  "name": "change the description",
  "description": "use to fetch defects from Defects BB",
  "type": "WebRequest",
  "command": {
    "method": "get",
    "uri": "https://defects.hid.facts4.work/api/defects",
    "params": {
      "access_token": "${f4w_access_token}",
      "part_id": "${part_id}"
    }
    "body": {}
  }
  "args": {
    "part_id": "used for filtering, define it in Schedule"
  }
}
Parameters:
  • id (string) – task’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Object:
 
  • name (string) – name of the task
  • description (string) – description of the task
  • type (string) – type of the task
  • command (json) – command hash with needed field per type
  • args (json) – argument descriptions that should be defined in Schedule
Response JSON Object:
 
  • id (string) – id of the task
  • name (string) – name of the task
  • description (string) – description of the task
  • type (string) – type of the task
  • command (json) – command hash with needed field per type
  • args (json) – argument descriptions that should be defined in Schedule
Status Codes:

DELETE methods

DELETE /api/v1/tasks/:id

Delete an existing task, responds with the confirmation or error. Can only delete one resource at a time, to remove a collection of machines call the DELETE method for each element.

Example request:

DELETE /api/v1/tasks/5880f2f1-e548-4db5-9ef3-3e23954689f4 HTTP/1.1
Host: https://scheduler.hid.facts4.work

Example response:

HTTP/1.1 200 OK
Parameters:
  • id (string) – task’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Status Codes: