Skip to main content

Receive intents

You can allow other apps to send data to your Dynatrace App. An app can receive an intent with a payload that you can use to perform an action. For example:

  • Pin the result of a DQL query on a dashboard
  • Set up an alert on a metric from a DQL query result
  • Show details of an app (based on its appId)

To receive an intent, you need to do the following:

Declare the intents​

An app can handle multiple intents that you declare in your app configuration file inside the app.intents property. You define an intent using an object where the key of the object is intentId. It consists of the following properties:

  • description — A short statement describing the action. It appears in the Open with... dialog.
  • properties — An object where you can define every payload property and its corresponding data type. Every payload property is defined using the key of this object, and the corresponding data type is defined with an object with the following properties:
    • required — A boolean that defines if a property is mandatory or not.
    • schema — A JSON Schema object describing the shape of the property
Note

It is mandatory to have at least one required payload property.

Here is an example of an app configuration with intent declarations:

{
  "environmentUrl": "<Your-Environment-URL>",
  "app": {
    "id": "<Your-App-ID>",
    "name": "<Your-App-Name>",
    "version": "0.0.0",
    "description": "<Your-App-Description>",
    "scopes": [],
    "intents": {
      "view_host": {
        "description": "View the host",
        "properties": {
          "dt.entity.host": {
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        }
      },
      "view_query": {
        "description": "View query",
        "properties": {
          "dt.query": {
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

In app.config.ts, you can also define intents using the getIntentPropertyDeclaration helper function from @dynatrace-sdk/navigation. This function lets you easily create intent declarations for built-in properties. It takes two parameters: a built-in property you want to declare and a boolean value to mark whether the property is required.

Tip

Use your IDE's autocompletion to see the list of available built-in properties when using getIntentPropertyDeclaration function.

Receive intent payload​

After you declare the type of intents your app can handle, the next step is to receive an intent in your app. You can achieve this using the getIntent method from the @dynatrace-sdk/navigation package.

Note

You need to install the @dynatrace-sdk/navigation npm package in your project to use intents.

Here is an example of using getIntent with React's useEffect:

import React, { useEffect, useState } from 'react';
import { Code, Paragraph } from '@dynatrace/strato-components-preview';
import { getIntent, IntentPayload } from '@dynatrace-sdk/navigation';

export const YourComponent = () => {
  const [intentPayload, setIntentPayload] = useState<IntentPayload>();
  useEffect(() => {
    const intent = getIntent();
    if (intent) {
      setIntentPayload(intent.getPayload());
    }
  }, []);

  return (
    <>
      {intentPayload && (
        <Paragraph>
          Received Intent Payload <Code>{JSON.stringify(intentPayload)}</Code>.
        </Paragraph>
      )}
    </>
  );
};

Things to know about the getIntent method:

  • The getIntent method returns an object of Intent type.
  • You can call the getIntent method anywhere in your Dynatrace App. For example, in App.tsx, a component, a custom hook, react context, and elsewhere.
Caution

If your app has routing configured, you need to create a route /intent/:intentId in your app to handle the intent using the getIntent method. The app shell opens this route and passes the intent object synchronously. If this route doesn't exist, your app won't receive the intent.

Handle multiple intents​

Each type of intent has a unique id. If your app handles multiple intents, you can target a specific intent using that id.

Here is an example of handling two different intents using the getId method:

import { useEffect } from 'react';
import { getIntent } from '@dynatrace-sdk/navigation';

export const AnotherComponent = () => {
  useEffect(() => {
    const intent = getIntent();

    if (intent?.getId() === 'share_chart') {
      // for example: shareChart(intent.context);
    }

    if (intent?.getId() === 'view_query') {
      // for example: viewQueryInTable(intent.context);
    }
  }, []);

  // … jsx and the rest of the code
};

In this example, if intentId is share_chart, the call is to a hypothetical method named shareChart. However, if intentId is view_query, the call is to a hypothetical method named viewQueryInTable. This is how you can perform different actions with different intents.

Still have questions?
Find answers in the Dynatrace Community