Create an incident

1Set up Slack CLI

Use the new Slack CLI to create and deploy Slack apps. With the Slack CLI, developers can create an app and generate some boilerplate code in seconds.

This section walks through setting up your environment for next gen platform development.

  • Install the Slack CLI

    We've built a command line interface to make the process of creating new apps, running them, and deploying them easier. Binaries are available for macOS and Windows.

    Deno is currently a pre-requisite for using the CLI — if you do not have Deno installed, please do so first.

    Additionally, the experience of writing an app will be greatly enhanced if your IDE includes support for Deno. Here's a plugin to add Deno capabilities to VS Code.

    To install the Slack CLI:

    1. Download the latest binary for your platform
    2. Decompress the downloaded file. On macOS, copy the slack binary to a destination in your path (we recommend /usr/local/bin). For Windows, copy the .exe file into any location accessible in your path.
    3. Test the app is properly installed by running slack version and verifying the version matches the one you downloaded.

    Now you can now use the Slack CLI to authenticate and create a new app.

  • Authenticate the Slack CLI

    Before you can create an app, you must authenticate.

    1. Run slack login — this will display some instruction text and a string to copy and paste in any channel in the test workspace.

          /hermesauthticket ABC123DEF...XYZ
      
    2. Copy the entire string, including the leading /, and paste it into any channel in your Slack workspace. (You are essentially calling a special slash command that will authenticate your app with Slack).

    3. Run slack auth info for details on your active workspace authorization.

    Now that you've authenticated, you can create a new app.

  • Create a new app

    Now you can create an app! cd to a directory where you have write access and want your app to live, most likely in your home. Then, run

    $ slack create [optional-project-name]
    

    This will create a new project called with a random name like priceless-lemur-123.

    If you want to name your project something specific, include an additional parameter

    $ slack create my-new-project
    

    Once the app has finished running, you'll have a new directory that contains a skeleton app.

    $ cd my-new-project
    

    The structure of these next-generation apps aims to favor convention over configuration. Directories are named logically and the files within those directories map to specific functionality with an app. For example, the functions directory contains a list of an app's functions, with a single file for each function an app defines.

2Understand how apps are structured and setup your application as a incident management system

This section walks you through the structure of your app and how the different pieces tie together.

We will then define a function invoked by a Slack trigger that creates a new incident channel, and sends a message with important incident data.

  • Understand how the app is structured

    Your new project has a directory structure that should resemble the following:

    .slack/
      - apps.json
      - cli.json
    assets/
      - icon.png
    functions/
     - myfunction.ts
    tables/
     - mytable.ts
    triggers/
     - mytrigger.ts
    workflows/
     - myworkflow.ts
    import_map.json
    project.ts
    README.md
    

    Functions: Modular, reusable, atomic blocks of functionality that can be grouped together as workflows. A function defines inputs, performs some useful bit of work using those inputs, and responds with pre-defined outputs. You'll be able to quickly write custom functions, deploy them via the CLI, and building workflows using these functions. Check out our functions documentation to learn more.

    Workflows: A workflow is a group of functions, including built-in functions provided by Slack. Check out our workflows documentation to learn more.

    Triggers: Define how workflows are called, such as a message action, shortcut, or event, where it is able to be executed, and who can execute it. Check out our triggers documentation to learn more.

    Tables: Define tables and store data to power your application. Check out our tables documentation to learn more.

    Project.ts: Contains all of the metadata about a project, such as the name of project, description, and requested OAuth scopes. It also contains a list of defined functions, tables, triggers and workflows.

  • Adding a new function to your app

    A function is defined via the DefineFunction method, which is part of the SDK that gets included with every newly created project. The function is exported so that it can be used elsewhere in your app (such as workflows). DefineFunction accepts a name (as a string) and object that defines the input and output parameters as well as an anonymous, asynchronous function that performs that actual work of the function (i.e. taking the input, doing something like calling an API, and then providing an output via a promise).

    Let's create a function that creates an incident. The incident will accept a name, severity, and description, and will populate a random ID:

    1. Create a create_incident.ts file under the functions/ directory of your project.
    2. Copy and paste the following code into it:
    import { DefineFunction, Schema } from "slack-cloud-sdk/mod.ts";
    export const CreateIncident = DefineFunction(
      "create_incident",
      {
        title: "Create Incident",
        description: "Creates an incident",
        input_parameters: {
          slug: {
            type: Schema.types.string,
            description: "Incident Name / Title",
          },
          description: {
            type: Schema.types.string,
            description: "Short Description of Incident",
          },
          severity: {
            type: Schema.types.string,
            description: "Incident Impact / Severity",
          },
        },
        output_parameters: {
          id: {
            type: Schema.types.integer,
            description: "Incident ID",
          },
        },
      },
      async (ctx) => {
        console.log(
          `New incident created: ${ctx.inputs.severity}: ${ctx.inputs.slug} | ${ctx.inputs.description}`,
        );
        const incidentId = Math.floor(Math.random() * 222222);
        return await {
          completed: true,
          outputs: { id: incidentId },
        };
      },
    );
    
    
    1. Now we need to import and reference the function we just created in the project metadata file, located at project.ts in the project root:
      1. Import your new function at the top of your project.ts file:

        import { CreateIncident } from "./functions/create_incident.ts";

      2. Make sure CreateIncident is referenced in the functions array of your Project definition, so the relevant section of your project.ts file looks like the following:

        functions: [CreateIncident],

  • Adding a new workflow to your app

    Now that we have defined the CreateIncident function, we will create a Workflow that utilizes it.

    In this section, we will create a Workflow that invokes our new function, then take its output and uses a built-in Slack function to create a new channel. Finally, the Workflow will post a message about the incident in the new channel it just built.

    1. Create a new_incident.ts file under the workflows/ directory of your project.
    2. Copy and paste the following code into it:
    import { DefineWorkflow, Schema } from "slack-cloud-sdk/mod.ts";
    import { CreateIncident } from "../functions/create_incident.ts";
    
    export const NewIncidentWorkflow = DefineWorkflow("new_incident", {
      title: "New Incident",
      description:
        "Generates a new incident, creates a channel, posts a message to channel",
      input_parameters: {
        slug: {
          type: Schema.types.string,
          description: "Incident Name / Slug",
        },
        description: {
          type: Schema.types.string,
          description: "Incident Description",
        },
        severity: {
          type: Schema.types.string,
          description: "Incident Severity",
        },
      },
    });
    
    const step1 = NewIncidentWorkflow.addStep(CreateIncident, {
      slug: NewIncidentWorkflow.inputs.slug,
      description: NewIncidentWorkflow.inputs.description,
      severity: NewIncidentWorkflow.inputs.severity,
    });
    const step2 = NewIncidentWorkflow.addStep(
      Schema.slack.functions.CreateChannel,
      {
        channel_name: NewIncidentWorkflow.inputs.slug,
        is_private: false,
      },
    );
    NewIncidentWorkflow.addStep(Schema.slack.functions.SendMessage, {
      channel_id: step2.outputs.channel_id,
      message:
        `There is an incident: ${step1.outputs.id} ${NewIncidentWorkflow.inputs.description}`,
    });
    
    
    1. Now we need to import and reference the workflow we just created in the project metadata file, located at project.ts in the project root:
      1. Import your new workflow at the top of your project.ts file:

        import { NewIncidentWorkflow } from "./workflows/new_incident.ts";

      2. Make sure NewIncidentWorkflow is referenced in the workflows array of your Project definition, so the relevant section of your project.ts file looks like the following:

        workflows: [NewIncidentWorkflow],

  • Adding a new trigger to your app

    With our Workflow defined, we can now create a Trigger to invoke it. There are many different kinds of triggers, but for our purposes we will use a Shortcut trigger. This Shortcut will be how users in your Slack workspace interact with this app.

    Let's create a incident creation trigger that, when invoked, executes NewIncidentWorkflow.

    1. Create a new_incident_shortcut.ts file under the triggers/ directory of your project.
    2. Copy and paste the following code into it:
    import { DefineTrigger, TriggerTypes } from "slack-cloud-sdk/mod.ts";
    import { NewIncidentWorkflow } from "../workflows/new_incident.ts";
    
    export const NewIncidentShortcut = DefineTrigger(
      "new_incident_shortcut",
      {
        type: TriggerTypes.Shortcut,
        name: "newincident",
        description: "Creates a new incident",
      },
    ).runs(NewIncidentWorkflow);
    
    1. Now we need to import and reference the trigger we just created in the project metadata file, located at project.ts in the project root:
      1. Import your new trigger at the top of your project.ts file:

        import { NewIncidentShortcut } from "./triggers/new_incident_shortcut.ts";

      2. Make sure NewIncidentShortcut is referenced in the triggers array of your Project definition, so the relevant section of your project.ts file looks like the following:

        triggers: [NewIncidentShortcut],

3Review project triggers, workflows, and functions before a widespread deploy

Before deploying your Incident Management changes to an entire instance, let's confirm that your project.ts is configured appropriately.

  • Review project.ts

    Let's take a quick minute to review our project.ts file to confirm everything looks right.

    import { Project } from "slack-cloud-sdk/mod.ts";
    import { CreateIncident } from "./functions/create_incident.ts";
    import { NewIncidentWorkflow } from "./workflows/new_incident.ts";
    import { NewIncidentShortcut } from "./triggers/new_incident_shortcut.ts";
    
    Project({
      name: "Incident Tutorial App",
      description:
        "An app for incident management. Create new incidents, spin up new channels, and post incident details for engineering teams to assemble.",
      icon: "assets/icon.png",
      runtime: "deno1.x",
      botScopes: ["commands", "chat:write", "chat:write.public", "groups:write"],
      functions: [CreateIncident],
      workflows: [NewIncidentWorkflow],
      triggers: [NewIncidentShortcut],
      tables: [],
      outgoingDomains: [],
    });
    
    

    You should now be able to run the app locally with slack run or deploy it to the hosting infrastructure provided by Slack via slack deploy.

    This concludes the setting up the app!

4App release and future considerations

This section will highlight the user experience, deploying to your instance, and future considerations and improvements.

  • Launching an incident and deploying your app

    Now that you've created a function, workflow, and a trigger within your project, you can deploy your application to your Slack instance. This is as easy as running slack deploy.

    Once a user invokes your application via the /newincident Shortcut, they will be prompted to enter a slug, description, and severity in a Workflow modal. With that information, a new channel will be created with a name based on the provided slug, and a message with severity and description details will be posted to the channel using a Slack built-in function. You can then add users to the channel to manage and resolve the incident.

  • Future considerations and next steps

    Now that you've created a baseline incidement reporting app, let's talk about next steps. As mentioned previously, the Slack built-in functions offer out of the box functionality that can enhance user experience.

    You might consider the following for a more robust incident management integration:

    • Adding on-call engineers to a recently created incident channel individually Schema.slack.functions.invite_user_to_channel or by using Schema.slack.functions.create_usergroup
    • Creating additional trigger functions that allow incidents to be created via TriggerType.Shortcut, TriggerType.MessageShortcut, or TriggerType.Events
    • Update channel topics to indicate the status of an active or inactive incident via Schema.slack.functions.update_channel_topic
    • Archive channels that represent incidents that have been fully resolved: Schema.slack.functions.archive_channel

Was this page helpful?