Integrating with Dynatrace via API

Supported version

BMC Helix Intelligent Integrations supports version 1.307 of Dynatrace for data collection.​​​​

Before you begin

Make sure you perform the following actions before you configure a connection with Dynatrace:

Dynatrace requirements

​​​​​To access the Dynatrace APIs required for data collection, generate an API token or create an OAuth client with the required scopes.

API token requirements

If you plan to use an API token, generate a token with the following scopes:

• API v2:
  • entities.read
  • events.read
  • extensions.read
  • logs.read
  • metrics.read
  • networkZones.read
  • problems.read
  • releases.read
  • securityProblems.read
  • settings.read
  • slo.read
• API v1:
  • DataExport

For more information about tokens, see Dynatrace API - Tokens and authentication in the Dynatrace documentation. 

OAuth client requirements

If you plan to use OAuth authentication, create the OAuth client with the following scopes in addition to the preceding API v2 scopes:

• account-env-read
• account-audit-logs-read
• storage:events:read
• storage:bizevents:read
• storage:user.events:read
• storage:security.events:read
• storage:entities:read
• storage:logs:read
• storage:metrics:read

For more information about creating OAuth clients and assigning scopes, see OAuth clients in the Dynatrace documentation.

BMC Helix Intelligent Integrations requirements

• Depending on your requirements, choose the BMC Helix Intelligent Integrations deployment modes and review the corresponding port requirements. For information about various deployment modes and port requirements, see Deployment scenarios.
• Based on the deployment mode, use the BMC Helix Intelligent Integrations SaaS deployment or deploy the BMC Helix Intelligent Integrations on-premises gateway. For more information about the gateway, see Deploying the BMC Helix Intelligent Integrations on-premises gateway.
• Make sure that the on-premises gateway is able to reach the third-party product on the required port (default value is 443).
• In the pattern configuration for Dynatrace, set the create_nodes variable to true (default is false). 
  For information about setting the variable, see Configuring patterns in the UI. 

Task 1: To configure the connection with Dynatrace

1. To access BMC Helix Intelligent Integrations, perform one of the following steps depending on your deployment mode:

   • BMC Helix Intelligent Integrations SaaS—Log on to BMC Helix Portal, and click the BMC Helix Intelligent Integrations tile.
   • BMC Helix Intelligent Integrations on-premises gateway—Use the following URL to access BMC Helix
     Intelligent Integrations: https://hostName:portNumber/swpui
2. On the CONNECTORS  tab, click  in the SOURCES panel.

3. Click the Dynatrace Managed/SaaS tile. 

4. Specify the following details for the source connection:

   1. Specify a unique instance name.

      Success

      Best practice
      We recommend that you specify the instance name in the following format: 

      <sourceType>_<sourceControllerServerName>{_<InstanceQualifier>}                    

      The instance qualifier helps you to distinguish the multiple instances configured from the same source server. For example, you can name your instances as Dynatrace_Host_PROD, Dynatrace_Host_TEST, and so on.

   2. Specify the Dynatrace host name.
   3. Specify the Dynatrace HTTP or HTTPS port number, depending on the connection protocol (the default port number is 443).
   4. Select the HTTPS option to use an HTTPS connection to the Dynatrace host.
      Error

      Caution

      Do not select the Allow Unsigned Certificate option in a production environment. You can select this option to allow unsigned certificates in a test environment. To learn how to install SSL certificates, see the Dynatrace  documentation.

   5. Specify the number of maximum concurrent REST API requests that should be executed during a collection schedule (default value is 5).
   6. Specify the time, in seconds, after which no attempt should be made to establish a connection (default value is 30).
   7. Specify one of the following authentication methods​​​​​:
      • API token—Specify a valid token to access the API. Make sure that the token is created with the required scopes. For more information about obtaining token, see Dynatrace API - Tokens and authentication​​​​​​ in the Dynatrace documentation. 
      • OAuth—Select the Use OAuth option and specify the Dynatrace account URN, client ID, and client secret. Make sure that the client ID or client name is registered as an OAuth client in Dynatrace. For more information about obtaining these details, see OAuth clients  in the Dynatrace documentation. 
   8. (On-premises only) The Environment ID is similar to the Account ID. Leave this field blank for SaaS deployments.
   9. Click Proxy and specify whether you want to configure a proxy server. If yes, specify the host name and port number (default value is 8888).
5. Click VALIDATE AND CREATE.
   The specified connection details are validated, and the corresponding source connection is created in the Source Connection list.

6. Select the source connection that you created from the list if it is not selected already.

   Warning

   Important

   The destination host connection is created and configured automatically when the source connection is created.

7. Make sure that you select the options for the required data types to collect data.

8. Configure the collectors for the selected data types by clicking the respective data type in the Collectors section. 

   Warning

   Important

   Depending on the Dynatrace API version you want to use for metrics collection and the type of metrics you want to collect, select one of the following options:

   • Dynatrace Managed Metrics: Depending on your selections in metric lists, such as metric categories, applications, and application tags, the Dynatrace Timeseries API v1 or Metrics API v2 is used to collect metrics, and the corresponding metrics are collected.
   • Dynatrace Managed V2 Metrics (Recommended): The Dyantrace Metrics API v2 is used to collect v2 metrics.

   Click here to view the collection parameters for the selected data types

   Important: The ✅️  symbol indicates that this field is applicable to the data type.

   Parameter name	Description	Data type
   		Dynatrace Managed Alerts	Dynatrace Managed Metrics	Dynatrace Managed V2 Metrics	Dynatrace Managed Tolology
   Collection Schedule	Specify the data collection frequency by using one of the following methods: Constantly, by specifying the schedule in minutes, hours, or days using the Duration option Default: 5 minutes Example: Collection Schedule is set to 5 mins. Current time is 00:30. If you run the collector just after 00:30, data is collected every 5 mins, first at 00:30 and next at 00:35, and so on.   Periodically, by specifying the schedule through a cron expression using the Cron schedule option  A cron expression is a string consisting of five subexpressions (fields) that describe individual details of the schedule.  These fields, separated by blank spaces, can contain any of the allowed values with various combinations of the allowed characters for that field. Default: */5 * * * * (evaluates to 5 minutes) Format: Minutes Hours (24-hour format) Day of Month Month Day of Week Example: If you specify 10 15 3 7 * , data is collected at 15:10 hours every third day in the month of July. For more information about how this parameter affects data collection,  see Data collection schedule.	✅️	✅️	✅️	✅️
   Data Collection Window	Specify the historical time period (in minutes) from the current time for which the data should be collected from Dynatrace.  Default: 5 minutes Example: Collection Schedule is set to 5 mins. Data Collection Window is set to 5 mins. Current time is 00:30. If you run the collector just after 00:30, data is collected first at 00:30 for the interval, 00:25 - 00:30, and next at 00:35 for the interval, 00:30 - 00:35, and so on. For more information about this parameter, see Data collection window.	✅️	✅️	✅️	✅️
   Data Latency	Specify the time (in minutes) by which the data time window should be shifted back on the timeline.  This parameter is useful in delayed data availability situations. Default: 60 minutes Example: Collection Schedule is set to 5 mins.  Data Collection Window is set to 10 mins. Data Latency is set to 2 mins.  Current time is 00:30. If you run the collector just after 00:30, data is collected first at 00:30 for the interval, 00:18 - 00:28, and next at 00:35 for the interval, 00:23 - 00:33, and so on. For more information about this parameter, see Data latency.	✅️	✅️	✅️	✅️
   Impacts	Select one or more alert impact statuses from the list.	✅️	❌️	❌️	❌️
   Severities	Select one or more alert severities from the list.	✅️	❌️	❌️	❌️
   Statuses	Select the alert status from the list.	✅️	❌️	❌️	❌️
   Metric Categories (Applicable only for API v1)	Select all or a subset of metric categories from the list. This list is updated automatically from Dynatrace.	❌️	✅️	❌️	❌️
   Application Tags and Applications	Depending on your selections in the Metric Categories and V2 Metrics lists, collect metrics for applications with specific tags or for all applications.​​ If you have selected any categories from the Metric Categories list, metrics are collected only for those categories. If you have selected any metrics from the V2 Metrics list, only those metrics are collected. If you have selected options from both lists, the selected metric categories are ignored.   The Application Tags and Applications lists are updated automatically from Dynatrace. To collect metrics for the applications with tags, perform the following steps: Select tags from the Application Tags list. Important: Tags are meant only for restricting the number of applications to be displayed in the Applications list. Metrics are collected based on the applications you select in the Applications list. Remove the All Applications option from the Application Tags list. The Applications list is populated with the applications that have the selected tags. Do one of the following: Select the applications one by one for which you want to collect metrics. Select the Select All option to display the applications having the selected tags and then, remove All Applications from the list. Otherwise, the metrics for all the applications are collected. Important: If you select All Applications, the tags you have selected from the Application Tags list are not considered and metrics for all the applications are collected. To collect metrics for all applications​​​​, perform the following steps: Make sure that All Applications is selected in the Application Tags list. Make sure that All Applications is selected in the Applications list.	❌️	✅️	❌️	❌️
   Service Tags and Services	Depending on your selections in the Metric Categories and V2 Metrics lists, collect metrics for services with specific tags or for all services​​.​​ If you have selected any categories from the Metric Categories list, metrics are collected only for those categories. If you have selected any metrics from the V2 Metrics list, only those metrics are collected. If you have selected options from both lists, the selected metric categories are ignored. The Service Tags and Services lists are updated automatically from Dynatrace. To collect metrics for the services with tags, perform the following steps: Select tags from the Service Tags list. Note: Tags are meant only for restricting the number of services to be displayed in the Services list. Metrics are collected based on the services you select in the Services list. Remove the All Services option from the Service Tags list. The Services list is populated with the services that have the selected tags. Do one of the following: Select the services one by one for which you want to collect metrics. Select the Select All option to display services with the selected tags and then, remove All Services from the list. Otherwise, the metrics for all the services are collected. Important: If you select All Services, the tags you have selected from the Service Tags list are not considered and metrics for all the services are collected. To collect metrics for all services, perform the following steps: Make sure that All Services is selected in the Service Tags list. Make sure that All Services is selected in the Services list.	❌️	✅️	❌️	❌️
   Host Tags and Hosts	Depending on your selections in the Metric Categories and V2 Metrics lists, collect metrics for hosts with specific tags or for all hosts. If you have selected any categories from the Metric Categories list, metrics are collected only for those categories. If you have selected any metrics from the V2 Metrics list, only those metrics are collected. If you have selected options from both lists, the selected metric categories are ignored. The Host Tags and Hosts lists are updated automatically from Dynatrace. To collect metrics for the hosts with tags, perform the following steps: Select tags from the Host Tags list. Note: Tags are meant only for restricting the number of hosts to be displayed in the Hosts list. Metrics are collected based on the hosts you select in the Hosts list. Remove the All Hosts option from the Host Tags list. The Host list is populated with the hosts that have the selected tags. Do one of the following: Select the hosts one by one for which you want to collect metrics. Select the Select All option to display hosts with the selected tags and then, remove All Hosts from the list. Otherwise, the metrics for all the hosts are collected. Important: If you select All Hosts , the tags you have selected from the Host Tags list are not considered and metrics for all the hosts are collected. To collect metrics for all hosts, perform the following steps: Make sure that All Hosts is selected in the Host Tags list. Make sure that All Hosts is selected in the Hosts list.	❌️	✅️	❌️	❌️
   Process Tags and Processes	Depending on your selections in the Metric Categories and V2 Metrics lists, collect metrics for processes with specific tags or for all processes​​.​​ If you have selected any categories from the Metric Categories list, metrics are collected only for those categories. If you have selected any metrics from the V2 Metrics list, only those metrics are collected. If you have selected options from both lists, the selected metric categories are ignored. The Process Tags and Processes lists are updated automatically from Dynatrace. To collect metrics for the processes with tags, perform the following steps: Select tags from the Process Tags list. Note: Tags are meant only for restricting the number of processes to be displayed in the Processes list. Metrics are collected based on the processes you select in the Processes list. Remove the All Processes option from the Process  Tags list. The Processes list is populated with the processes that have the selected tags. Do one of the following: Select the processes one by one for which you want to collect metrics. Select the Select All option to display processes with the selected tags and then, remove All Processes from the list. Otherwise, the metrics for all the processes are collected. Important: If you select All Processes , the tags you have selected from the Process Tags list are not considered and metrics for all the processes are collected. To collect metrics for all processes, perform the following steps: Make sure that All Processes is selected in the Process Tags list. Make sure that All Processes is selected in the Processes list.	❌️	✅️	❌️	❌️
   Process Group Tags and Process Groups	Depending on your selections in the Metric Categories and V2 Metrics lists, collect metrics for process groups with specific tags or for all process groups​.​​​​​​​ If you have selected any categories from the Metric Categories list, metrics are collected only for those categories. If you have selected any metrics from the V2 Metrics list, only those metrics are collected. If you have selected options from both lists, the selected metric categories are ignored. The Process Group Tags and Process Groups lists are updated automatically from Dynatrace. To collect metrics for the process groups with tags, perform the following steps: Select tags from the Process Group Tags list. Important: Tags are meant only for restricting the number of process groups to be displayed in the Process Groups list. Metrics are collected based on the process groups you select in the Process Groups list. Remove the All Process Groups option from the Process Group Tags list. The Process Groups list is populated with the process groups that have the selected tags. Do one of the following: Select the process groups one by one for which you want to collect metrics. Select the Select All option to display process groups with the selected tags and then, remove All Process Groups from the list. Otherwise, the metrics for all the process groups are collected. Important: If you select All Process Groups , the tags you have selected from the Process Group Tags list are not considered, and metrics for all the process groups are collected. To collect metrics for all process groups, perform the following steps: Make sure that All Process Groups is selected in the Process Group Tags list. Make sure that All Process Groups is selected in the Process Groups list.	❌️	✅️	❌️	❌️
   V2 Metrics (Applicable only for API v2)	Select all or a subset of v2 metrics from the list. If you don't select any metrics, data for all the v2 metrics is collected. This list is updated automatically from Dynatrace .	❌️	✅️	✅️	❌️
   Entity Types	Select all entity types or a subset from the following list: APPLICATION HOST PROCESS_GROUP PROCESS_GROUP_INSTANCE SERVICE SERVICE_METHOD SERVICE_METHOD_GROUP	❌️	❌️	✅️	✅️
   Management Zone Regex	Specify the regex for the management zones. Data is collected only for entities that belong to zones whose names match the specified regex. By default, data for all entities is collected if you leave the text box empty. Examples: To collect metrics only for entities that belong to a management zone, specify .*.  To collect metrics for entities that belong to the management zones whose names contain the strings Prod and QA, specify the regex as (?=.*Prod)(?=.*QA).*.  To collect metrics for entities that belong to the management zones whose names start with the string Prod, specify the regex as ^Prod.*. Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter .*Prod.* and ^(?!.*Prod).* together. The former regex collects metrics for entities that belong to management zones whose names contain the string Prod, while the latter regex collects metrics for entities that belong to management zones whose names do not contain the string Prod.	✅️	❌️	✅️	✅️
   Entity Tag Regex and Entity Name Regex	Use these parameters to collect metrics for the entities with specific tags or all entities (default). Specify the regex for the entity tags and entities. Perform the following steps to collect metrics for the entities with tags:​​​​​ Specify the regex for entity tags.  Important: Tags are meant only for restricting the number of entities to be evaluated for the Entity Regex text box. Metrics are collected based on the regex you specify in the Entity Regex list. Specify the regex for entities.​​​​​​	❌️	❌️	✅️	❌️

9. To create the required collector streams for the selected data types, click CREATE COLLECTORS.

10. Configure the distributors for the selected data types by clicking the respective data type in the Distributors section.

    Click here to view the distribution parameters for the selected data types

    Parameter name	Description	Dynatrace Managed Alerts	Dynatrace Managed Metrics	Dynatrace Managed V2 Metrics	Dynatrace Managed Topology
    Max Batching Size	Specify the maximum number of data items to send in a single POST request to the destination API. The batch size depends on the destination’s ability to buffer the incoming data. Default: 250	✅️	✅️	✅️	✅️
    Max Batching Delay	Specify the maximum time (in seconds) to wait before building and processing a batch. Default: 3 seconds	✅️	✅️	✅️	✅️
    Base Retry Delay	Specify the initial time (in seconds) for which to wait before retrying to build and process a batch. The waiting time increases in the following sequence: n1, n2, n3, and so on, where n indicates the number of seconds. Default: 2 seconds Example: Base Retry Delay is set to 2 seconds. Retry is performed after 2, 4, 8, 16, ... seconds.	✅️	✅️	✅️	✅️
    Max Intra-Retry Delay	Specify the maximum limit for the base retry delay.  Default: 60 seconds Example: Max Intra-Retry Delay is set to 60 seconds. Base Retry Delay is set to 2 seconds. Retries are performed 2, 4, 8, 16, 32,... seconds later.	✅️	✅️	✅️	✅️
    Max Retry Duration	Specify the total time for retrying a delivery. For REST destinations, a delivery is a batch of data items in one POST request.  Default: 5 minutes Example: Max Retry Duration is set to 8 hours. Base Retry Delay is set to 2 seconds. Requests are sent for 2+4+8+16+32+64+132... until 8 hours in total duration is reached. After that, no subsequent attempts are made to retry the delivery. The assumption here is that if there is an outage or other issue with the destination tool, recovery should take less than the value of the Max Retry Duration parameter to be completed.	✅️	✅️	✅️	✅️
    Attributes To Be Dropped When Updating Events	Specify the event attributes that you do not want to be updated in BMC Helix Operations Managementwhen events are updated.  For example, if you do not want an event's severity, source address, source category, and subcategory to be updated in BMC Helix Operations Management, you need to specify those attributes in a comma-separated format: severity,source_address,source_category,source_subcategory . Important: You can obtain the event attribute names in BMC Helix Operations Management, by exporting any event data in JSON, BAROC, XML, or CSV format . The exported file contains all attributes of the event data, and from there you can identify the attributes to be dropped.	✅️	✅️	✅️	✅️
    Device Filters and Metrics filtersDevice and Metrics filters help remove unwanted data and send only the required data to BMC Helix applications. The data is filtered by using the regular expression (regex) provided for device name, monitor name, monitor type, and metrics, and is sent to BMC Helix applications.
    Device Name Regex	Specify the regex for the device name. Metrics for devices whose names match the regex are sent to BMC Helix applications. Examples: To send data for the devices that contain the string Linux in their names, specify the regex as .*Linux.*. To send data for the devices that contain the string Cisco and Linux, specify the regex as (?=.*Cisco)(?=.*Linux).*. To send the data for the devices whose names start with the string Linux, specify the regex as ^Linux.*.  Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter .*Linux.* and ^(?!.*Linux).* together. The former regex sends metrics for the devices whose names contain the string Linux, while the latter regex sends metrics for the devices whose names do not contain the string Linux.	❌️	✅️	✅️	❌️
    Monitor Name Regex	Specify the regex for the monitor name. Metrics for the monitors whose names match the regex are sent to BMC Helix applications. Examples: To send data for the monitors that contain the string system in their names, specify the regex as .*system.*. To filter out the data for monitors that contain system in their name, specify the regex as ^(?!.*system).*. To send the data for monitors whose names start with the string system, specify the regex as ^system.*. Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter .*system.* and ^(?!.*system).* together. The former regex sends metrics for the monitors whose names contain the string system, while the latter regex sends metrics for the monitors whose names do not contain the string system.	❌️	✅️	✅️	❌️
    Monitor Type Regex	Specify the regex for the monitor type. Metrics are sent to BMC Helix applications for the monitor type that matches the regex. Examples: To send data for the monitor type that contains the string health, specify the regex as .*health.*. To send data for the monitor type that starts with the string health, specify the regex as ^health.*. To filter out the monitor type that contains the string health, specify the regex as ^(?!.*health).*. Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter, ^health.* and ^(?!.*health).* together. The former regex collects metrics for the monitor type whose names contain the string health, while the latter regex collects data for the monitor types whose names do not contain the string health.	❌️	✅️	✅️	❌️
    Metrics Regex	Specify the regex for the metrics. Metrics are sent to BMC Helix applications whose names match the regex. Examples: To send metrics that contain the string avg in their names, specify the regex as .*avg.*. To filter out the metrics that contain the string avg, specify the regex as ^(?!.*avg).*. To send metrics whose names start with the string avg, specify the regex as ^avg.*. Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter, .*avg.* and ^(?!.*avg).* together. The former regex sends metrics whose name contains the string avg, while the latter regex sends metrics whose name does not contain the string avg.	❌️	✅️	✅️	❌️
    Events FiltersEvents filters help remove unwanted data and send only the required events to BMC Helix applications. The data is filtered by using the regular expression (regex) provided for host, message, and detailed message and is sent to BMC Helix applications.
    Host Regex	Specify the regex for the host name. Events for the hosts whose names match the regex are sent to BMC Helix applications. Examples: To send data for the host name /inventory/pricing, specify the regex as ^/inventory/pricing$. To filter out data whose host name contains the string inventory, specify the regex as ^(?!.*inventory).*. To send the data for the host whose names start with the string inventory, specify the regex as ^inventory.*.  Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter .*(inventory).* and ^(?!.*inventory).* together. The former regex sends events for the hosts whose names contain the string inventory, while the latter regex sends events for the hosts whose names do not contain the string inventory.	✅️	❌️	❌️	❌️
    Message Regex	Specify the regex for the event message. Messages for the events that match the regex are sent to BMC Helix applications. Examples: To send events whose messages contain the string HRV alert, specify the regex as .*HRV alert*. To filter out the events whose message contains the string HRV alert, specify the regex as ^(?!.*HRV alert).*. To send events whose message starts with the string HRV alert, specify the regex as ^(HRV alert).*.  Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter .*HRV alert.* and ^(?!.*HRV alert).* together. The former regex sends events whose message contains the string HRV alert, while the latter regex sends events whose message do not contain the string HRV alert.	✅️	❌️	❌️	❌️
    Detailed Message Regex	Specify the regex for the detailed message. Detailed messages for the events that match the regex are sent to BMC Helix applications. Examples:​​ To send events whose detailed message contains the string ci_display_name: easyTravel-k8s, specify the regex as .*ci_display_name: easyTravel-k8s.*. To filter out the events whose detailed message contains the string ci_display_name: easyTravel-k8s, specify the regex as ^(?!.*ci_display_name: easyTravel-k8s).*. To send the events whose detailed message starts with the string ci_display_name: easyTravel-k8s, specify the regex as ^(ci_display_name: easyTravel-k8s).*. Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter .*ci_display_name: easyTravel-k8s.* and ^(?!.*ci_display_name: easyTravel-k8s).* together. The former regex sends events whose detailed message contains the string ci_display_name: easyTravel-k8s, while the latter regex sends events whose message do not contain the string ci_display_name: easyTravel-k8s.	✅️	❌️	❌️	❌️

11. Click CREATE DISTRIBUTORS to create the required distributor streams for the selected data types.
12. Click VALIDATE AND CREATE and then click SAVE STREAM to save the stream.
    After you save the stream, the connection that you just created is listed on the SOURCES panel.
13. (Optional, applicable for 26.1.01 and later versions) Perform the following steps if you want to collect and view the Dynatrace metrics data in a hierarchical manner. Otherwise, skip to step 14.
    With the custom JSLT, each host is represented as a device in BMC Helix Operations Management, and process group instances are represented as monitors, with related metrics organized hierarchically beneath them. 
    1. On the SOURCES panel, click Configure Mediator for the source connection that you created and then expand DYNATRACE METRICS and navigate to the DISTRIBUTOR CONFIGURATION tab.
    2. To view JSON in edit mode, click Edit JSON.

    3. Search for the following line:

        "jsltField": "//NO JSLT",

    4. Delete the existing value from the jsltField field; the result should look as follows:

       "jsltField": "",
    5. To disable the edit mode for JSON, click Edit JSON.

    6. In the JSLT field, enter the following JSLT:

       Click here to see the JSLT

       // ===========================
       // Dynatrace -> BHOM hierarchy
       // ===========================
       //
       // Enforced hierarchy (non-HOST):
       //  L2  Process Groups                         (Dynatrace_Process_Group_Instances) <-- container (NO ID SUFFIX)
       //  L3  <Process Group Instance>               (Dynatrace_Process_Group_Instance)   <-- unique (ID suffix ok)
       //  L4  Services                               (Dynatrace_Services)                <-- container (NO ID SUFFIX)
       //  L5  <Actual Service>                       (Dynatrace_Service)                 <-- unique (ID suffix ok)
       //  L6  Service Method Groups                  (Dynatrace_Service_Method_Groups)   <-- container (NO ID SUFFIX)
       //  L7  <Service Method Group>                 (Dynatrace_Service_Method_Group)    <-- unique (ID suffix ok)
       //  L8  Service Methods                        (Dynatrace_Service_Methods)         <-- container (NO ID SUFFIX)
       //  L9  <Service Method> (treated as SMGI)     (Dynatrace_Service_Method)          <-- unique (ID suffix ok)
       //
       // HOST payload is emitted ONLY when CI_Type == HOST.
       // ParentEntityName/ParentEntityTypeId always match the immediate previous emitted level.
       //
       // BHOM NOTE:
       // Some BHOM UIs require parent linkage keys at TOP LEVEL of labels (not only in labels.extras).
       // So we emit parentEntityName/parentEntityTypeId/instanceName both places.
       
       let productName = "Dynatrace"
       
       // ---------------- helpers ----------------
       def isBlank(x)
         if ($x == null) true else (if ($x == "") true else false)
       
       def coalesce(a, b)
         if (isBlank($a)) $b else $a
       
       // sanitize but keep it safe: never return blank
       // - replaces problematic chars incl whitespace with "_"
       // - trims leading/trailing underscores
       def sanitize(x)
         if (isBlank($x)) ""
         else
           let y = replace($x, "[/=+?:;|\\s()@\\$&\\^%!#\\*\\[\\]]+", "_")
           replace($y, "^_+|_+$", "")
       
       def nonBlankSanitized(x, fb)
         let sx = sanitize($x)
         if (isBlank($sx)) sanitize($fb) else $sx
       
       def metricToBmcMetricName(m)
         nonBlankSanitized($m.name, "UNKNOWN_METRIC")
       
       def dropNulls(arr)
         [ for ($arr) . if (. != null) ]
       
       def startsWithAny(s, a, b)
         (not(isBlank($s)) and (starts-with($s, $a) or starts-with($s, $b)))
       
       def isContainerLevel(k)
         ($k == 2 or $k == 4 or $k == 6 or $k == 8)
       
       // ---------------- hostname ----------------
       def hostName(m)
         if (not(isBlank($m.extras.parent_host_display_name)))
           $m.extras.parent_host_display_name
         else if ($m.extras.CI_Type == "HOST" and not(isBlank($m.extras.discoveredName)))
           $m.extras.discoveredName
         else if (not(isBlank($m.extras.parent_host_detected_name)))
           $m.extras.parent_host_detected_name
         else if (($m.extras.CI_Type == "APPLICATION" or $m.extras.CI_Type == "PROCESS_GROUP") and not(isBlank($m.extras.displayName)))
           $m.extras.displayName
         else
           "DYNATRACE_HOST"
       
       // ---------------- measurementGroup logic ----------------
       def mgSize(m)
         if (is-array($m.measurementGroup)) size($m.measurementGroup) else 0
       
       def arrayHas(arr, v)
         (size([ for ($arr) . if (. == $v) ]) > 0)
       
       def metricIdLeafName(m)
         let mid = coalesce($m.extras.metricId, "UNKNOWN")
         let parts = split($mid, ":")
         let lastIndex = size($parts) - 1
         let lastColon = $parts[$lastIndex]
         let dots = split($lastColon, "\\.")
         let dotIndex = size($dots) - 1
         nonBlankSanitized($dots[$dotIndex], "UNKNOWN_METRIC_ID_LEAF")
       
       def mgLast(m)
         $m.measurementGroup[mgSize($m) - 1]
       
       // Human-friendly base “instance” (used when you want instance-oriented leaf names)
       def mgEntityInstanceName(m)
         let mg = $m.measurementGroup
         if (mgSize($m) >= 3)
           if (arrayHas($m.measurementGroup, "host")
               and arrayHas($m.measurementGroup, "disk")
               and mgSize($m) >= 4
               and contains(mgLast($m), "/"))
             "disk " + coalesce(mgLast($m), "UNKNOWN_DISK")
           else
             coalesce($mg[2], "UNKNOWN_INSTANCE")
         else if (mgSize($m) == 2)
           metricIdLeafName($m)
         else
           "DYNATRACE"
       
       // ---------------- HOST entityName/entityTypeId ----------------
       def hostEntityName(m)
         let mg = $m.measurementGroup
       
         if (mgSize($m) >= 3)
           if (arrayHas($m.measurementGroup, "host")
               and arrayHas($m.measurementGroup, "disk")
               and mgSize($m) >= 4
               and contains(mgLast($m), "/"))
             "disk " + coalesce(mgLast($m), "UNKNOWN_DISK")
           else
             coalesce($mg[2], "UNKNOWN_HOST_ENTITY")
         else if (mgSize($m) == 2)
           metricIdLeafName($m)
         else
           "DYNATRACE"
       
       def hostEntityTypeId(m)
         let mg = $m.measurementGroup
       
         if (mgSize($m) >= 3)
           nonBlankSanitized(join([ for ($mg[1 : mgSize($m) - 1]) . ], "_"), "UNKNOWN_HOST_TYPE")
         else if (mgSize($m) == 2)
           nonBlankSanitized($mg[1], "UNKNOWN_HOST_TYPE")
         else
           "UNKNOWN_HOST_TYPE"
       
       // ---------------- safer name resolvers ----------------
       def processGroupInstanceName(m)
         let n =
           if ($m.extras.CI_Type == "PROCESS_GROUP_INSTANCE")
             coalesce($m.extras.displayName, $m.extras.detectedName)
           else
             coalesce($m.extras.parent_process_group_instance_display_name,
                      $m.extras.parent_process_group_instance_detected_name)
       
         if (isBlank($n))
           coalesce($m.extras.displayName,
                    coalesce($m.extras.detectedName, "UNKNOWN_PGI"))
         else
           $n
       
       // SERVICE name (L5)
       def serviceName(m)
         if (startsWithAny($m.extras.entityId, "SERVICE_METHOD_GROUP-", "SERVICE_METHOD-"))
           coalesce(
             coalesce($m.extras.parent_service_display_name, $m.extras.parent_service_detected_name),
             "UNKNOWN_SERVICE"
           )
         else
           coalesce(
             coalesce($m.extras.displayName, $m.extras.detectedName),
             "UNKNOWN_SERVICE"
           )
       
       // L7 Service Method Group
       def methodGroupName(m)
         coalesce(
           coalesce(
             coalesce($m.extras.parent_service_method_group_display_name,
                      $m.extras.parent_service_method_group_detected_name),
             coalesce($m.extras.service_method_group_detected_name,
                      coalesce($m.extras.displayName, $m.extras.detectedName))
           ),
           "UNKNOWN_SERVICE_METHOD_GROUP"
         )
       
       // L9 Service Method (treated as SMGI)
       def methodGroupInstanceName(m)
         if (not(isBlank($m.extras.entityId)) and starts-with($m.extras.entityId, "SERVICE_METHOD-"))
           coalesce(
             coalesce($m.extras.service_method_detected_name,
                      coalesce($m.extras.CI, coalesce($m.extras.displayName, $m.extras.detectedName))),
             "UNKNOWN_SERVICE_METHOD"
           )
         else
           coalesce(
             coalesce($m.extras.displayName, $m.extras.detectedName),
             "UNKNOWN_SERVICE_METHOD"
           )
       
       // ---------------- entity type by hierarchy level ----------------
       def hierarchyEntityTypeId(m, k)
         if ($k == 2) "Dynatrace_Process_Group_Instances"
         else if ($k == 3) "Dynatrace_Process_Group_Instance"
         else if ($k == 4) "Dynatrace_Services"
         else if ($k == 5) "Dynatrace_Service"
         else if ($k == 6) "Dynatrace_Service_Method_Groups"
         else if ($k == 7) "Dynatrace_Service_Method_Group"
         else if ($k == 8) "Dynatrace_Service_Methods"
         else if ($k == 9) "Dynatrace_Service_Method"
         else "UNKNOWN_ENTITY_TYPE"
       
       // ---------------- entity name by hierarchy level ----------------
       def hierarchyEntityNameByIdx(m, k)
         if ($k == 2) "Process_Group_Instances"
         else if ($k == 3) nonBlankSanitized(processGroupInstanceName($m), "UNKNOWN_PGI")
         else if ($k == 4) "Services"
         else if ($k == 5) nonBlankSanitized(serviceName($m), "UNKNOWN_SERVICE")
         else if ($k == 6) "Service_Method_Groups"
         else if ($k == 7) nonBlankSanitized(methodGroupName($m), "UNKNOWN_SERVICE_METHOD_GROUP")
         else if ($k == 8) "Service_Methods"
         else if ($k == 9) nonBlankSanitized(methodGroupInstanceName($m), "UNKNOWN_SERVICE_METHOD")
         else "UNKNOWN_ENTITY"
       
       // ---------------- instanceName per hierarchy level ----------------
       def hierarchyInstanceNameByIdx(m, k)
         if ($k == 2) "Process Group Instances"
         else if ($k == 3) processGroupInstanceName($m)
         else if ($k == 4) "Services"
         else if ($k == 5) serviceName($m)
         else if ($k == 6) "Service Method Groups"
         else if ($k == 7) methodGroupName($m)
         else if ($k == 8) "Service Methods"
         else if ($k == 9) methodGroupInstanceName($m)
         else "UNKNOWN_INSTANCE"
       
       def serviceEntityId(m)
         coalesce(
           $m.extras.parent_service_id,
           if (not(isBlank($m.extras.entityId)) and starts-with($m.extras.entityId, "SERVICE-"))
             $m.extras.entityId
           else
             null
         )
       
       def smgEntityId(m)
         coalesce(
           $m.extras.parent_service_method_group_id,
           if (not(isBlank($m.extras.entityId)) and starts-with($m.extras.entityId, "SERVICE_METHOD_GROUP-"))
             $m.extras.entityId
           else
             null
         )
       
       // ---------------- depth rules ----------------
       // Only SERVICE_METHOD_GROUP-* or SERVICE_METHOD-* exist.
       def serviceDepthFromEntityId(m)
         if (not(isBlank($m.extras.entityId)) and starts-with($m.extras.entityId, "SERVICE_METHOD-")) 9
         else if (not(isBlank($m.extras.entityId)) and starts-with($m.extras.entityId, "SERVICE_METHOD_GROUP-")) 7
         else
           if (mgSize($m) >= 2 and $m.measurementGroup[1] == "service") 5 else 6
       
       def fullDepth(m)
         if ($m.extras.CI_Type == "PROCESS_GROUP") 2
         else if ($m.extras.CI_Type == "PROCESS_GROUP_INSTANCE") 3
         else if ($m.extras.CI_Type == "SERVICE") serviceDepthFromEntityId($m)
         else 0
       
       // ---------------- IDs per hierarchy level ----------------
       // We DO suffix ONLY real levels (3,5,7,9). Containers NEVER get suffix.
       def pgiEntityId(m)
         coalesce(
           $m.extras.parent_process_group_instance_id,
           if ($m.extras.CI_Type == "PROCESS_GROUP_INSTANCE") $m.extras.entityId else null
         )
       
       def hierarchyEntityIdByIdx(m, k)
         if ($k == 3) pgiEntityId($m)
         else if ($k == 5) serviceEntityId($m)
         else if ($k == 7) smgEntityId($m)
         else if ($k == 9) $m.extras.entityId
         else null
       
       def parentEntityIdForK(m, k)
         if ($k <= 2) null else hierarchyEntityIdByIdx($m, $k - 1)
       
       def findHostType(m)
         if ($m.extras.CI_Type == "APPLICATION" or $m.extras.CI_Type == "PROCESS_GROUP") $m.extras.CI_Type else "Server"
       
       // ---------------- common unique-name logic ----------------
       def uniqueEntityNameForLevel(m, k)
         let baseName = nonBlankSanitized(hierarchyEntityNameByIdx($m, $k), "UNKNOWN_ENTITY_NAME")
         if (isContainerLevel($k))
           $baseName
         else
           let idk = hierarchyEntityIdByIdx($m, $k)
           if (isBlank($idk)) $baseName else string($baseName + "_" + $idk)
       
       def uniqueParentEntityNameForLevel(m, k)
         if ($k <= 2) null
         else
           let parentBase = nonBlankSanitized(hierarchyEntityNameByIdx($m, $k - 1), "UNKNOWN_PARENT_ENTITY_NAME")
          
        if (isContainerLevel($k - 1))
             $parentBase
           else
             let pid = hierarchyEntityIdByIdx($m, $k - 1)
             if (isBlank($pid)) $parentBase else string($parentBase + "_" + $pid)
       
       // ---------------- labels builder ----------------
       def labelsObj(host, entTypId, entName, metricName, unit, extId, parentName, parentTypeId, instanceName, hostType)
         if ($parentName == null)
           {
             "metricName": $metricName,
             "hostname": $host,
             "entityTypeId": $entTypId,
             "entityName": $entName,
             "entityId": nonBlankSanitized($productName, "Dynatrace") + ":" + nonBlankSanitized($host, "HOST") + ":" + $entTypId + ":" + $entName,
             "unit": $unit,
             "isKpi": "true",
             "hostType": $hostType,
             "source": nonBlankSanitized($productName, "Dynatrace"),
             "external_id": $extId
           }
         else
           {
             "metricName": $metricName,
             "hostname": $host,
             "entityTypeId": $entTypId,
             "entityName": $entName,
             "entityId": nonBlankSanitized($productName, "Dynatrace") + ":" + nonBlankSanitized($host, "HOST") + ":" + $entTypId + ":" + $entName,
             "unit": $unit,
             "isKpi": "true",
             "hostType": $hostType,
             "source": nonBlankSanitized($productName, "Dynatrace"),
             "external_id": $extId,
             "extras": {
               "parentEntityName": nonBlankSanitized($parentName, "UNKNOWN_PARENT_NAME"),
               "parentEntityTypeId": nonBlankSanitized($parentTypeId, "UNKNOWN_PARENT_TYPE"),
               "instanceName": $instanceName
             }
           }
       
       // ---------------- emit HOST-only ----------------
       def emitTopLevelOnly(m)
         let host  = hostName($m)
         let extId = coalesce(string("DYNATRACE_" + $m.extras.CI_Type + "-" + $m.extras.entityId), $m.extras.ciExternalId)
         let entName = nonBlankSanitized(hostEntityName($m), "UNKNOWN_ENTITY_NAME")
       
         {
           "labels": labelsObj(
             $host,
             hostEntityTypeId($m),
             $entName,
             metricToBmcMetricName($m),
             $m.unit,
             $extId,
             null, null, null,
          findHostType($m)
           ),
           "samples": [{ "value": $m.value, "timestamp": $m.originTimestamp }]
         }
       
       // ---------------- emit NON-HOST TOP entity at level k (no parent) ----------------
       def emitNonHostTopAtK(m, k)
         let host  = hostName($m)
         let extId = coalesce(string("DYNATRACE_HOST-" + $m.extras.parent_host_id), $m.extras.ciExternalId)
       
         let entTypId = nonBlankSanitized(hierarchyEntityTypeId($m, $k), "UNKNOWN_ENTITY_TYPE_ID")
         let uniqueEntName = uniqueEntityNameForLevel($m, $k)
       
         {
           "labels": labelsObj(
             $host,
             $entTypId,
             $uniqueEntName,
             "Availability",
             "Percent",
             $extId,
             null, null, null,
          findHostType($m)
           ),
           "samples": [{ "value": "100", "timestamp": $m.originTimestamp }]
         }
       
       // ---------------- emit NON-HOST hierarchy node at level k (Availability) ----------------
       def emitNonHostAtK(m, k)
         let host  = hostName($m)
         let extId = coalesce(string("DYNATRACE_HOST-" + $m.extras.parent_host_id), $m.extras.ciExternalId)
       
         let entTypId = nonBlankSanitized(hierarchyEntityTypeId($m, $k), "UNKNOWN_ENTITY_TYPE_ID")
         let uniqueEntName = uniqueEntityNameForLevel($m, $k)
       
         let parentName = uniqueParentEntityNameForLevel($m, $k)
         let parentType =
           if ($k <= 2) null else nonBlankSanitized(hierarchyEntityTypeId($m, $k - 1), "UNKNOWN_PARENT_ENTITY_TYPE_ID")
       
         let instName = nonBlankSanitized(hierarchyInstanceNameByIdx($m, $k), "UNKNOWN_INSTANCE_NAME")
       
         {
           "labels": labelsObj(
             $host,
             $entTypId,
             $uniqueEntName,
             "Availability",
             "Percent",
             $extId,
             $parentName,
             $parentType,
             $instName,
          findHostType($m)
           ),
           "samples": [{ "value": "100", "timestamp": $m.originTimestamp }]
         }
       
       // ---------------- emit metric LEAF as a child entity ----------------
       def emitMetricLeafChild(m, cnt)
         let host  = hostName($m)
         let extId = coalesce(string("DYNATRACE_HOST-" + $m.extras.parent_host_id), $m.extras.ciExternalId)
       
         let parentEntityType = nonBlankSanitized(hierarchyEntityTypeId($m, $cnt), "UNKNOWN_PARENT_ENTITY_TYPE_ID")
         let parentName = uniqueEntityNameForLevel($m, $cnt)
       
         let mgName = nonBlankSanitized(hostEntityName($m), "UNKNOWN_MEASUREMENT_GROUP")
         let leafMetricName = metricToBmcMetricName($m)
       
         let safeEntityId = coalesce($m.extras.entityId, "UNKNOWN_ENTITY_ID")
       
         let leafEntityName = nonBlankSanitized($mgName + "_" + $safeEntityId, "UNKNOWN_LEAF_ENTITY")
         let leafEntityTypeId = nonBlankSanitized(string($parentEntityType + "_" + $mgName), "UNKNOWN_LEAF_TYPE")
         let leafInstanceName = nonBlankSanitized(mgEntityInstanceName($m), "UNKNOWN_LEAF_INSTANCE")
       
         {
           "labels": labelsObj(
             $host,
             $leafEntityTypeId,
             $leafEntityName,
             $leafMetricName,
             $m.unit,
             $extId,
             $parentName,
             $parentEntityType,
             $leafInstanceName,
          findHostType($m)
           ),
           "samples": [{
             "value": $m.value,
             "timestamp": $m.originTimestamp
           }]
         }
       
       // ---------------- expand one metric record ----------------
       def expandOne(m)
         if ($m.extras.CI_Type == "HOST"
             or $m.extras.CI_Type == "PROCESS_GROUP"
             or contains($m.extras.CI_Type, "APPLICATION"))
           [ emitTopLevelOnly($m) ]
       
         // ---------------- SERVICE special handling ----------------
         else if ($m.extras.CI_Type == "SERVICE" and isBlank($m.extras.parent_process_group_instance_display_name))
           let cnt = fullDepth($m)
           let serviceLevelDepth = serviceDepthFromEntityId($m)
       
           dropNulls([
             // Emit current SERVICE-level as TOP (correct type+name for level)
             emitNonHostTopAtK($m, $serviceLevelDepth),
       
             // If entity is a Service Method Group (depth=7): emit container+method under it
             if ($serviceLevelDepth == 7) emitNonHostAtK($m, 8) else null,
             if ($serviceLevelDepth == 7) emitNonHostAtK($m, 9) else null,
       
             // If entity is a Service Method (depth=9): top-level already emitted above
       
             // If entity is Service only (depth=5) (or anything else not 7/9):
             // create full: Service -> Service Method Group -> Service Methods
             if ($serviceLevelDepth != 7 and $serviceLevelDepth != 9) emitNonHostAtK($m, 6) else null,
             if ($serviceLevelDepth != 7 and $serviceLevelDepth != 9) emitNonHostAtK($m, 7) else null,
             if ($serviceLevelDepth != 7 and $serviceLevelDepth != 9) emitNonHostAtK($m, 8) else null,
             if ($serviceLevelDepth != 7 and $serviceLevelDepth != 9) emitNonHostAtK($m, 9) else null,
       
             // metric leaf
             if ($cnt >= 2 and mgSize($m) >= 2) emitMetricLeafChild($m, $cnt) else null
           ])
       
         // ---------------- default non-HOST path ----------------
         else
           let cnt = fullDepth($m)
           dropNulls([
             if ($cnt >= 2) emitNonHostAtK($m, 2) else null,
             if ($cnt >= 3) emitNonHostAtK($m, 3) else null,
             if ($cnt >= 4) emitNonHostAtK($m, 4) else null,
             if ($cnt >= 5) emitNonHostAtK($m, 5) else null,
             if ($cnt >= 6) emitNonHostAtK($m, 6) else null,
             if ($cnt >= 7) emitNonHostAtK($m, 7) else null,
             if ($cnt >= 8) emitNonHostAtK($m, 8) else null,
             if ($cnt >= 9) emitNonHostAtK($m, 9) else null,
       
             // metric leaf
             if ($cnt >= 2 and mgSize($m) >= 2) emitMetricLeafChild($m, $cnt) else null
           ])
       
       // ---------------- ENTRY ----------------
       let items = if (is-array(.)) . else [.]
       flatten([ for ($items) expandOne(.) ])
       
    7. Click SAVE & CLOSE.
14. On the SOURCES panel, move the slider to the right to start the data stream for the connector you created.