Send events using REST API

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:

1. create an API token
2. find the relevant component ID
3. call 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

What is an event source?

An event source represents a tool, such as Bitbucket, GitHub, Jenkins, or ArgoCD—connected to Compass that supplies events to a component's activity feed. Compass uniquely identifies an event source based on externalEventSourceId. We require externalEventSourceId as an input on any request to create events. For example, a Bitbucket repository creates events of multiple types such as build events and deployment events. In this scenario, the externalEventSourceId could be the Bitbucket repository's ID or URL, while the eventType is deployment or build based on the type of event.

Today Compass supports the following event types:

• deployment
• build
• incident
• flag
• alert
• lifecycle
• custom
• push
• pull request

Step 1: Create an API token

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 how to manage API tokens for your Atlassian account

Step 2: Find your component ID

Each event will need to be associated with a component. Learn how to find a component's ID

Step 3: Call the Compass REST API

Here, we’ve used a cURL command as an example to show you how to call the REST API. You can also use another method to call the REST API.

This example sends an event of the custom type to a component's activity feed. 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.

Use cURL command

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.

1
2
curl \
    --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\": \"https://www.example.com\",
                \"lastUpdated\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
                \"externalEventSourceId\": \"$EXTERNAL_EVENT_SOURCE_ID\",
                \"customEventProperties\": {
                    \"id\": \"1\",
                    \"icon\": \"INFO\"
                }
            }
        },
        \"componentId\": \"$COMPONENT_ID\",
    }"

Replace variables in the cURL command

• On line number 3 --url https://example.atlassian.net/gateway/api/compass/v1/events \, replace example with your Compass site's name

• 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 your site. The component ID that you retrieved earlier contains the cloud ID (e.g.: in ari:cloud:compass:00000000-0000-0000-0000-0000:component/1111-1111-1111-1111-111111111111/22222222-2222-2222-2222-2222 the cloud ID value is 00000000-0000-0000-0000-0000). )

• On line number 15 \"lastUpdated\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\", specify the timestamp when the event was sent. You can:

  • leave the line as is, in which case the timestamp is set to the time and date when the cURL command runs
  • replace $(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 day
    • T is the delimiter between the date and the time
    • hh:mm:ss is the time in hours, minutes, and seconds
    • Z represents zero UTC offset
  • An example of the timestamp value in this line is \"timestamp\": \"2022-01-31T01:23:45Z\".

• On line number 16 \"externalEventSourceId\": \"$EXTERNAL_EVENT_SOURCE_ID\", specify the external event source ID. For example:

  • The ID of a repository related to this component (e.g. 123e4567-e89b-12d3-a456-426614174000)
  • The URL of a repository related to this component (e.g. https://bitbucket.org/workspace-name/repository-name)
  • The name of the CI/CD job or pipeline related to this component (e.g. deploy-test-component)

• On line number 23 \"componentId\": \"$COMPONENT_ID\", specify the component ID this event belongs to as you retrieved earlier (e.g.: ari:cloud:compass:00000000-0000-0000-0000-0000:component/1111-1111-1111-1111-111111111111/22222222-2222-2222-2222-2222).

Test the cURL command

Run the cURL command in:

• Terminal on Mac or Linux
• Command Prompt on Windows
  • On a Windows computer, you might need to download cURL and adjust the command’s syntax before running it.

If the command is successful, you’ll see the event on your component’s activity feed in Compass.