Last updated Nov 15, 2024

Send events using REST API

This flow is still supported, but instead you could try out a simpler approach outlined here

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

What is an event source?

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.

Step 1: Set up an event source using the Atlassian platform GraphQL API

The first step is to set up an event source using our GraphQL API. Learn more about the Atlassian platform GraphQL API

Get the cloud ID of your Compass site

You’ll need this cloud ID to make subsequent API calls.

Use this query call to get the cloud ID:

Query

1
2
  query example {
    tenantContexts(hostNames:["your-domain.atlassian.net"]) {
      cloudId
      }
    }

Replace the hostNames input with your Compass site's name and run the query

Create an event source

Use this query to create the event source:

Query

1
2
    mutation 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.
- The combination of externalEventSourceId and eventType uniquely identifies an event source. Learn more about what is an event source
Run the query.
Note the id of the eventSource from the query result.

Connect the event source to a component

When connected, the events sent by the event source appear on the component’s activity feed.

Use this query to connect the event source:

Query

1
2
    mutation 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. To get a component's ID, go to a its Overview page in Compass, select more actions (•••), then select Copy component ID.
Run the query.

Step 2: 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 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.

This API is rate limited. Only 100 requests per user per minute are allowed.

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\"
                }
            }
        }
    }"

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 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. 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 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

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.

Use the cURL command by adding it to your build system or deployment scripts to automatically send events to the activity feed of your component.