Rate this page:
In Compass, there are two main methods for getting events from tools to show on a component’s activity feed. One method is by connecting event sources from the component’s details page in Compass and the other is by sending events using the Compass REST API.
To send events using the REST API:
Here, we’ll use a cURL command as an example to show you how to call the REST API. You can either use the cURL command we’ve shown here or call the REST API using a different method. Learn more about the Compass REST API
An event source is a tool connected to Compass that supplies events to a component's activity feed, for example, Bitbucket or Github.
Compass uniquely identifies an event source based on externalEventSourceId
and eventType
.
For example, a Bitbucket repository creates events of multiple types such as build events and deployment events.
In this scenario, the externalEventSourceId
is the Bitbucket repository's ID, while the eventType
is deployment
or build
based on the type of event.
So, to send both deployment and build events from the repository to the activity feed, we need to create two different event sources -- each having the same externalEventSourceId
but a different eventType
.
The first step is to set up an event source using our GraphQL API. Learn more about the Atlassian platform GraphQL API
To set up the event source:
Use this query call to get the cloud ID:
Query
1 2query example { tenantContexts(hostNames:["your-domain.atlassian.net"]) { cloudId } }
Replace the hostNames
input with your Compass site's name and run the query.
Use this query to create the event source:
Query
1 2mutation createEventSource($input: CreateEventSourceInput!) { compass { createEventSource(input: $input) { eventSource { id } success errors { message } } } }
Variables
1 2{ "input": { "cloudId": "<your cloud ID>", "externalEventSourceId": "<external event source ID>", "eventType": "CUSTOM" } }
Replace the input variables:
cloudId
with your Compass site’s cloud ID you found earlier.externalEventSourceId
with an external event source ID that uniquely identifies the source of your events, for example, the ID of a repository that generates deployment events.eventType
with a valid event type for the API. This example uses the CUSTOM
event type. Refer to the createEventSource
mutation in the Atlassian platform GraphQL API explorer for a list of all valid event types.externalEventSourceId
and eventType
uniquely identifies an event source. Learn more about what is an event sourceRun the query and note down the id
of the eventSource
that the query returns.
Use this query to connect the event source:
Query
1 2mutation attachEventSource($input: AttachEventSourceInput!) { compass { attachEventSource(input: $input) { success errors { message } } } }
Variables
1 2{ "input": { "eventSourceId": "<event source ID>", "componentId": "<component ID>" } }
Replace the input variables:
eventSourceId
with the ID of the event source you noted earlier.componentId
with the component’s ID you want to connect the event source to. You can find the component's ID from its details page in Compass. When you’re there, select more actions (•••), then select Copy component ID. Learn how to view a component's detailsRun the query.
You need an Atlassian API token to call the Compass REST API. Log in to https://id.atlassian.com/manage/api-tokens to create the API token.
Learn more managing API tokens for your Atlassian account
Here, we’ve used a cURL command as an example to show you how to call the REST API. This example sends an event of the custom
type to a component's activity feed. Add this cURL command to your CI/CD tool, such as Bitbucket Pipelines or Github Actions, or run it in your terminal to call the REST API.
You can either use the cURL command we’ve shown here or use another method to call the REST API. Learn more about the Compass REST API
This API is rate limited. Only 100 requests per user per minute are allowed.
To call the REST API:
Use this cURL command:
1 2curl \ --request POST \ --url https://example.atlassian.net/gateway/api/compass/v1/events \ --user "$USER_EMAIL:$USER_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data "{ \"cloudId\": \"$CLOUD_ID\", \"event\": { \"custom\": { \"updateSequenceNumber\": 1, \"displayName\": \"name\", \"description\": \"description\", \"url\": \"www.exampleUrl.com\", \"lastUpdated\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\", \"externalEventSourceId\": \"$EXTERNAL_EVENT_SOURCE_ID\", \"customEventProperties\": { \"id\": \"1\", \"icon\": \"INFO\" } } } }"
Replace the variables in the cURL command:
On line number 4 --user "$USER_EMAIL:$USER_API_TOKEN" \
, specify your Atlassian account email address and Atlassian API token that you created earlier.
For security purposes, we recommend storing the values of $USER_EMAIL
and $USER_API_TOKEN
as external environment variables, instead of hardcoding them into the script.
On line number 8 \"cloudId\": \"$CLOUD_ID\"
, specify the cloud ID of the site that you retrieved earlier.
On line number 13 \"lastUpdated\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\"
, specify the timestamp when the event was sent. This is an optional variable. You can:
$(date -u +'%Y-%m-%dT%H:%M:%SZ')
with a specific timestamp following the ISO-8601 standard of YYYY-MM-DDThh:mm:ssZ
, where:
YYYY-MM-DD
represents the date in year, month, and dayT
is the delimiter between the date and the timehh:mm:ss
is the time in hours, minutes, and secondsZ
represents zero UTC offsetAn example of the timestamp value in this line is \"timestamp\": \"2022-01-31T01:23:45Z\"
.
On line number 14 \"externalEventSourceId\": \"$EXTERNAL_EVENT_SOURCE_ID\"
, specify the external event source ID. It is the same as externalEventSourceId
, the ID which you used to create the event source earlier. For example, the ID of a repository that generates deployment events.
Test the cURL command by running it in Terminal on Mac or Linux, Command Prompt on Windows.
deployment
type appear as Other events only on the timeline view of the activity feed. Non-deployment events do not appear on the list view of the activity feed. Learn how to view a component's activity feedAn example of how to use the cURL command is to add it to your build system or deployment scripts to automatically send events to the activity feed of your component.
The Compass REST API supports many other event types. See the Compass REST API reference documentation for information about supported event types and event details for a particular event type.
Rate this page: