Dynatrace OneAgent to JSM Assets Integration Guide

This guide explains how to use OnLink to import Dynatrace OneAgent data into JSM Assets. It covers the Dynatrace OneAgent API connection, sample data, field mapping, validation, and optional query parameters.

Overview

OnLink can import Dynatrace OneAgent API responses into JSM Assets object types by using mapping statements such as key:, map:, and config:. The same approach can be used for Dynatrace OneAgent object types such as devices, users, circuits, and wireless data, provided the corresponding Dynatrace OneAgent API endpoint and Assets object type are configured.

The high-level process is:

Create or confirm the target JSM Assets schema and object type.
Configure an OnLink Assets Data Source that uses API token to connect to Dynatrace OneAgent.
Set the API method and Dynatrace OneAgent endpoint, then fetch sample data.
Map Dynatrace OneAgent JSON fields to JSM Assets attributes.
Use Get Data to validate the result, then run the import.

Prerequisites

A JSM Assets schema and object type for the data you want to import.
OnLink installed and available from Manage your apps.
A Dynatrace OneAgent API token with access to the required API endpoints.
Permission in JSM Assets to configure data sources, mappings, and imports.
The Dynatrace OneAgent API endpoint URL for the object type you plan to import.

1. Prepare Dynatrace OneAgent credentials

Before configuring OnLink, confirm that you have a Dynatrace API Token. For generating a API token and setting scope, see https://docs.dynatrace.com/docs/dynatrace-api/basics/dynatrace-api-authentication .

Dynatrace uses a unique token format consisting of three components separated by dots (.).

Token example

dt0s01.ST2EY72KQINMH574WMNVI7YN.G3DFPBEJYMODIDAEX454M7YWBUVEFOWKPRVMWFASS64NFH52PX6BNDVFFM572RZM

Token Scope

Read OneAgents

oneAgents.read

Grants access to GET requests of the OneAgents API.

Use the generated token in OnLink data source configuration.

2. Configure the OnLink data source

In OnLink, add an Assets Data Source.
Set Authentication Type to Bearer Token.
Set the token generated from Dynatrace.

3. Configure the API method

Use a GET request to retrieve records from the Dynatrace OneAgent API. For example, to fetch devices, configure the request as follows:

Set Method to GET.
Set URL to the Dynatrace OneAgent API endpoint. e.g https://{your-environment-id}.live.dynatrace.com/api/v1/oneagents. Place your environment id instead of the placee holder.
Set Response data path to hosts.
Leave other settings at their defaults unless the endpoint requires query parameters.

GET https://{your-environment-id}.live.dynatrace.com/api/v1/oneagents

4. Fetch sample data

Save the connection, then run it to fetch sample values from Dynatrace OneAgent. Use the returned sample JSON to confirm that the endpoint is correct and to identify the field names needed for mapping.

Sample response

{
  "hosts": [
    {
      "active": true,
      "autoUpdateSetting": "ENABLED",
      "availabilityState": "CRASHED",
      "availableVersions": [
        "string"
      ],
      "configuredMonitoringEnabled": true,
      "configuredMonitoringMode": "CLOUD_INFRASTRUCTURE",
      "currentActiveGateId": 1,
      "currentActiveGateIds": [
        "string"
      ],
      "currentNetworkZoneId": "string",
      "detailedAvailabilityState": "CRASHED_FAILURE",
      "faultyVersion": true,
      "hostInfo": {
        "agentVersion": {
          "major": 1,
          "minor": 1,
          "revision": 1,
          "sourceRevision": "string",
          "timestamp": "string"
        },
        "amiId": "string",
        "autoInjection": "DISABLED_MANUALLY",
        "autoScalingGroup": "string",
        "awsInstanceId": "string",
        "awsInstanceType": "string",
        "awsNameTag": "string",
        "awsSecurityGroup": [
          "string"
        ],
        "azureComputeModeName": "DEDICATED",
        "azureEnvironment": "string",
        "azureHostNames": [
          "string"
        ],
        "azureResourceGroupName": "string",
        "azureResourceId": "string",
        "azureSiteNames": [
          "string"
        ],
        "azureSku": "BASIC",
        "azureVmName": "string",
        "azureVmScaleSetName": "string",
        "azureVmSizeLabel": "string",
        "azureZone": "string",
        "beanstalkEnvironmentName": "string",
        "bitness": "32bit",
        "boshAvailabilityZone": "string",
        "boshDeploymentId": "string",
        "boshInstanceId": "string",
        "boshInstanceName": "string",
        "boshName": "string",
        "boshStemcellVersion": "string",
        "cloudPlatformVendorVersion": "string",
        "cloudType": "AZURE",
        "consumedHostUnits": "string",
        "cpuCores": 1,
        "customizedName": "string",
        "discoveredName": "string",
        "displayName": "string",
        "entityId": "string",
        "esxiHostName": "string",
        "firstSeenTimestamp": 1,
        "fromRelationships": {
          "isNetworkClientOfHost": [
            "string"
          ]
        },
        "gceInstanceId": "string",
        "gceInstanceName": "string",
        "gceMachineType": "string",
        "gceProject": "string",
        "gceProjectId": "string",
        "gcePublicIpAddresses": [
          "string"
        ],
        "gcpZone": "string",
        "hostGroup": {
          "meId": "string",
          "name": "string"
        },
        "hypervisorType": "AHV",
        "ipAddresses": [
          "string"
        ],
        "isMonitoringCandidate": true,
        "kubernetesCluster": "string",
        "kubernetesLabels": {},
        "kubernetesNode": "string",
        "lastSeenTimestamp": 1,
        "localHostName": "string",
        "localIp": "string",
        "logicalCpuCores": 1,
        "logicalCpus": 1,
        "managementZones": [
          {
            "description": "Dynatrace entity for the REST API example",
            "id": "6a98d7bc-abb9-44f8-ae6a-73e68e71812a",
            "name": "Dynatrace entity"
          }
        ],
        "monitoringMode": "FULL_STACK",
        "networkZoneId": "string",
        "oneAgentCustomHostName": "string",
        "openStackInstaceType": "string",
        "openstackAvZone": "string",
        "openstackComputeNodeName": "string",
        "openstackProjectName": "string",
        "openstackSecurityGroups": [
          "string"
        ],
        "openstackVmName": "string",
        "osArchitecture": "ARM",
        "osType": "AIX",
        "osVersion": "string",
        "paasAgentVersions": [
          {}
        ],
        "paasMemoryLimit": 1,
        "paasType": "AWS_ECS_EC2",
        "publicHostName": "string",
        "publicIp": "string",
        "scaleSetName": "string",
        "simultaneousMultithreading": 1,
        "softwareTechnologies": [
          {
            "edition": "string",
            "type": "string",
            "version": "string"
          }
        ],
        "tags": [
          {
            "context": "AWS",
            "key": "string",
            "value": "string"
          }
        ],
        "toRelationships": {
          "isNetworkClientOfHost": [
            "string"
          ],
          "isProcessOf": [
            "string"
          ],
          "isSiteOf": [
            "string"
          ],
          "runsOn": [
            "string"
          ]
        },
        "userLevel": "NON_SUPERUSER",
        "virtualCpus": 1,
        "vmwareName": "string",
        "zosCPUModelNumber": "string",
        "zosCPUSerialNumber": "string",
        "zosLpaName": "string",
        "zosSystemName": "string",
        "zosTotalGeneralPurposeProcessors": 1,
        "zosTotalPhysicalMemory": 1,
        "zosTotalZiipProcessors": 1,
        "zosVirtualization": "string"
      },
      "modules": [
        {
          "instances": [
            {
              "active": true,
              "faultyVersion": true,
              "instanceName": "string",
              "moduleVersion": "string"
            }
          ],
          "moduleType": "APACHE"
        }
      ],
      "monitoringType": "CLOUD_INFRASTRUCTURE",
      "plugins": [
        {
          "instances": [
            {
              "pluginVersion": "string",
              "state": "string"
            }
          ],
          "pluginName": "string"
        }
      ],
      "unlicensed": true,
      "updateStatus": "INCOMPATIBLE"
    }
  ],
  "nextPageKey": "string",
  "percentageOfEnvironmentSearched": 1
}

Pagination notes

Dynatrace OneAgent API responses may be paginated. Use the following configuration.

5. Configure the Assets import and mapping

After the connection is established, create the Assets import by following the JSM Assets Data Synchronization guide.

Use the fetched API sample to identify the JSON field names and map them to the corresponding JSM Assets attributes. The key: mapping should identify the stable unique value used to match and update existing Assets objects.

Mapping	Purpose

Mapping	Purpose
`key:entityId=Entity ID`	Uses the Dynatrace OneAgent `entityId` field as the unique key for matching and updating JSM Assets objects in the `Entity ID` attribute.
`map:displayName=Device Name`	Maps the Dynatrace OneAgent `displayName` field to `Device Name`.
`map:osType=OS Type`	Maps the Dynatrace OneAgent `osType` field to `OS Type`.
`map:osVersion=OS Version`	Maps the Dynatrace OneAgent `osVersion` field to `OS Version`.
`map:hypervisorType=Hypervisor Type`	Maps the Dynatrace OneAgent `hypervisorType` field to `Hypervisor Type`.

Mapping guidance

Start with one unique key: mapping so OnLink can identify whether to create or update an Assets object.
Add map: entries for each OneAgent field you want to store in Assets.
Compare the OneAgent sample JSON with the Assets object type attributes before running an import.
If a value is nested in the JSON response, inspect the sample output carefully and use the field path supported by the OnLink mapping configuration.

6. Validate and run the import

Use Get Data to preview the data returned by Device42.
Confirm that the sample records contain the expected fields and values.
Verify that the key field maps to a unique JSM Assets attribute.
Review object type mappings and attribute names for spelling and case consistency.
Run the import only after the previewed data and mapping are correct.

Optional filtering

Use OneAgent API query parameters to limit the records returned by the endpoint. For supported filters, see the API documentation: OneAgent API Reference.

Example: to return only hosts that are monitored, add this query parameter:

availabilityState=MONITORED