Advanced 1: Activities

Overview

Once you begin developing applications on upsun.com, you may find that you want to connect those projects to external services.

Aside from our regular integrations, upsun.com provides you with the ability to write custom scripts that can respond to events on projects and environments.

In this guide, you’ll get a little background on activities, and then have a chance to create your own Activity Script.

Every event that takes place on upsun.com - whether that’s a pushed commit, redeploy, or updated environment variable - is an activity. Every activity on upsun.com has the stages and phases you would expect.

They’re triggered, and then after some pending state while it’s running, it will complete with either success or failure. It’s with this information that we can add webhooks to these states that trigger additional actions in our pipelines.

Activity Scripts

Activity Scripts are JavaScript programs that can be associated with a project.They are a limited form of JavaScript (no modules or objects available, aside from those built-in), but the can still be used to run common actions in response to activities.

Caveats

Unlike most things on upsun.com, Activity Scripts are not committed features. That is to say, the state of an Activity Script that is committed to a repository does not reflect its state on a particular environment tied to a commit.

They are project-level scripts, that are uploadable, updatable, and deletable through the API, CLI, and management console.

An example

Let’s say that I would like to receive Slack notifications from my project when certain events - like a deployment on an environment - completes.

1. First, I would need to create a new webhook that includes the workspace and channel ID for Slack.
2. Then I’d create an environment variable on my project called SLACK_URL with that webhook.

3. Finally the script, which looks like this:

   function getEnvironmentVariables() {
     return activity.payload.deployment.variables.reduce(
       (vars, { name, value }) => ({
         ...vars,
         [name]: value,
       }),
       {}
     );
   }
   
   const ENV_VARIABLES = getEnvironmentVariables();
   
   /**
   * Sends a color-coded formatted message to Slack.
   *
   * You must first configure a Platform.sh variable named "SLACK_URL".
   * That is the group and channel to which the message will be sent.
   *
   * To control what events it will run on, use the --events switch in
   * the Platform.sh CLI.
   *
   * @param {string} title
   *   The title of the message block to send.
   * @param {string} message
   *   The message body to send.
   */
   function sendSlackMessage(title, message) {
     const url = ENV_VARIABLES.SLACK_URL;
   
     if (!url) {
       throw new Error("You must define a SLACK_URL project variable.");
     }
   
     const messageTitle =
       title + (new Date().getDay() === 5) ? " (On a Friday! :calendar:)" : "";
   
     const color = activity.result === "success" ? "#66c000" : "#ff0000";
   
     const body = {
       attachments: [
         {
           title: messageTitle,
           text: message,
           color: color,
         },
       ],
     };
   
     const resp = fetch(url, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
       },
       body: JSON.stringify(body),
     });
   
     if (!resp.ok) {
       console.log("Sending slack message failed: " + resp.body.text());
     }
   }
   
   sendSlackMessage(activity.text, activity.log);
   

   The SLACK_URL variable is retrieved from the activity payload (activity.payload.deployment.variables), and a message of our choosing is sent to the webhook URL on Slack using the built-in fetch module within the sendSlackMessage method.

4. Adding this script to the project through the CLI looks like:

   upsun integration:add --type script --file ./slack_notifier.js --events LIST_OF_EVENTS

   The only thing missing from this command is which events should trigger this script. If we’re only interested in deployments, we’d just use the single value environment.push. Otherwise, we can add more activities to that list separated with a comma.

   This command will upload the script to the project, where it will trigger the Slack notification across all environments. If we instead wanted to exclude certain environments (--exluded-environments=LIST) or only notify on specific environments (environments=LIST) we can do so with flags.

5. When we modify and are trying to debug these scripts, upsun.com places them in their own specified logs that are accessible via the CLI: upsun integration:activities.