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 intents mechanism:
- Source app - Sends an intent to another app
- Target app - Receives the intent and performs an action 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:
The
source app
sends the request to the app shell. For example, using thesendIntent
method from@dynatrace-sdk/navigation
. The actual communication happens using thewindow.postMessage
API.The
app shell
allows the user to select an app from a list of apps that can handle the intent.The app shell opens the
target app
in an iframe and passes the intent as query arguments in the URL.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:
const intentPayload = {
'dt.entity.host': 'HOST-F66B242CD3A5E38E',
};
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.
- To learn more about how to send an intent, see the Send intents guide
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.config.ts
file. It can then perform some action on the received intent.
- To learn more about how to receive an intent, see the Receive intents guide.
- To learn more about
app.config.ts
configuration, see the Dynatrace App Toolkit reference.
App shell
The app shell handles the intent sent by the source app.
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
- Shows the
The app shell launches the target app of the given
appId
.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's app.config.ts
. 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',
},
}
}
}
}
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
.
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.