Instance methods

GET /api/1/environments/(envId)/instances

Returns list of instances launched in given environment.

Parameters:
  • envId (uuid) – id of environment
Status Codes:

Response body:

[
  {
    "id" : "50dd88bee4b082b7a96d072e",
    "name" : "Public site",
    "environment" : "51cc3fa3e4b0d80937fda204",
    "application" : "5878f3173d06cd26897ed1e3",
    "revision" : "4fc905cee4b00ca256e2e355",
    "status": "Running"
  },
  ...
]
GET /api/1/applications/(appId)/instances

Returns list of instances for given application.

Parameters:
  • appId (uuid) – id of the application
Status Codes:

Response body:

[
  {
    "id" : "50dd88bee4b082b7a96d072e",
    "name" : "Public site",
    "environment" : "51cc3fa3e4b0d80937fda204",
    "application" : "5878f3173d06cd26897ed1e3",
    "revision" : "4fc905cee4b00ca256e2e355"
    "status": "Running"
  },
  ...
]

See also: How to find a particular application instance?

GET /api/1/revisions/(revId)/instances

Returns list of instances for given revision.

Parameters:
  • revId (uuid) – id of revision
Status Codes:

Response body:

[
  {
    "id" : "50dd88bee4b082b7a96d072e",
    "name" : "Public site",
    "environment" : "51cc3fa3e4b0d80937fda204",
    "application" : "5878f3173d06cd26897ed1e3",
    "revision" : "4fc905cee4b00ca256e2e355"
    "status": "Running"
  },
  ...
]
GET /api/1/instances/(uuid: id)

Retrieves the application instance status.

Parameters:
  • id (uuid) – id of the application instance
Status Codes:

Response body:

{
  "id": (instance-id),
  "name": (instance-name),
  "version": (manifest-version),
  "parameters": {
    (parameter-name): (parameter-value),
    ...
  },
  "status": (instance-status),
  "ownerId": (instance-owner),
  "workflowHistory": [
    {
      "name": (job-name),
      "status": (job-status),
      "ownerId" (job-owner),
      "steps": [
        {
          "name": (step-name)
          "status": (step-status)
          "percentComplete": (step-progress)
        },
        ...
      ]
    },
    ...
  ],
  "returnValues": {
    (property-name): (property-value),
    ...
  },
  "applicationId": (application-id),
  "environmentId": (environment-id),
  "components": [
    {
      "name": (component-name),
      "instanceId": (component-instance-id)
    },
    ...
  ]
}
  • id (uuid): requested instance ID.
  • name (string): requested instance name, as seen on the UI.
  • version (int): version of the application manifest used to launch this instance.
  • parameters: configuration parameters of the instance in the form of parameter-name to parameter-value map. In component applications each parameter-name consists of two parts: interface-name.pin-name.
  • status (string): current instance status, can be one of the following values:
    • Requested: the instance is launching.
    • Running: the instance is launched and ready to work.
    • Executing: the instance is busy since it’s executing one or more jobs.
    • Failed: the instance failed to complete one or more jobs.
    • Destroying: the instance is destroying.
    • Destroyed: the instance is destroyed.
  • ownerId (uuid): ID of the user who has launched the instance.
  • workflowHistory: contains information on executing and completed jobs.
    • name (string): job name.
    • status (string): job status, one of the following values:
      • Executing: the job is executing.
      • Succeeded: the job completed successfully.
      • Failed: the job failed to complete.
    • ownerId (uuid): ID of the user who has executed the job.
    • steps: contains brief information about the current workflow steps.
      • name (string): step name.
      • status (string): step status, takes one of the following values:
        • Requested: the step is queued for execution but has not started yet.
        • Executing: the step is executing.
        • Succeeded: the step completed successfully.
        • Failed: the step failed to complete.
      • percentComplete (int): step progress in percents, 0 to 100.
  • returnValues: properties of the instance in the form of in the form of property-name to property-value map. In component applications each property-name consists of two parts: interface-name.pin-name.
  • applicationId (uuid): ID of the application that the instance belongs to.
  • environmentId (uuid): ID of the environment used to launch this instance.
  • components: in case of an hierarchical application enumerates components and their respective instance IDs; empty for applications with non-component manifests.
    • name (string): component name.
    • instanceId (optional uuid): ID of the component instance if the component refers to an external application.
POST /api/1/instances/(uuid: id)/(workflow)

Runs the specified application instance workflow.

Parameters:
  • id (uuid) – id of the instance to use
  • workflow (string) – name of the workflow to run
Status Codes:
  • 200 OK – success
  • 400 Bad Request – the content type is incorrect or the request body is not valid JSON
  • 401 Unauthorized – the specified credentials are not valid
  • 403 Forbidden – the user is not authorized to launch this workflow (destroy requires EditInstance permission) or the instance belongs to a submodule
  • 404 Not Found – the specified instance doesn’t exist
  • 409 Conflict – it is not allowed to run workflow currently since another workflow is already running

Request body: JSON-encoded workflow parameters. Note, that parameters of any type should be converted to string by wrapping to json:

{
  "stringParam": "test",
  "intParam": "42",
  "listParam": "[1, 2, \"ok\"]"
}

Response body:

{
  "id": (instance-id)
}

Response values:

  • id (uuid): the current instance id.
PUT /api/1/instances/(uuid: id)/userData

Associates user data with the instance.

Parameters:
  • id (uuid) – id of the instance to use
Status Codes:
  • 200 OK – success
  • 400 Bad Request – incorrect content type of json is not valid or json does not have plain string keys on the top level
  • 403 Forbidden – user in not authorized to edit specified instance
  • 404 Not Found – specified instance does not exist

Request body: JSON-encoded user data

{
  "key1" : ["a", "b"],
  "key2" : "some data"
}
DELETE /api/1/instances/(uuid: id)?(int: force)=<1|0>

Deletes the instance

Parameters:
  • id (uuid) – id of the application instance
  • force (int) – optional (default 0), specifies whether the instance should be deleted even if it is active, attempts to shutdown the instance gracefully before deleting its records
Status Codes:

Response body:

{}
POST /api/1/instances/(uuid: id)/(workflow)/schedule

Schedules the specified application instance workflow at the specified time interval.

Parameters:
  • id (uuid) – id of the instance to use
  • workflow (string) – name of the workflow to schedule
Status Codes:
  • 200 OK – success
  • 400 Bad Request – the content type is incorrect or the request body is not valid JSON
  • 401 Unauthorized – the specified credentials are not valid
  • 403 Forbidden – the user is not authorized to launch this workflow (destroy requires EditInstance permission) or the instance belongs to a submodule
  • 404 Not Found – the specified instance doesn’t exist

Request body: JSON-encoded schedule time interval and workflow parameters:

{
  "interval": "3600000",
  "parameters": {
    "stringParam": "test",
    "intParam": "42",
    "listParam": "[1, 2, \"ok\"]"
  }
}
  • interval: schedule time interval in milliseconds, 0 to execute the workflow immediately.

  • parameters: workflow parameters.

    Note

    Workflow parameters of any type should be converted to string by wrapping into JSON as shown in the sample code block above.

Response body:

{
  "id": "588b3a8e3d064ba646378e70"
}
  • id: ID of the scheduled workflow; if no ID returned then the workflow has been started immediately.
POST /api/1/instances/(uuid: id)/(workflow)/reschedule

Re-schedules the specified scheduled workflow at the other time interval.

Parameters:
  • id (uuid) – id of the instance to use
  • workflow (string) – ID or name of the scheduled workflow to re-schedule
Status Codes:
  • 200 OK – success
  • 400 Bad Request – the content type is incorrect or the request body is not valid JSON
  • 401 Unauthorized – the specified credentials are not valid
  • 403 Forbidden – the user is not authorized to launch this workflow (destroy requires EditInstance permission) or the instance belongs to a submodule
  • 404 Not Found – the specified instance doesn’t exist

Request body: JSON-encoded new schedule time interval and workflow parameters:

{
  "interval": "3600000",
  "parameters": {
    "stringParam": "test",
    "intParam": "42",
    "listParam": "[1, 2, \"ok\"]"
  }
}
  • interval: schedule time interval in milliseconds, 0 to cancel the workflow schedule

  • parameters: workflow parameters.

    Note

    Workflow parameters of any type should be converted to string by wrapping into JSON as shown in the sample code block above.

Response body:

{
  "id": "588b3a8e3d064ba646378e70"
}
  • id: ID of the scheduled workflow; if no ID returned then the workflow schedule has been cancelled.
GET /api/1/instances/(uuid: id)/schedules

Lists scheduled workflows of the specified application instance.

Parameters:
  • id (uuid) – id of the application instance
Status Codes:

Response body:

{
  "schedules": [
    {
      "id": "588b41493d0694c32949661d",
      "name": "destroy",
      "timestamp": 1021182000000
    },
    {
      "id": "588b41563d064ba646378e7e",
      "name": "start",
      "timestamp": 595566001250
    },
    {
      "id": "588b415f3d064ba646378e7f",
      "name": "land",
      "timestamp": 595571510000
    }
  ]
}
  • id: ID of the scheduled workflow.
  • name: name of the scheduled workflow.
  • timestamp: schedule time since Epoch in milliseconds.
PUT /api/1/instances/(uuid: id)/configuration

Updates the instance configuration with the specified values.

Parameters:
  • id (uuid) – id of the instance to use
Status Codes:
  • 200 OK – success
  • 400 Bad Request – the content type is incorrect or the request body is not valid JSON
  • 401 Unauthorized – the specified credentials are not valid
  • 403 Forbidden – the user is not authorized to launch this workflow (destroy requires EditInstance permission) or the instance belongs to a submodule
  • 404 Not Found – the specified instance doesn’t exist

Request body: JSON-encoded configuration parameters for the root module and all its submodules, if necessary:

{
  "instanceName": "New Instance Name",
  "manifestVersion": 3,
  "revisionId" : "58d3ee503d06d6423ce3e534",
  "parameters": {
    "interface_name.param1": "Param 1 Value",
    "interface_name.param2": "Param 2 Value"
  },
  "submodules": {
    "intermediate_submodule": {
      "manifestVersion": 4,
      "submodules": {
        (submodule-id): {
          "manifestVersion": 2,
          "revisionId": "58f8ab1a7cea350dd8c16204",
          "parameters": {
            "submodule_interface_name.param3": "Param 3 Value",
            "submodule_interface_name.param4": "Param 4 Value"
          },
          "submodules": { ... } // This is a recursive section
        }
      }
    }
  }
}
  • instanceName (optional string): new instance name; if missing the instance name will not be changed.

    Note

    Only the root module’s instance name can be changed.

  • manifestVersion (optional int): new application manifest version for the instance; if missing the manifest version will not be changed.

  • revisionId (optional uuid): ID of the new revision to be applied to the instance; if missing the current revision will not be changed. If both manifestVersion and revisionId are specified then the value of manifestVersion supersedes the manifest version defined for the specified revision.

  • parameters (optional): new configuration parameters for the instance, where parameter names should consist of the application interface and pin names, separated by dots.

    Parameters with manifest default values are optional. Parameters without manifest default values are required.

    Note

    Those parameters which are not specified in the parameters section will be reset to their default values, defined in the target version of the application manifest. In particular, if the whole parameters section is missing in the request body, then all the parameters will be reset to their default values. Also if there are parameters which have no default values and some of them are missing in the parameters section, then the reconfiguration request will fail with the corresponding error.

  • submodules (optional): submodules configuration which have to be changed directly. The submodule-id is ID of a particular submodule as it defined in the application manifest. For each submodule the following configuration options are available: manifestVersion, revisionId, parameters and submodules, which have the same meanings as the corresponding configuration options for the root module.

    If both the root module’s revisionId and the submodule’s manifestVersion options are specified, then the submodule’s manifestVersion takes precedence over the manifest version of the submodule which is stored in the target root module’s revision.

    Note

    It is not allowed to reconfigure a submodule parameter directly, if it is mapped to some interface pin in the outer submodule. Reconfigure the mapped parameter in the outer submodule instead.

Response body:

{}

Note

The reconfiguration request doesn’t take effect immediately when it returns – it may require a bit more time to complete.

See also: How to reconfigure an application instance?