Skip to main content

Intents

The intents mechanism is one way to extend an app's functionality. An intent is a message object you define in an app that allows you to pass the user flow from one app to another.

There are many reasons for sending intents. For example:

  • Share a chart with the Dashboard app
  • Show details of an app based on the appId

Lifecycle of an intent​

There are three elements involved in the intent mechanism:

  • Source app - Sends an intent to another app
  • Target app - Receives the intent and acts on the intent
  • App shell - Handles the communication between the source and the target app.

Here is what happens when a source app sends an intent:

  1. The source app sends the request to the app shell. For example, using the sendIntent method from @dynatrace-sdk/navigation. The actual communication happens using the window.postMessage API.

  2. The app shell allows the user to select an app from a list of apps that can handle the intent.

  3. The app shell opens the target app in an iframe and passes the intent as query arguments in the URL.

  4. The target app can perform any action on the received intent.

Structure of an intent payload​

An intent payload is a set of key-value pairs that contains information you want to share.

Examples​

Here are some examples of intent payload objects:

payload with host information
const intentPayload = {
  'dt.entity.host': 'HOST-F66B242CD3A5E38E',
};
payload with dt.query and dt.timeframe information
const intentPayload = {
    'dt.query': 'timeseries avg(cpu.temperature)',
    'dt.timeframe': {
      "from": "now-2h",
      "to": "now"
    }
  },
};

Main elements of the intent mechanism​

Source app​

The source app sends the actual intent to the app shell.

Target app​

The target app is the app that receives an intent. Each target app has to define the type of intents that it can receive in the app configuration file. It can then perform some action on the received intent.

App shell​

The app shell handles the intent sent by the source app.

  1. The app shell finds a target app as follows:

    • Shows the Open with... dialog to let the user choose a target app
    • Shows an empty state dialog if no app can handle the intent

  2. The app shell launches the target app of the given appId.

  3. The app shell passes the intent object synchronously to the target app as initialization data using URL query arguments.

Matching intent with apps​

The app shell finds installed apps capable of handling a specific intent by validating the intent object against the intents declared in the app configuration file. The validation mechanism matches the intent payload with the required properties of an intent defined in the target app. In the target app, each intent is defined using a unique intent id.

In the following example, a target app declares two intents with intent id query-existing and query-new.

{
  "intents": {
    "query-existing": {
      "description": "Add a query to existing notebook",
      "properties": {
        "dt.query": {
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "query-new": {
      "description": "Add a query to a new notebook",
      "properties": {
        "dt.query": {
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      }
    }
  }
}
Full example
{
  "environmentUrl": "<Your-Environment-URL>",
  "app": {
    "id": "<Your-App-ID>",
    "name": "<Your-App-Name>",
    "version": "0.0.0",
    "description": "<Your-App-Description>",
    "scopes": [],
    "intents": {
      "query-existing": {
        "description": "Add a query to existing notebook",
        "properties": {
          "dt.query": {
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        }
      },
      "query-new": {
        "description": "Add a query to a new notebook",
        "properties": {
          "dt.query": {
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Both of these intents have the same properties. If an app sends dt.query via an intent, the target app will be listed twice on the Open with dialog. The user can select a specific action in the target app that'll be passed via the intent app route using /intent/:intentId.

Note

The target app only has access to properties defined in its intent declaration. The app shell removes additional properties sent by the source app.

Limitations​

  • The URL length: The app shell creates the URL for each intent as a query argument. In this case, the length of the URL depends on the intent definition. There is no length standard for the URL. However, here is what our tests indicated:
    • Modern browsers can handle up to 2 MB. Address bars are limited to 32 KB.
    • Many mobile browsers become unresponsive for links longer than 16 KB.

Still have questions?
Find answers in the Dynatrace Community