Ingest business event via API

You can configure external business or IT systems to send business events in JSON format to the business events API (REST endpoint). It can be achieved through:

Ingest Endpoint
DQL Endpoint

Set up OAuth for API access

Before you begin, you need to set up OAuth for API access. To do it, perform the following steps:

Create a new OAuth client

Create a new policy

Grant the policy to a group

Obtain an access token

Create a new OAuth client

You can create new OAuth clients on the account management page in your Dynatrace tenant, following the steps mentioned below.

In the user menu in the upper-right corner of the page, go to Account management > Account Management API > Create new Client.
Provide a description and email addresses of your users.
Choose the needed scopes by selecting one or more options. For reading and writing business events select:
- Read bizevents: (storage:bizevents:read)
- Read buckets: (storage:buckets:read)
- Write/edit events (storage:events:write)
Select Generate client. Make sure to save your client's secret since you won't have the chance to see it again.

Create a new policy

To use the OAuth client, you need to make sure that the right policy is assigned to your user. To search for/create a policy:

In the user menu in the upper-right corner of the page, go to Account management > Identity management > Policy management.
Select Add policy, name the policy and add the following policy statements for writing and querying business events:
- ALLOW storage:buckets:read WHERE storage:table-name = "bizevents;
- ALLOW storage:bizevents:read;
- ALLOW storage:events:write;

Grant the policy to a group

You can assign the policy to a group where your user belongs, or create a new group where you will add your user.

In the user menu in the upper-right corner of the page, go to Account management > Identity management > Group management.
Select Edit to edit a group, go to the Policies tab, and select the policies that you need to bind (for example, the ones you created).
Select Save.

If you have access to multiple tenants, make sure that you work on the right one. You get an overview of all tenants by selecting Accounts in the upper left corner below the Dynatrace logo.

Obtain an access token

You can use the created OAuth client to obtain an access token for the API. Follow the OAuth 2.0 flow as described below and send a request to the access token url. You will receive a bearer access token that you can use for authentication in the other endpoints.

Endpoint-Url: https://sso.dynatrace.com/sso/oauth2/token
Method: POST
Content-Type: application/x-www-form-urlencoded
Headers:

Key	Value
grant_type	client_credentials
client_id	`dt0s02.*`
client_secret	`dt0s02..`

Example API request

plaintext
POST /sso/oauth2/token HTTP/2
     Host: sso-sprint.dynatracelabs.com
     User-agent: insomnia/2022.7.5
     Cookie: AWSALBCORS=ZR+kk/lWEdAwXeX6tNt+cR2c5NXQih7nYHN2ZGHZuJvw8gWAc2cwKOA+Rf5JfHRRmLaqI+d/4jRT3srx2riGVL40DqbqUMNPCYSiAxklZdf23E0OfTjWidu0mBh+; AWSALB=ZR+kk/lWEdAwXeX6tNt+cR2c5NXQih7nYHN2ZGHZuJvw8gWAc2cwKOA+Rf5JfHRRmLaqI+d/4jRT3srx2riGVL40DqbqUMNPCYSiAxklZdf23E0OfTjWidu0mBh+; dtCookie=v_4_srv_2_sn_CBC4338B6C33199ECBD7397DBFDB1F6D_perc_100000_ol_0_mul_1_app-3A24c6ab183dfd113c_1_rcs-3Acss_0
     Content-type: application/x-www-form-urlencoded
     Accept: application/x-www-form-urlencoded, application/json
     Content-length: 150
     Headers: grant_type=client_credentials&client_id=dt0s02.UEJVIEV4&client_secret=dt0s02.UEJVIEV4.K2GBRXPS2IRT6UJPK5AE66LETUPH7B6WQLKHJ6ITX3BKCVXE4JDOWKSKTR536G6F

Example API response

plaintext
TTP/1.1 200 OK
  Date: Thu, 01 Sep 2022 05:15:12 GMT
  Content-Type: application/json
  Content-Length: 1060
  Connection: keep-alive
  Set-Cookie: AWSALB=Dxxl1OSC7nq1HaIF9CzQxmKyqxDyYigbnd2QB0ZtMJ9yKDzgkxMubR/uT7XpatOrThreoACtEQ+fF7kbHz7SUBRzdsHzUHIqr36V8Rf3JL9Uk/HNQDKxf3PeBrwW; Expires=Thu, 08 Sep 2022 05:15:12 GMT; Path=/
  Set-Cookie: AWSALBCORS=Dxxl1OSC7nq1HaIF9CzQxmKyqxDyYigbnd2QB0ZtMJ9yKDzgkxMubR/uT7XpatOrThreoACtEQ+fF7kbHz7SUBRzdsHzUHIqr36V8Rf3JL9Uk/HNQDKxf3PeBrwW; Expires=Thu, 08 Sep 2022 05:15:12 GMT; Path=/; SameSite=None; Secure
  X-Frame-Options: deny
  Frame-Options: deny
  X-XSS-Protection: 1; mode=block
  X-Content-Type-Options: nosniff
  Content-Security-Policy: default-src 'self' https://static.sso-sprint.dynatracelabs.com; script-src 'self' 'unsafe-inline' https://static.sso-sprint.dynatracelabs.com; frame-ancestors 'none'; form-action http: https:; report-uri https://report-csp.internal.dynatracelabs.com/sso2.0
  X-Content-Security-Policy: default-src 'self' https://static.sso-sprint.dynatracelabs.com; script-src 'self' 'unsafe-inline' https://static.sso-sprint.dynatracelabs.com; frame-ancestors 'none'; form-action http: https:; report-uri https://report-csp.internal.dynatracelabs.com/sso2.0
  Strict-Transport-Security: max-age=31536000; preload
  Cache-Control: no-cache, no-store, no-transform
  Pragma: no-cache
  {"scope":"account-idm-read account-idm-write account-env-read account-env-write account-uac-read account-uac-write iam-policies-management iam:policies:write iam:policies:read iam:bindings:write iam:bindings:read iam:effective-permissions:read storage:bizevents:read storage:events:read storage:events:write","token_type":"Bearer","expires_in":300,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiI2YWUwMmFmNC01NmIwLTRhM2MtODI0OS1mYjc2ZDgyOTYwYTQiLCJhdWQiOiJkdDBzMDIuVUVKVklFVjQiLCJyZXMiOiJ1cm46ZHRhY2NvdW50OjJiMjM2NDM4LTJhMzEtNDg3Mi04NjU1LWJjYTRmYThhZjkxNyIsIl9jbGFpbV9uYW1lcyI6eyJncm91cHMiOiIwIn0sInNjb3BlIjoiYWNjb3VudC1pZG0tcmVhZCBhY2NvdW50LWlkbS13cml0ZSBhY2NvdW50LWVudi1yZWFkIGFjY291bnQtZW52LXdyaXRlIGFjY291bnQtdWFjLXJlYWQgYWNjb3VudC11YWMtd3JpdGUgaWFtLXBvbGljaWVzLW1hbmFnZW1lbnQgaWFtOnBvbGljaWVzOndyaXRlIGlhbTpwb2xpY2llczpyZWFkIGlhbTpiaW5kaW5nczp3cml0ZSBpYW06YmluZGluZ3M6cmVhZCBpYW06ZWZmZWN0aXZlLXBlcm1pc3Npb25zOnJlYWQgc3RvcmFnZTpiaXpldmVudHM6cmVhZCBzdG9yYWdlOmV2ZW50czpyZWFkIHN0b3JhZ2U6ZXZlbnRzOndyaXRlIiwiX2NsYWltX3NvdXJjZXMiOnsiMCI6eyJlbmRwb2ludCI6bnVsbH19LCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJkYW5pZWwubWFyc2NobmlnQGR5bmF0cmFjZS5jb20iLCJleHAiOjE2Nzk5ODk1MTUsImlhdCI6MTY3OTk4OTIxNSwiZ3QiOiJjYyIsImp0aSI6IjllNWRiNjc4LWFmNTQtNDBhNi1hOTc5LTY5ODQwZmFmYTNhOSIsImVtYWlsIjoiZGFuaWVsLm1hcnNjaG5pZ0BkeW5hdHJhY2UuY29tIn0.iNm1WMqrEUZKOM3HyN7XEYsPyR3yaMPG-mvgUoLHpfXMzu73KadfUhUKFTlLVJwf7kVXzlYOxiCsS3nW_7zWVQ","resource":"urn:dtaccount:2b236438-2a31-4872-8655-bca4fa8af917"}

Business event enrichment

When you report business events, Dynatrace enriches them by adding additional context. For example, Dynatrace adds information about your application, geolocation, device, and more.

For details, see Business event enrichment.

Ingest endpoint

Business Analytics offers a dedicated API to ingest JSON format data into Dynatrace.
To access the dedicated Environment API:

In Dynatrace, open the User menu by selecting the User icon in the upper-right corner.
Select Environment API v2.
Expand Business events, then POST section.
- Endpoint-Url: [https://\|https:] {environmentId}.dynatrace.com/api/v2/bizevents/ingest
- Method: POST
- Authentication: OAuth
Note: Business Events API limits the data size to 1 MB per request.

Request body

Pure JSON: no mandatory fields are required for ingest

Example payload using pure JSON:

json
{
    "paymentId": "pid-{% randomnumber 1, 10000, 0, 0 %}",
    "orderId": "oid-{% randomnumber 1, 10000, 0, 0 %}",
    "amount": {% randomnumber 1, 10000, 0, 0 %},
    "event.type": "com.bizingest.json.flat"
}

In addition to the pure JSON format, Dynatrace offers the CloudEvent and the CloudEvent Batch formats.

CloudEvent

Example payload using CloudEvent

CloudEvent (application/cloudevent+json)

json
{
  "specversion": "1.0",
  "id": "{% uuid 'v4' %}",
  "source": "ba.dt.local",
  "type": "com.dynatrace.business",
  "time": "{% now 'iso-8601', '' %}",
  "data": {
    "paymentId": "pid-{% randomnumber 1, 10000, 0, 0 %}",
    "orderId": "oid-{% randomnumber 1, 10000, 0, 0 %}",
    "nested": {
      "firstName": "Max",
      "lastName": "Meyer"
    }
  }
}

In the CloudEvent standard, mandatory fields exist and can be enriched by additional data fields. The mandatory fields are:
- Specversion
- Source - automatically converted into event.provider
- Type - automatically converted into event.type
- Id - automatically converted into event.id
Note: Your additional data need to be added in the data object fields. In the example above, the additional data is paymentId, orderId, firstName, and lastName.
CloudEvent batch (batch ingest of events): as in the previous example, mandatory fields exist and can be enriched by additional data fields, such as paymentId and orderId.

Example payload using CloudEvent batch

CloudEvent batch (application/cloudevent-batch+json)

json
[
  {
    "specversion": "1.0",
    "id": "{% uuid 'v4' %}",
    "source": "ba.dt.local",
    "type": "com.dynatrace.business",
    "time": "{% now 'iso-8601', '' %}",
    "data": {
      "paymentId": "pid-{% randomnumber 1, 10000, 0, 0 %}",
      "orderId": "oid-{% randomnumber 1, 10000, 0, 0 %}"
    }
  },
  {
    "specversion": "1.0",
    "id": "{% uuid 'v4' %}",
    "source": "ba.dt.local",
                "type": "com.dynatrace.business",
    "time": "{% now 'iso-8601', '' %}",
    "data": {
      "paymentId": "pid-{% randomnumber 1, 10000, 0, 0 %}",
      "orderId": "oid-{% randomnumber 1, 10000, 0, 0 %}"
    }
  }
]