Added example and instruction on how to setup CircleCI event handler

Author: vbihun

snippets/scripts/compass-circleci-event-handler/README.md

@@ -0,0 +1,66 @@
+# How to use this
+Copy a script from config-example.yml file to your project's config to get events from your project.
+
+Variables in the example:
+- **component-external-event-source-id** - get link to project CircleCI pipelines that you fill to Projects links in the Compass component (example: https://app.circleci.com/pipelines/github/test/potential-octo-giggle or https://app.circleci.com/pipelines/bitbucket/test/potential-octo-giggle). Copy string from `/pipelines` (example: `github/test/potential-octo-giggle` or `bitbucket/test/potential-octo-giggle`) and change github or bitbucket to gh or bb (example: `gh/test/potentian-octo-giggle` or `bb/test/potential-octo-giggle`). Add the final string to `externalEventSourceId` field in the config file;
+
+- **name-of-your-site** - go to your site and copy the string before .atlassian.net/…. Example: `test-site.atlassian.net/compass` - you should copy only test-site. Add the final string to `name-of-your-site` field in the config file;
+
+- **$USER-EMAIL** - your email of site on Atlassian. Add email to the CircleCI project’s variables. Path to the CircleCI project’s variables: *Projects → Your project’s settings → Environments Variables → Add. Name: USER-EMAIL*; 
+
+- **$TOKEN** - create an API token. Open the link (https://id.atlassian.com/manage-profile/security/api-tokens) and create a token. After that, add the Token to the CircleCI project’s variables. Path to the CircleCI project’s variables: *Projects → Your project’s settings → Environments Variables → Add; Name: TOKEN*;
+
+- **$CLOUD-ID** - to get your `cloudId`, you should click on your avatar and go to the Profile. After loading the page in the URL, you should see at the end of the URL a query parameter - cloudId. Copy the cloudId and add it to the CircleCI project’s variables. Path to the CircleCI project’s variables: *Projects → Your project’s settings → Environments Variables → Add. Name: CLOUD-ID*; 
+
+- **$COMPONENT-ID** - copy component’s id in the component. Click on `…` → `Copy component ID`. Add the Component ID to the CircleCI project’s variables. Path to the CircleCI project’s variables: *Projects → Your project’s settings → Environments Variables → Add; Name: COMPONENT-ID*;
+
+## How to get all CircleCI components
+
+You should use the GraphQL query:
+
+```
+query searchComponents($cloudId: String!, $query: CompassSearchComponentQuery) {
+  compass {
+    searchComponents(cloudId: $cloudId, query: $query) {
+      ... on QueryError {
+        identifier
+        message
+      }
+      ... on CompassSearchComponentConnection {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          component {
+            name
+            id
+            links {
+              name
+              type
+              url
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+and query variables:
+```
+{
+  "cloudId": <your-cloud-id>,
+  "query": {
+    "first": 100,
+    "fieldFilters": [
+      {
+        "name": "linkTypes",
+        "filter": { "eq": "PROJECT" }
+      }
+    ]
+  }
+}
+```
+
+To use this query, go to the link: `https://<your-site-name>.atlassian.net/gateway/api/graphql` and copy-paste the GraphQL query to the query editor and copy-paste variables to the Variables editor in the bottom of the page, and click the Run button. You will see all components with the Projects link type in your site. You can find a component that has a CircleCI link and open a link to set up the config file.

snippets/scripts/compass-circleci-event-handler/config-example.yml

@@ -0,0 +1,83 @@
+jobs:
+  build:
+    docker:
+      - image: <your-image>
+    steps:
+      - checkout
+
+      # Notify Compass on success
+      - run:
+          name: Notify Compass (SUCCESSFUL)
+          when: on_success
+          command: |
+            curl \
+              --request POST \
+              --url "https://<name-of-your-site>.atlassian.net/gateway/api/compass/v1/events" \
+              --user "$USER-EMAIL:$TOKEN" \
+              --header "Accept: application/json" \
+              --header "Content-Type: application/json" \
+              --data "{
+                \"cloudId\": \"$SITE-CLOUD-ID\",
+                \"componentId\": \"$COMPONENT-ID\",
+                \"event\": {
+                  \"build\": {
+                    \"displayName\": \"Build #$CIRCLE_BUILD_NUM on $CIRCLE_BRANCH\",
+                    \"description\": \"CircleCI build succeed\",
+                    \"url\": \"$CIRCLE_BUILD_URL\",
+                    \"lastUpdated\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
+                    \"externalEventSourceId\": \"<component-external-event-source-id>\",
+                    \"updateSequenceNumber\": $CIRCLE_BUILD_NUM,
+                    \"buildProperties\": {
+                      \"state\": \"SUCCESSFUL\",
+                      \"startedAt\": \"$(date -u -d @$CIRCLE_WORKFLOW_STARTED_AT +'%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || date -u +'%Y-%m-%dT%H:%M:%SZ')\",
+                      \"completedAt\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
+                      \"pipeline\": {
+                        \"pipelineId\": \"$CIRCLE_WORKFLOW_ID\",
+                        \"url\": \"$CIRCLE_BUILD_URL\",
+                        \"displayName\": \"Workflow $CIRCLE_WORKFLOW_ID\"
+                      }
+                    }
+                  }
+                }
+              }"
+
+      # Notify Compass on failure
+      - run:
+          name: Notify Compass (FAILED)
+          when: on_fail
+          command: |
+            curl \
+              --request POST \
+              --url "https://<name-of-your-site>.atlassian.net/gateway/api/compass/v1/events" \
+              --user "$USER-EMAIL:$TOKEN" \
+              --header "Accept: application/json" \
+              --header "Content-Type: application/json" \
+              --data "{
+                \"cloudId\": \"$CLOUD-ID\",
+                \"componentId\": \"$COMPONENT-ID\",
+                \"event\": {
+                  \"build\": {
+                    \"displayName\": \"Build #$CIRCLE_BUILD_NUM on $CIRCLE_BRANCH\",
+                    \"description\": \"CircleCI build failed\",
+                    \"url\": \"$CIRCLE_BUILD_URL\",
+                    \"lastUpdated\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
+                    \"updateSequenceNumber\": $CIRCLE_BUILD_NUM,
+                    \"externalEventSourceId\": \"<component-external-event-source-id>\",
+                    \"buildProperties\": {
+                      \"state\": \"FAILED\",
+                      \"startedAt\": \"$(date -u -d @$CIRCLE_WORKFLOW_STARTED_AT +'%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || date -u +'%Y-%m-%dT%H:%M:%SZ')\",
+                      \"completedAt\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
+                      \"pipeline\": {
+                        \"pipelineId\": \"$CIRCLE_WORKFLOW_ID\",
+                        \"url\": \"$CIRCLE_BUILD_URL\",
+                        \"displayName\": \"Workflow $CIRCLE_WORKFLOW_ID\"
+                      }
+                    }
+                  }
+                }
+              }"
+
+workflows:
+  build_workflow:
+    jobs:
+      - build