Ingest business event via API
powered by Grail
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
)
- Read bizevents: (
- 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 |
|
client_secret |
|
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.
- Endpoint-Url:
Request body
-
Pure JSON: no mandatory fields are required for ingest
Example payload using pure 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
-
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 ispaymentId
,orderId
,firstName
, andlastName
. -
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
andorderId
.