Quickstart Guide

copied

We’ll walk you through the following steps to get started using Nimbella Commander to create your own custom app and commands in Slack, then give you a number of commonly used Commander commands.

What you need

copied

To do the tutorial and eventual create your own apps, you need a Slack workspace, free or premium. You must be the workspace owner or an administrator to create and install a Slack app.

Install Commander

copied

When it is released to the public, Commander will be a Slack app you can install from the Slack App Directory.

For now, follow these instructions to install Commander manually. The link will open in a new tab.

Test the installation of the Commander app

copied

In any channel of your Slack workspace, enter the command /nc  and press the Return key. If the app is installed correctly, you will see a response from the Commander app showing the version number.

Tutorial: Create and install a Slack app and a command prefix

copied

Now we’ll create a custom Slack app, which involves the following tasks:

  1. Create a Slack app for the DevOps team. The app could eventually contain a number of slash commands to accomplish tasks that DevOps normally performs.
  2. Create a slash command called /devops. We’ll create a slash command in the DevOps app that will serve as a command prefix when you run commands in Slack.
  3. Install the app into Slack.
  4. Connect the app to Commander.
  5. Create a print command that can be used for various notifications. Commands for your custom app are created in Slack using Commander slash commands.

1 Create a Slack App for DevOps

copied

Make sure you’re logged into your Slack workspace before starting.

  1. Go to https://api.slack.com/apps.
  2. Click Create New App.

    Create 1

  3. In the Create a Slack App panel, enter the following information. a. For AppName, enter DevOps. b. For Development Slack Workspace, choose your workspace.

    Create 2

  4. Click Create App to close the panel and create the app. This returns you to the Basic Information page.

2 Create a /devops Slash Command Prefix

copied

Assuming you’ll have a number of apps with various slash commands, it can get difficult to keep them all straight, and Slack doesn’t have a formal namespace built into their commands. We’ll create a slash command in the DevOps app that will serve as the command prefix for all the commands that we create for that app.

  1. On the Basic Information page, click Slash Commands.

    Create 3

  2. Click Create New Command.

    Create 4

  3. On the Create New Command page, enter the following information: a. For Command, enter /devops . b. For Request URL, enter https://nimbella.com. We’ll go back and change this URL after we get the correct one for this command. c. For Short Description, enter DevOps command prefix. d. Select the checkbox for Escape channels, users, and links sent to your app.

    Create 5

  4. In the Preview section, check your entries. As shown in this screenshot, the preview shows the information you entered and the slash command as it will be typed into Slack. Preview of Autocomplete Entry

  5. Click Save.

This returns you to the Slash Commands page.

3 Install the app

copied

  1. In the left sidebar menu, in the Settings section click Install App.
  2. Click Install App to Workspace.

    Create 6

  3. Accept the default permissions and click Allow. Create 7a If the app is installed successfully, you’ll see a screen with the OAuth access token.

    Create 7b

4 Connect the App to Commander

copied

We’ll use the Commander app’s /nc  command to add our DevOps app to Commander.

First, let’s talk about the syntax of the Nimbella Commander app-add  command that’s used to add an app to Commander:

Commander User
User 6:06 PM
/nc app_add <app-name> /<command-prefix> 

The parameters in this command are:

  • <app-name>  This will be the lower-case version of our app name, in this case devops
  • <command-prefix>  The command prefix that we created in the last task.

To connect the DevOps app to Commander:

  1. In Slack, run the following command:

    Commander User
    User 6:06 PM
    /nc app_add devops /devops 

    You should see a Commander response that looks something like this:

    Commander Admin
    Commander App 6:06 PM

    The devops app has been added. Please attach this Request URL to the /devops command in Slack: https://apigcp.nimbella.io/api/v1/web/grave-fermi-s1djh2-0ygaml/app_138/router

  2. Copy the URL that appears in the response.

  3. Go to https://api.slack.com/apps.
  4. In the App Name list, select the DevOps app.

    Connect 1

  5. Click Add features and functionality.

    Connect 2

  6. In the Features section in the left sidebar, click Slash Commands.

    Connect 3

  7. Click the Edit icon to the right of the /devops  command.

    Connect 4

  8. Replace the Request URL with the one that you copied.

    Connect 5

  9. Click Save.

The/devops  slash command (which will serve as the command prefix) is now connected to Commander. From now on, you’ll use Commander’s /nc  slash commands to create commands for the DevOps app, as we’ll do in the next section.

5 Create a Print Command

copied

Now we’re ready to create our first command in our DevOps app. We’ll use Commander right in Slack to create a print  command, with a parameter that we can then use for various types of notifications in our DevOps app. We’ll use this command in our GitHub example in the Triggers section to notify us that something has changed in our GitHub repository.

  1. In Slack, enter the following slash command exactly as it appears here, including the angle brackets:

    Commander User
    User 6:06 PM
    /nc command_create print <msg> 

    You’ll see a response similar to the following:

    Commander Admin
    Commander App 6:06 PM

    Created command print <msg>, edit the code

  2. Click the link to edit the Commander code for the command.

  3. Find this line in the source code:
    text: JSON.stringify({text, secrets, params}, null, 2)
    Change the line to this:
    text: msg
  4. Click Save.
  5. In Slack, test the command by entering the command prefix (devops ), followed by the command (print ), followed by a text string for the msg  parameter

    Commander User
    User 6:06 PM
    /devops print Howdy! 

    If your print  message has more than one word, surround it with single or double quotes or else you’ll get a response that a parameter was not found. You should see the Slack response shown in this screenshot, coming from your custom app and displaying the print message.

    Howdy

Note that we created the command with an/nc  slash command, but we ran the command in in our DevOps app with our /devops  command prefix.

Next steps for your app

copied

There are a number of other ways to use Commander to enhance your custom app. We’ll step through the possibilities, with links to the Commander Developer Guide.

Manage user roles and user groups to control who can administer the app, code individual commands, and run the custom app’s commands in Slack.

Create a task to execute a command at scheduled times.

Create a trigger to execute a command when called by an external webhook.

Create encrypted parameter values for sensitive information by creating secrets.

Create command sets to group commands, and export them to make them externally available with their source code.

View logs for apps, commands, and users.

Here’s something you do NOT have to do: secure your app. The signatures of incoming requests from Slack users issuing Slack commands are verified to ensure they are coming from Slack. Tasks and triggers are secured automatically by symmetric secret keys. See the Security section in the Developer Guide.