Try it free

OneAgent remote configuration management API - POST a configuration job

  • Reference
  • Published Oct 06, 2022

The request consumes an application/json payload.

POSTManagedDynatrace for Governmenthttps://{your-domain}/e/{your-environment-id}/api/v2/oneagents/remoteConfigurationManagement
POSTEnvironment and Cluster ActiveGate (default port 9999)https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/oneagents/remoteConfigurationManagement

Authentication

Api-Token:

To execute this request, you need an access token with oneAgents.write scope.

One of the following permissions is required for personal access tokens:

  • environment:roles:viewer

To learn how to obtain and use it, see Personal access tokens.

Parameters

You identify your OneAgents by their IDs. Use the OneAgent on a host request to learn the IDs of OneAgents that you'd like to configure.

ParameterTypeDescriptionInRequired
restartboolean

One Agents will be restarted (true) or not (false) after configuration. By default OneAgents will be restarted when network zone, host group, host tags or host properties are reconfigured - the restart is required to apply the changes.

queryOptional
bodyRemoteConfigurationManagementOperationOneAgentRequest

JSON body of the request, containing remote configuration management job definition.

bodyRequired

Request body objects

The RemoteConfigurationManagementOperationOneAgentRequest object

Remote configuration management operation creation request.

ElementTypeDescriptionRequired
entitiesstring[]

A list of entities IDs for which remote configuration management is to be executed.

Required
operationsRemoteConfigurationManagementOperation[]

A list of remote configuration management operations to be executed.

Required

The RemoteConfigurationManagementOperation object

Definition of a single remote configuration management operation.

ElementTypeDescriptionRequired
attributestring

The attribute which is affected by the operation.

The element can hold these values
  • group
  • hostGroup
  • hostProperty
  • hostTag
  • networkZone
Required
operationstring

The operation performed on given attribute.

The element can hold these values
  • clear
  • set
Required
valuestring

The value which should be assigned to given attribute.

Optional

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.

{
  "entities": [
    "HOST-D454A967666E7970",
    "HOST-811760CFF2A5E872"
  ],
  "operations": [
    {
      "attribute": "networkZone",
      "operation": "set",
      "value": "exampleNetworkZoneName"
    }
  ]
}

Response

Response codes

CodeTypeDescription
201RemoteConfigurationManagementJob

Created

400RemoteConfigurationManagementValidationResult

Failed. The input is invalid.

409-

Other remote configuration management job is currently being executed

4XXErrorEnvelope

Client side error.

5XXErrorEnvelope

Server side error.

Response body objects

The RemoteConfigurationManagementJob object

Remote configuration management job.

ElementTypeDescription
endTimestring

Date (in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z') when the remote configuration management job was finished. This field is present only for finished jobs.

entityTypestring

Type of entities modified by remote configuration management.

The element can hold these values
  • ACTIVE_GATE
  • ONE_AGENT
failedEntitiesRemoteIdentityOperationFailedEntityDto[]

A list of failed remote configuration management jobs.

idstring

The ID of the remote configuration management job.

inProgressEntitiesstring[]

A list of in-progress remote configuration management jobs.

operationsRemoteConfigurationManagementOperation[]

A list of executed (successful and failed) remote configuration management jobs.

processedEntitiesCountinteger

Number of entities that were already processed at the time the response was created.

startTimestring

Date (in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z') when the remote configuration management job was started.

timeoutTimestring

Date (in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z') when the running remote configuration management job will time-out. This field is present only for running jobs.

totalEntitiesCountinteger

Total number of entities to process.

The RemoteIdentityOperationFailedEntityDto object

Failed remote configuration management information.

ElementTypeDescription
entityIdstring

Entity ID for which remote configuration management request was failed

failureMessagestring

Communication settings changing failure error description

failureReasonstring

Reason of communication settings changing failure.

The element can hold these values
  • CONNECTION_FAILURE
  • TIMEOUT

The RemoteConfigurationManagementOperation object

Definition of a single remote configuration management operation.

ElementTypeDescription
attributestring

The attribute which is affected by the operation.

The element can hold these values
  • group
  • hostGroup
  • hostProperty
  • hostTag
  • networkZone
operationstring

The operation performed on given attribute.

The element can hold these values
  • clear
  • set
valuestring

The value which should be assigned to given attribute.

The RemoteConfigurationManagementValidationResult object

The result of remote configuration management validation.

ElementTypeDescription
invalidEntitiesRemoteConfigurationManagementEntityValidationError[]

A list of validation errors for entities.

invalidOperationsRemoteConfigurationManagementOperationValidationError[]

A list of validation errors for operations.

The RemoteConfigurationManagementEntityValidationError object

Entity validation error for remote configuration management.

ElementTypeDescription
entitystring

The ID of the entity for which validation failed.

reasonsstring[]

The reason of entity validation failure.

The element can hold these values
  • CLOUD_NATIVE_NOT_SUPPORTED
  • NOT_ALLOWED_WITH_CLUSTER_ACTIVE_GATE
  • NOT_CONNECTED
  • RUNNING_IN_CONTAINER
  • STANDALONE_NOT_SUPPORTED
  • VERSION_NOT_SUPPORTED

The RemoteConfigurationManagementOperationValidationError object

Validation error of remote configuration management operation definition.

ElementTypeDescription
attributestring

The attribute which is affected by the operation.

The element can hold these values
  • group
  • hostGroup
  • hostProperty
  • hostTag
  • networkZone
operationstring

The operation performed on given attribute.

The element can hold these values
  • clear
  • set
reasonstring

The reason of validation failure.

valuestring

The value which should be assigned to given attribute.

Response body JSON models

{
  "endTime": "2020-11-05T08:15:30.144Z",
  "entityType": "ACTIVE_GATE or ONE_AGENT",
  "failedEntities": [
    {
      "entityId": "HOST-D454A967666E7970",
      "failureMessage": "Failed to access new tenant: f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "failureReason": "CONNECTION_FAILURE"
    }
  ],
  "id": "7974003406714390819",
  "inProgressEntities": [
    "HOST-D454A967666E7970"
  ],
  "operations": [
    {
      "attribute": "networkZone",
      "operation": "set",
      "value": "exampleNetworkZoneName"
    }
  ],
  "processedEntitiesCount": 1,
  "startTime": "2020-11-05T08:15:30.144Z",
  "timeoutTime": "2020-11-05T08:15:30.144Z",
  "totalEntitiesCount": 1
}
{
  "invalidEntities": [
    {
      "entity": "entityId",
      "reasons": [
        "RUNNING_IN_CONTAINER"
      ]
    }
  ],
  "invalidOperations": [
    {
      "attribute": "networkZone",
      "operation": "set",
      "reason": "Value must not start with a period",
      "value": ".exampleInvalidNetworkZoneName"
    }
  ]
}

The response is not sent to the client until all OneAgents defined in the payload are processed. A OneAgent is considered to be processed when the reconfiguration message is sent to it; the actual reconfiguration is handled independently by the OneAgent.

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.

POSTManagedDynatrace for Governmenthttps://{your-domain}/e/{your-environment-id}/api/v2/oneagents/remoteConfigurationManagement/validator
POSTEnvironment and Cluster ActiveGate (default port 9999)https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/oneagents/remoteConfigurationManagement/validator

Authentication

Api-Token:

To execute this request, you need an access token with oneAgents.write scope.

One of the following permissions is required for personal access tokens:

  • environment:roles:viewer
  • fleet-management:oneagents:write

To learn how to obtain and use it, see Personal access tokens.

Platform Token / OAuth:

Required scope: fleet-management:oneagents:write

To learn how to obtain and use it, see Platform tokens or OAuth clients.

Response

Response codes

CodeTypeDescription
204-

Success. Response doesn't have a body.

400RemoteConfigurationManagementValidationResult

Failed. The input is invalid.

4XXErrorEnvelope

Client side error.

5XXErrorEnvelope

Server side error.

Response body objects

The RemoteConfigurationManagementValidationResult object

The result of remote configuration management validation.

ElementTypeDescription
invalidEntitiesRemoteConfigurationManagementEntityValidationError[]

A list of validation errors for entities.

invalidOperationsRemoteConfigurationManagementOperationValidationError[]

A list of validation errors for operations.

The RemoteConfigurationManagementEntityValidationError object

Entity validation error for remote configuration management.

ElementTypeDescription
entitystring

The ID of the entity for which validation failed.

reasonsstring[]

The reason of entity validation failure.

The element can hold these values
  • CLOUD_NATIVE_NOT_SUPPORTED
  • NOT_ALLOWED_WITH_CLUSTER_ACTIVE_GATE
  • NOT_CONNECTED
  • RUNNING_IN_CONTAINER
  • STANDALONE_NOT_SUPPORTED
  • VERSION_NOT_SUPPORTED

The RemoteConfigurationManagementOperationValidationError object

Validation error of remote configuration management operation definition.

ElementTypeDescription
attributestring

The attribute which is affected by the operation.

The element can hold these values
  • group
  • hostGroup
  • hostProperty
  • hostTag
  • networkZone
operationstring

The operation performed on given attribute.

The element can hold these values
  • clear
  • set
reasonstring

The reason of validation failure.

valuestring

The value which should be assigned to given attribute.

Response body JSON models

{
  "invalidEntities": [
    {
      "entity": "entityId",
      "reasons": [
        "RUNNING_IN_CONTAINER"
      ]
    }
  ],
  "invalidOperations": [
    {
      "attribute": "networkZone",
      "operation": "set",
      "reason": "Value must not start with a period",
      "value": ".exampleInvalidNetworkZoneName"
    }
  ]
}