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. set up an event source for your component using the Atlassian platform GraphQL API
2. create an API token
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 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

To set up the event source:

1. Get the cloud ID of your Compass site. You’ll need this cloud ID to make subsequent API calls.

   1. Use this query call to get the cloud ID:

      Query

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

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

2. Create an event source.

   1. 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"
        }
      }
      

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

   3. Run the query and note down the id of the eventSource that the query returns.

3. Connect the event source to a component. The connection lets the events you send to the event source appear in the component’s Activity page in Compass.

   1. 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>"
        }
      }
      

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

   3. 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 more managing 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. 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

To call the REST API:

1. Use this cURL command:

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

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

     • remove the line, in which case the timestamp is set to when Compass receives the event
     • 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.

3. Test the cURL command by running it 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. Events other than the 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 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.