• Home
  • Dynatrace API
  • Environment
  • ActiveGates
  • ActiveGates auto-update jobs
  • POST an auto-update job

ActiveGate API - POST an auto-update job

Creates a new auto-update job on the specified ActiveGate.

The job updates the ActiveGate to the specified version. You can fetch the list of available versions with the GET available versions of ActiveGate call.

The request consumes and produces an application/json payload.

POSTManaged https://{your-domain}/e/{your-environment-id}/api/v2/activeGates/{agId}/updateJobs
SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/activeGates/{agId}/updateJobs
Environment ActiveGate https://{your-activegate-domain}/e/{your-environment-id}/api/v2/activeGates/{agId}/updateJobs

Authentication

To execute this request, you need an access token with Write ActiveGates (activeGates.write) scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

ParameterTypeDescriptionInRequired
agIdstring

The ID of the required ActiveGate.

pathrequired
bodyUpdateJob

JSON body of the request, containing update-job parameters.

bodyrequired

Request body objects

The UpdateJob object

Configuration of the ActiveGate update job.

ElementTypeDescription
jobIdstring

The ID of the update job.

Can be null.

jobStatestring

The status of the update job.

The element can hold these values
  • FAILED
  • IN_PROGRESS
  • PENDING
  • ROLLBACK
  • SCHEDULED
  • SKIPPED
  • SUCCEED

Can be null.

updateMethodstring

The method of updating the ActiveGate or its component.

The element can hold these values
  • AUTOMATIC
  • MANUAL_INSTALLATION
  • ON_DEMAND

Can be null.

updateTypestring

The component to be updated.

The element can hold these values
  • ACTIVE_GATE
  • REMOTE_PLUGIN_AGENT
  • SYNTHETIC
  • Z_REMOTE

Can be null.

agTypestring

The type of the ActiveGate.

The element can hold these values
  • CLUSTER
  • ENVIRONMENT
  • ENVIRONMENT_MULTI

Can be null.

startVersionstring

The initial version of the ActiveGate.

Can be null.

environmentsstring[]

A list of environments (specified by IDs) the ActiveGate can connect to.

Can be null.

cancelableboolean

The job can (true) or can't (false) be cancelled at the moment.

Can be null.

durationinteger

The duration of the update, in milliseconds.

Can be null.

timestampinteger

The timestamp of the update job completion.

The null value means the job is still running.

Can be null.

errorstring

The information about update error.

Can be null.

targetVersionstring

The target version of the update.

Specify the version in the <major>.<minor>.<revision>.<timestamp> format.

To update to the latest available version, use the latest value.

Request body JSON model

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.

json
{ "jobId": "-3524498778810258605", "jobState": "SUCCEED", "updateMethod": "AUTOMATIC", "updateType": "ACTIVE_GATE", "agType": "ENVIRONMENT", "startVersion": "1.185.0.20200201-120000", "environments": [ "string" ], "cancelable": false, "duration": 3608000, "timestamp": 1582031917814, "error": "string", "targetVersion": "1.190.0.20200301-130000" }

Response

Response codes

CodeTypeDescription
201UpdateJob

Success. The update-job have been created.

400ErrorEnvelope

Failed. The input is invalid.

Response body objects

The UpdateJob object

Configuration of the ActiveGate update job.

ElementTypeDescription
jobIdstring

The ID of the update job.

Can be null.

jobStatestring

The status of the update job.

The element can hold these values
  • FAILED
  • IN_PROGRESS
  • PENDING
  • ROLLBACK
  • SCHEDULED
  • SKIPPED
  • SUCCEED

Can be null.

updateMethodstring

The method of updating the ActiveGate or its component.

The element can hold these values
  • AUTOMATIC
  • MANUAL_INSTALLATION
  • ON_DEMAND

Can be null.

updateTypestring

The component to be updated.

The element can hold these values
  • ACTIVE_GATE
  • REMOTE_PLUGIN_AGENT
  • SYNTHETIC
  • Z_REMOTE

Can be null.

agTypestring

The type of the ActiveGate.

The element can hold these values
  • CLUSTER
  • ENVIRONMENT
  • ENVIRONMENT_MULTI

Can be null.

startVersionstring

The initial version of the ActiveGate.

Can be null.

environmentsstring[]

A list of environments (specified by IDs) the ActiveGate can connect to.

Can be null.

cancelableboolean

The job can (true) or can't (false) be cancelled at the moment.

Can be null.

durationinteger

The duration of the update, in milliseconds.

Can be null.

timestampinteger

The timestamp of the update job completion.

The null value means the job is still running.

Can be null.

errorstring

The information about update error.

Can be null.

targetVersionstring

The target version of the update.

Specify the version in the <major>.<minor>.<revision>.<timestamp> format.

To update to the latest available version, use the latest value.

Response body JSON model

json
{ "jobId": "-3524498778810258605", "jobState": "SUCCEED", "updateMethod": "AUTOMATIC", "updateType": "ACTIVE_GATE", "agType": "ENVIRONMENT", "startVersion": "1.185.0.20200201-120000", "environments": [ "string" ], "cancelable": false, "duration": 3608000, "timestamp": 1582031917814, "error": "string", "targetVersion": "1.190.0.20200301-130000" }

Validate payload

We recommend that you validate the payload before submitting it with an actual request. A response code of 204 indicates a valid payload.

The request consumes an application/json payload.

POSTManaged https://{your-domain}/e/{your-environment-id}/api/v2/activeGates/{agId}/updateJobs/validator
SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/activeGates/{agId}/updateJobs/validator
Environment ActiveGate https://{your-activegate-domain}/e/{your-environment-id}/api/v2/activeGates/{agId}/updateJobs/validator

Authentication

To execute this request, you need an access token with Write ActiveGates (activeGates.write) scope. To learn how to obtain and use it, see Tokens and authentication.

Response

Response codes

CodeTypeDescription
204-

Validated. The submitted update-job is valid. Response doesn't have a body.

400ErrorEnvelope

Failed. The input is invalid.

Example

In this example, the request creates an update job to update the ActiveGate with the ID of 1812885988 to the 1.198.0.20200630-163221 version.

The API token is passed in the Authorization header.

Curl

shell
curl -L -X POST 'https://mySampleEnv.live.dynatrace.com/api/v2/activeGates/1812885988/updateJobs' \ -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \ -H 'Content-Type: application/json' \ --data-raw '{ "targetVersion": "1.198.0.20200630-163221" }'

Request URL

plaintext
https://mySampleEnv.live.dynatrace.com/api/v2/activeGates/1812885988/updateJobs

Request body

json
{ "targetVersion": "1.198.0.20200630-163221" }

Response body

json
{ "jobId": "-7240069678607892845", "jobState": "PENDING", "updateMethod": null, "updateType": null, "cancelable": true, "startVersion": "1.195.5.20200522-174041", "targetVersion": "1.198.0.20200630-163221", "timestamp": null, "agType": "ENVIRONMENT", "environments": [ "mySampleEnv" ], "error": null, "duration": null }

Response code

201

Related topics
  • Dynatrace ActiveGate

    Understand the basic concepts related to ActiveGate.