UI Components
The Sentry Integration Platform provides developers with the ability to define User Interface components to render within specific parts of Sentry's UI, through a JSON-based schema. Two possible use-cases are Issue Link and Stack Trace Link.
Schema
The UI components are specified in the schema section of integration details. The required form of this schema is:
{
"elements": [
// Each element is a specification for a component the developer wants to use.
...
]
}
Component Details
Issue Link
With issue linking, the developer can connect Sentry issues with a task in their project management system. This functionality provides a way to use any project management tool the developer uses or develops.
The Issue Link component displays "Link <Service> Issue" in the Issue sidebar, which opens a modal allowing the user to create or link the issue to a task in the external service. For example, this is what our Clubhouse integration looks like.
Schema
{
"type": "issue-link",
"link": {
"uri": <String>,
"required_fields": <Array<FormField>>,
"optional_fields": <Array<FormField>>
},
"create": {
// Same as "link" schema
}
}
Attributes of the link and create fields
- uri - (Required) The URI to request when the User submits the Link/Create Issue form.
- required_fields - (Required) List of
FormField
components the User is required to complete. - optionalfields - List of optional
Form Field
components the User _may complete.
A FormField
can be one of three types (which behave like their HTML equivalents) — Select
, Text
, and TextArea,
described below.
Select
{
"type": "select",
"label": <String>,
"name": <String>,
"uri": <URI>,
"async": <Bool>,
"options": <Array<String, String>>,
"depends_on": <Array<String>> (optional)
}
Attributes
- label - (Required) Label text to be rendered for the form field
- name - (Required) Value to use in
name
attribute of the field - uri -(Required if developer doesn't provide
options
) URI to retrieve values from. - async - (Optional) Used only if
uri
is present. If true (default), will query the URI as the user types, for autocomplete suggestions (see response format below). If false, will query the URI once initially to retrieve all possible options. This request must succeed, and the response must return data in the format Sentry expects, otherwise the entire component won't render. - options - (Required if developer doesn't provide
uri
) Static list of options in the format of [label, value] - depends_on - (Optional) If a field value depends on the value of another field, a request will be made to load those options when the dependent field is set.
- skip_load_on_open (Optional) If true, this field will not load options when the page loads. Instead, it will wait for the user to start typing before fetching options.
URI Request Format
The request sent to the uri
to load options is a GET
request. The parameters are encoded into the query parameters as such:
{
"installationId": <String>,
"projectSlug": <String>,
"query": <String>,
"dependentData": <String> (optional),
}
- installationId - The ID of the installation associated with the request
- projectSlug - The slug of the project in Sentry
- query - The search term the user is typing
- dependentData - A JSON encoded string of the dependent data if that field has
depends_on
set
URI Response Format
Response from uri
, when specified, must be in the following format:
[
{
"label": <String>,
"value": <String>,
"default": <Bool>, (optional)
},
...
]
Text
Schema
{
"type": "text",
"label": <String>,
"name": <String>,
(optional) default: <String>,
}
Attributes
- label - (Required) Label text to be rendered for the form field
- name - (Required) Value to use in
name
attribute of the field - default - default to pre-populate with. Options include
issue.title
andissue.description
issue.title
- title of the Sentry issueissue.description
- description of the Sentry issue
Textarea
Schema
{
"type": "textarea",
"label": <String>,
"name": <String>,
(optional) default: <String>,
}
Attributes
- label - (Required) Label text to be rendered for the form field
- name - (Required) Value to use in
name
attribute of the field - default - default to pre-populate with options include
issue.title
andissue.description
issue.title
- title of the Sentry issueissue.description
- description of the Sentry issue
Example of a complete issue-link schema
{
"elements": [
{
"type": "issue-link",
"link": {
"uri": "/sentry/issues/link",
"required_fields": [
{
"type": "select",
"label": "Issue",
"name": "issue_id",
"uri": "/sentry/issues"
}
]
},
"create": {
"uri": "/sentry/issues/create",
"required_fields": [
{
"type": "text",
"label": "Title",
"name": "title"
}
],
"optional_fields": [
{
"type": "select",
"label": "Owner",
"name": "owner",
"uri": "/sentry/members",
"async": true
}
]
}
}
]
}
Stack Trace Link
This feature allows the developer to insert a link within a stack trace frame. The link contains details about the project, file, line number, etc. It can also be used to view the file on another website, continue debugging in a different monitoring tool, etc. For example, this is what our Rookout integration looks like using stack trace linking.
Schema
{
"type": "stacktrace-link",
"uri": <URI>,
}
Attributes
uri
- (Required) The link destination. Sentry will automatically add the following query params to the link.installationId
- Your integration's installation ID (helps you determine the requesting Sentry org)projectSlug
- slug of the project the issue belongs tofilename
- full path of the stack frame filelineNo
- line number of the stack trace in the file
Example
"elements": [
{
"type": "stacktrace-link",
"uri": "/stacktrace-redirect",
}
]
Any time a component supports a uri
attribute, Sentry will make a request to the third-party service using the Base URL or their webhook_url
.
For a more complete description of the grammar, see the source code.
Create/Link Issue
If you have a UI component for issue linking and a user attempts to create or link an issue, it will send a request to your service based on the uri
you provide.
Request Format
The request that is sent is a POST
request, so all the information is stored in the body.
Schema
{
"fields": <Object>,
"installationId": <String>,
"issueId": <String>,
"webUrl": <String>,
"project": {"slug": <String>, "id": <String>},
"actor": {"type": "user", "name": <String>, "id": <String>},
}
Attributes
fields
- Key/value pairs of the data in the form fieldsinstallationId
- The ID of the installation associated with the requestissueId
- The ID of the issue in SentrywebUrl
- The URL of the issue in Sentryproject
:slug
- The slug of the project in Sentryid
- The ID of the project in Sentry
actor
:name
- The name of the user in Sentryid
- The ID of user in Sentry
Response Format
When creating or linking an issue, the response format must have the following schema:
Schema
{
"webUrl": <String>,
"project": <String>,
"identifier": <String>,
}
Attributes
webUrl
: The URL of the linked issue in your project management systemproject
: The first part of the displayed issue that should probably be associated with a project in your systemidentifier
: The second part of the displayed issue that should be unique to the project
When an external issue is created or linked in Sentry, Sentry shows a display name that links back to the service where it was either created or linked. The display name is composed of two pieces: the project
and the identifier
. A hash (#) connects each piece. Here's an example of what it looks like in Sentry:
Supplementary Information
Error Handling
Component rendering either 100% works or shows nothing. To protect the integration from looking chaotic due to errors we have no control over; if any part of the third-party component rendering fails, nothing will render.