Developer Guide

copied

Slack Apps

copied

Slack allows the use of custom Slack apps, which are accessed in Slack by means of Slash Commands. When a user types a specific slash command like /times , it sends a message to a public URL. The request includes the command and any additional text following the command. Slack calls the public URL a Request URL.

Custom Slack apps and slash commands are created using Slack's web interface at api.slack.com and linked to your custom code by means of the Request URL. The custom app is set up at a server that listens for requests at the Request URL. It responds to the request and the response appears in the Slack channel in which the command was typed.

Slack apps with Nimbella Commander

copied

Commander provides a full development and runtime environment for developing custom Slack apps. There are a number of advantages to using Commander to develop, host, and maintain your custom apps.

You don’t need your own server

Commander lets you host and run Slack apps in the Nimbella Cloud, so you don’t have to deploy your own server. After you create a listing for your custom app on the Slack API apps page, you create one slash command and point the slash command’s Request URL to a Commander URL. Your app’s custom code lives in the Nimbella cloud, and Nimbella servers respond to slash commands developed for your app.

The slash command you create for your custom app at the Slack API site serves as a command prefix for your app’s commands. When users run commands for the app, they always begin with this prefix. For example, if you have a custom app called DevOps with a command prefix of /devops , then your app responds to any slash commands that have the form /devops <command> .

Selective listening

Most custom Slack apps function as bots, listening to all messages in a public channel and responding to direct requests. The apps you create with Commander don't read messages in channels. They only respond to slash commands with the appropriate command prefix. This means you don't have to worry about your custom Slack app reading messages in your public or private channels.

Create custom commands and administer your app right in Slack

After you install the Commander app in Slack, you can create custom slash commands and administer your custom app from the Slack interface. See the tutorial in the Quickstart Guide for an example of creating a custom slash command in the Slack UI.

Easy to code

Commands are written in JavaScript, and premium versions of Commander allow other options such as the Node.js runtime. This means custom apps can be developed by app developers or even DevOps staff who know shell scripting.

Advanced features

  • Administrators assign user roles to control who can administer your custom app, who can write code for the commands, and who can run the slash commands.
  • You can set up recurring tasks and triggers that run commands without user input.
  • You can create encrypted parameter values, called secrets, which keep sensitive information from being viewed by users or being stored in Slack’s history.
  • You can import and export command sets to either use someone else’s code or share your own.

Security

There's nothing you need to do to secure your app. The signatures of incoming requests from Slack users issuing Slack commands are verified to ensure they are coming from Slack. See Security.

Ready to get started?

copied

Check out the Commander Overview and then use the Quickstart Guide to get your first app installed in Commander. Then follow this Developer Guide to understand where to go from there. Once you’re proficient, you’ll be able to look up commands in the Commander Reference Guide if you need a quick reminder.

About commands

copied

The Commander app for Slack lets you control nearly all of the administrative functions for your custom app directly in the Slack interface by running slash commands with the command prefix /nc . The entire set of Commander commands is listed in the Reference Guide. This Developer Guide also contains many examples of these commands, grouped by administrative function.

Note: You must have the Commander app installed in Slack to use these commands. See the Quickstart Guide for instructions on how to install the Commander app.

The current app

copied

Commander /nc  slash commands rely on the concept of a current app. When you add a custom Slack app to Commander with the app_add command, that app becomes your current app. If you only have one custom app that uses Commander, that app is always your current app.

If you have multiple custom Slack apps in your workspace, you can use the app_current command to verify which app is being treated as the current app or make another app the current one.

Show the current app:

Commander User
User 6:06 PM
/nc app_current 
Commander Admin
Commander App 6:06 PM

Your current app is devops

Switch to the accounting app:

Commander User
User 6:06 PM
/nc app_current accounting 

Command Parameters

copied

Commands support a variety of parameter definitions and Commander automatically parses parameters so they can be accessed easily in your source code.

When you create a command, you specify the parameters the command takes by enclosing parameter names in angle brackets. For example, the following command_create command creates a command for your custom app that will take two parameters:

Commander User
User 6:06 PM
/nc command_create add_host <hostname> <ip_addr> 

In the code for the command, you can access the command's parameters by name using params:

if (params.hostname == 'a.nimbella.com') {

But also, the default generated command source code creates local variables as a convenience:

 const {
    Hostname,
    Ip_addr
  } = params;

This means you can access the parameters by name in a function without params:

if (hostname == 'a.nimbella.com') {

When a user runs this command in Slack, they add parameter values as in the following example (assuming the command prefix for the custom app is /devops ):

Commander User
User 6:06 PM
/devops add_host a.com 100.200.3.4 

If you’re working on a command and discover you want to change the command's parameters, you can change them with the command_params command. For example, if you wanted to add a TTL parameter to the add_host command you created above:

Commander User
User 6:06 PM
/nc command_params add_host <hostname> <ip_addr> <ttl> 

Note: If you use /nc command_params to create new parameters, the command source code is not regenerated, so to access those parameters directly by name without using params , you'll need to add them to the list of local variables in the code first.

Parameter values with white space

When a command is run in your custom app, parameter values that include white space should be enclosed in a pair of either double or single quotes. For example, if you have a print  command with a <msg>  parameter, the value could be:

Commander User
User 6:06 PM
/devops print "This parameter has multiple words" 

This command passes the value This parameter has multiple words  to the command source. If you want to pass a parameter value that includes the double quotes, use single quotes to enclose the string, such as:

Commander User
User 6:06 PM
/devops print ‘“Life is what happens when you're busy making other plans.” - John Lennon’ 

Note: On Apple computers (and potentially others), double quotes appear entered as either Unicode left or right double quotes. If the string starts with a Unicode left quote, a Unicode right quote will be expected to end it.

Optional command parameter

A list of parameters can end with one optional parameter in square brackets, such as the [<ttl>]  parameter in this example:

Commander User
User 6:06 PM
/nc command_create add_host <hostname> <ip_addr> [<ttl>] 

This command can be run with either the first two parameters or all three, so either of these commands is valid:

Commander User
User 6:06 PM
/devops add_host a.nimbella.com 1.2.3.4 
Commander User
User 6:06 PM
/devops add_host a.nimbella.com 1.2.3.4 300 

Parameter options

The parameter definition for a command can also include options. Options are preceded with a hyphen (-). Options can be either be flags or named options. Here's an example that contains a flag option -detail  and a named option -ttl  with value ttl_value :

Commander User
User 6:06 PM
/nc command_create add_host <hostname> <ip_addr> [-detail] [-ttl <ttl_value>] 

In the source code for the command, you can check to see if a flag option is present either by using the params variable:

if (params.detail) {

or by its name alone, because the default generated code creates a local variable with the name of the option:

if (detail) {

Similarly, you can check if a named option exists by its name alone and check its value using the name of the value:

if (ttl && ttl_value == 30) {

The add_host  command created above with the -detail  and -ttl  options can be run in any of the following ways:

Commander User
User 6:06 PM
/devops add_host a.com 1.2.3.4 
Commander User
User 6:06 PM
/devops add_host a.com 1.2.3.4 -detail 
Commander User
User 6:06 PM
/devops add_host a.com 1.2.3.4 -ttl 90 -detail 

Note:

  • Options may not be used when an optional command parameter is present.
  • When options are specified, they must be specified at the end of the parameter definition.

Variable number of arguments

Command parameter definitions support varargs , a variable number of arguments. A parameter definition for a command with varargs  ends with the ellipsis notation (…). The following example specifies that the add_host  command can take any number of parameters:

Commander User
User 6:06 PM
/nc command_create add_host ... 

When varargs  is used, you must code the command parameters to be parsed. In the command source code, the text of the full command, including the command prefix and all parameters, is available in commandText :

let parts = commandText.split(" ");
let cmdPrefix = parts[0];
let cmd = parts[1];

Note: If you use varargs , your parameter definition cannot include any optional command parameters or parameter options.

Create/manage custom apps

copied

Add a custom app and its command prefix to Slack

copied

Use app_add to add a custom app to Commander. Before running this command, you must have created the app and a slash command that will represent the command prefix at api.slack.com/apps. See the Quickstart Guide for a tutorial that includes this command.

  • Add a custom app called devops and a /devops command prefix to Commander:

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

List all apps connected to Commander

copied

Use the app_list command.

  • List all the apps in your Slack workspace that are connected to Commander:

    Commander User
    User 6:06 PM
    /nc app_list 

Create/manage commands

copied

Create a command for your custom app

Use command_create to create custom slash commands for the current app. Put parameters to be created in angle brackets.

  • Create an add_host  command with parameters for hostname and IP address:

    Commander User
    User 6:06 PM
    /nc command_create add_host <hostname> <ip_addr> 

    Outputs a link to the Nimbella Cloud command source code, which you edit.

If you lose this link or want to go back to it later, use the command_code command.

See the tutorial in the Quickstart Guide for a detailed example of creating the command in Slack and following the link to add code.

Retrieve the source code link for a command

Use command_code to retrieve the link to the source code for a command you’ve already created. A link is generated that will work for 24 hours.

  • Retrieve the code link for the add_host  command:
    Commander User
    User 6:06 PM
    /nc command_code add_host 

List all commands in the current app

Use command_list.

  • List all of the commands in the current app:
    Commander User
    User 6:06 PM
    /nc command_list 

Info about a command

Use command_info to get the following information about an individual command:

  • When it was created
  • Who created it
  • When the source was last modified
  • Who modified the source

This information appears in the command output.

  • Get information about the add_host  command:
    Commander User
    User 6:06 PM
    /nc command_info add_host 

View or set a command’s short description

Commands have a short description that describes what they are or what they do. Use command_desc to view or create the short description. If you’re adding a description that has white space, enclose the value in single or double quotes.

  • View the short description of the add_host  command:
    Commander User
    User 6:06 PM
    /nc command_desc add_host 
  • Set the short description of the add_host  command:
    Commander User
    User 6:06 PM
    /nc command_desc add_host "Adds a hostname" 

Call a webhook for a command

Commander automatically executes the source code for a command when it is run in Slack. If you don't want the command to automatically run its source code, you can set it to call a webhook instead with command_webhook. When a webhook is set up for a command, the associated webhook URL will be contacted and its result returned to Slack instead of running the command's source code.

Tip: A command webhook can be useful when developing code. Use a webhook relay to proxy a command to your local development machine to develop and debug the command source code locally. After setting up a webhook relay to your local machine, you can run a Node server locally that will execute the command when it is run in Slack.

You can revert to executing the source code for the command by first clearing the webhook, then using retrieve the link to the code editor to save the command code.

  • Turn off the add_host  command webhook:
    Commander User
    User 6:06 PM
    /nc command_webhook add_host clear 
  • Retrieve the link to the code editor to save the add_host  source code and return to running the command normally:
    Commander User
    User 6:06 PM
    /nc command_code add_host 

If you need to, you can use command_log to get the log history of the command to see who ran the command at what times and also the time it took the command to execute. See the Logs section for more information.

  • Get the log history of the add_host command:
    Commander User
    User 6:06 PM
    /nc command_log add_host 

Delete a command

Use command_delete plus the command name.

  • Delete the add_host  command:
    Commander User
    User 6:06 PM
    /nc command_delete add_host 

Add npm packages for a command

copied

If your command source code is written in JavaScript and your command requires additional npm (Node Package Manager) packages to run, you can install them in your JavaScript source code with this function, which accepts an array of npm packages to install:

async function install(pkgs) {
  pkgs = pkgs.join(' ');
  return new Promise((resolve, reject) => {
    const { exec } = require('child_process');
    exec(`npm install ${pkgs}`, (err, stdout, stderr) => {
      if (err) reject(err);
      else resolve();
    });
  });
}

The following example shows the install()  function being used to install two npm packages:

let packages = [ 'read-installed', 'chalk' ];
await install(packages);

After installing the npm packages, they can be used as they normally would with require() . This example shows the read-installed package being used:

var readInstalled = require('read-installed');
readInstalled("/", { depth: 0, dev: true }, function(err, map) { … })

Note: The installation of npm packages takes a little time, so commands that install packages will start up slower than those that do not.

To speed up subsequent runs of a command function that installs packages, the package references returned from the require()  statement can be moved into global variables in the command source code and the packages are only loaded if those values are undefined. This method will cause the packages to be installed the first time the command is executed. Note thah they do not need to be installed if the same execution environment is used again by the underling serverless platform. When serverless function environments are reused in a serverless platform, the globals can maintain their previous values.

For example, if the readInstalled  variable above was global, the code could look like this:

var readInstalled;
function _command(...) {
  if (!readInstalled) {
    let packages = [ 'read-installed', 'chalk' ];
    await install(packages);
    readInstalled = require('read-installed');
  }
}

The first time the code is executed, readInstalled  is undefined and the packages loaded. If the environment is reused later by the underlying serverless platform, the readInstalled  value can be used without installing the packages.

Create/manage user roles/groups

copied

There are three user roles, described in detail in the following sections:

About user roles

copied

For examples of assigning these user roles, see Commands to manage users and user groups.

Admin

In Commander, every custom Slack app starts with one administrative user: the Slack user who initially adds the custom app to Commander. It’s up to that admin to assign other Slack users as admins for that app. Admins in turn can assign users as coders for specific commands in the app and as runners of specific commands in the app.

Admins can also create user groups to make it easier to set coder and runner roles for multiple users. See the command examples below.

Admins have no restrictions on what they can do when it comes to an app. Only admin users can create commands, assign roles to other users, and perform other administrative tasks. Admins can do anything that coders and runners can do.

Coder

The coder role is associated with specific commands. A Slack user with a coder role for a command is allowed to edit the source code for the command and also run the command. App admins manage the list of coders for commands. Coders are automatically runners for the commands they can edit.

Runner

The runner role is associated with specific commands ii the custom app. A Slack user with a runner role for a command is allowed to run that command. They cannot run commands in the Commander app.

About user groups

copied

Instead of assigning Coder and Runner roles to individual users, admins can combine users into user groups to make it easier to set coder and runner roles for multiple users. The entire user group can then be added or removed as coders or runners for a command.

Commands to manage users and user groups

copied

Manage admin users

Use the app_admins command to list, add, or remove Slack users as admins for the current app. A plus (+) in front of a user name adds the user to the list and a minus (-) removes a user from the list.

Note: There must be a space between the plus (+) and minus (-) signs and the user to be added or removed as admins for the current app.

  • List the users who are admins for the current app:
    Commander User
    User 6:06 PM
    /nc app_admins 
    Commander Admin
    Commander App 6:06 PM

    devops admins: Sam, Jill

  • Add Bill and Mary and remove Larry as admins for the current app:
    Commander User
    User 6:06 PM
    /nc app_admins + @Bill + @Mary - @Larry 

Manage coder users

Use command_coders to list, add, or remove users as coders for particular commands.

  • View the current list of coders for the add_host command:
    Commander User
    User 6:06 PM
    /nc command_coders add_host 
  • Add Jim and Bob and remove John as coders for the print command:
    Commander User
    User 6:06 PM
    /nc command_coders print + @Jim + @Bob - @John 

Manage users who run commands

Use command_runners to list, add, or remove users as runners for particular custom commands.

  • Add Joe and Sue and remove John as runners for the print command:
    Commander User
    User 6:06 PM
    /nc command_runners print + @Joe + @Sue - @John 

Allow anyone to run a custom command

There is a special user group that always exists called anyone , which includes every Slack user. If you want to allow a command to be run by anyone , you can add the anyone group to the list of command runners:

  • Let anyone run the print command:
    Commander User
    User 6:06 PM
    /nc command_runners print + anyone 

Create user groups

Use group_create to create a user group.

  • Create a user group called devgroup1:
    Commander User
    User 6:06 PM
    /nc group_create devgroup1 

List, add, or remove members of a user group

Use the group_members command.

  • Add Sue to devgroup1:
    Commander User
    User 6:06 PM
    /nc group_members devgroup1 + @Sue 
  • Add Jim, Bob, and John and remove Sue from devgroup1:
    Commander User
    User 6:06 PM
    /nc group_members devgroup1 + @Jim + @Bob + John - @Sue 
  • List the members of devgroup1:
    Commander User
    User 6:06 PM
    /nc group_members devgroup1 
    Commander Admin
    Commander App 6:06 PM

    devgroup1 members: Jim, Bob, John

List all user groups

Use the group_list command.

  • List all user groups for the current app.
    Commander User
    User 6:06 PM
    /nc group_list 
    Commander Admin
    Commander App 6:06 PM

    devgroup1

Delete a user group

Use the group_delete command to delete a user group. Only the named group of users is deleted, the command does not affect the Slack users themselves in any way.

  • Delete the user group devgroup1:
    Commander User
    User 6:06 PM
    /nc group_delete devgroup1 

Add a user group to a command

We gave examples of using command_coders and command_runners to add users as coders and runners respectively. Here are two examples of adding a user group instead.

  • Add the user group devgroup1 as coders for the print command:

    Commander User
    User 6:06 PM
    /nc command_coders print + devgroup1 
  • Add the user group bookkeeping as runners for the bills command:

    Commander User
    User 6:06 PM
    /nc command_runners bills + bookkeeping 

Secrets

copied

Admins can create secrets, which are key-value pairs in which the value is encrypted. The key is an arbitrary name, and the value represents an input parameter that should not be visible, such as an API key or password. When secret keys are used as input parameters in commands, the values are automatically decrypted and appear as input parameters to the source code.

Commander has a Secret Creator web user interface (UI) in which you create the key-value pairs and and the secret values are encrypted and stored. That way, unencrypted secret values are stored outside of your app's source code and never appear in plain text in Slack. Only admins have access to the Secret Creator.

Each Slack app contains a unique encryption key to encrypt the values for all key-value pairs. Secrets encrypted for one app can't be decrypted by any other app. The encrypted values are stored in your app using AES-256-bit symmetric encryption.

Here’s an overview of how secrets are created, with detailed procedures below:

  • Use the secrete_create  command in Slack, which outputs a link to the Secret Creator.
  • Create the key-value name pairs in the Secret Creator and click a button to encrypt the values. The Secret Creator outputs a secret_add  command for each key-value pair you’ve created.
  • Copy and paste the secret_add  commands into Slack to add them to your app.

Note: All commands for creating and managing secrets require an admin user role, but secrets can be listed by anyone with access to the secret_list command. The output of all of these commands is visible in the Slack channel in which they are run, but the parameter value is always encrypted.

Here are examples of procedures related to secrets.

Create secret key-value pairs and add them to your app:

  1. Enter the following command into Slack:

    Commander User
    User 6:06 PM
    /nc secret_create 
    Commander Admin
    Commander App 6:06 PM

    click here to access the Secret Creator

  2. In the Secret Creator UI, add a set of name-value pairs, then click Make Secrets. The Secret Creator outputs a list of secret_add commands, as in this example:

    Commander User
    User 6:06 PM
    /nc secret_add awsKey NFa_305fe79...c21e4285385f17_ 
    Commander User
    User 6:06 PM
    /nc secret_add gwpKey NFa_5c67f7b...85e915084650f6_ 
  3. Copy and paste each secret_add command from the Secret Creator output into Slack to add the encrypted key-value pairs to your current app.

View an app’s secret key-value pairs

copied

Use the secret_list command.

  • List the current app’s secret key-value pairs:

    Commander User
    User 6:06 PM
    /nc secret_list 

    The output is a list of keys with their encrypted values. Only the beginning and end of the encrypted values are shown for each secret because the encrypted values can get rather long.

Delete a secret

copied

Use the secret_delete command in Slack with the name of the secret key.

  • Delete the secret key-value pair named gc_key :

    Commander User
    User 6:06 PM
    /nc secret_delete gc_key 

Access the decrypted value of a secret in your command code

copied

Once added to your app, decrypted secret values can be accessed in source code using the secrets  input parameter.

  • Example code that accesses a secret value with the key mySecretApiKey :
    async function my_command(params, text, secrets = {}) {
      if (!secrets.mySecretApiKey) {
        return { text: "you need a mySecretApiKey secret to run this command" };
      }
      .. connect to API using secrets.mySecretApiKey ..
    }
  • Look in the command source code under the secrets input parameter. For example:
    awsConnection = createAwsConnection(secrets.awsKey);
    gwpConnection = createGwpConnection(secrets.gwpKey);
    …

Logs

copied

Commander has three log commands to view logs for an app, command, or user respectively:

The log commands are straightforward and currently only have the functionality to display the logs. Here are examples of each being used:

  • Show the log for the current app:

    Commander User
    User 6:06 PM
    /nc app_log 

    Output example:

    Commander Admin
    Commander App 6:06 PM

    343. user_log @Joe Ran by @Joe 10/18/2019, 12:19:13 AM (App: /devops)

    Commander Admin
    Commander App 6:06 PM

    342. command_code print Ran by @Joe 10/17/2019, 11:26:08 PM (App: /devops)

  • Show the log for the add_host  command:

    Commander User
    User 6:06 PM
    /nc command_log print 

    Output example:

    Commander Admin
    Commander App 6:06 PM

    8. print Ran by @Joe 10/17/2019, 6:49:34 PM Execution time 125ms with status 200 (App: /devops)

    Commander Admin
    Commander App 6:06 PM

    7. print Ran by @Joe 10/17/2019, 1:30:53 PM Execution time 122ms with status 200 (App: /devops)

  • Show the log for user @Sam :

    Commander User
    User 6:06 PM
    /nc user_log @Sam 

    Output example:

    Commander Admin
    Commander App 6:06 PM

    404. command_delete print Ran by @Sam 10/17/2019, 6:49:20 PM (App: /devops)

    Commander Admin
    Commander App 6:06 PM

    403. command_list Ran by @Sam 10/17/2019, 6:48:20 PM (App: /devops)

Tip: Every log has a line number. To go back in history, log commands support a -from  option with a line number parameter, for example:

Commander User
User 6:06 PM
/nc app_log -from 90 
Commander User
User 6:06 PM
/nc command_log add_host -from 210 
Commander User
User 6:06 PM
/nc user_log @Rick -from 300 

More advanced features, such as searching logs and allowing them to be exported will be supported in future releases.

Channels

copied

By default, Slack apps that use Commander can only output to Slack in response to a Slack command. Tasks, which run a command at an interval or rate, and triggers, which connect external webhooks to commands, aren’t run by users, so they require the ability to post to a Slack channel on their own. Commander includes channel commands that enable triggers and tasks to post in channels on their own.

Note: If you aren't using tasks or triggers, you don't need to add channels to your app

Create/add a channel

copied

In Commander, a channel is associated with an incoming webhook that can post into that channel. To allow your app to post in a channel, you must first create an incoming webhook for that channel in your custom Slack app, then add it to Commander using the channel_add command. You can use this command with a public, private or locked channel. When you add a channel, a message is posted into that channel to let you know the channel was added to Commander.

Here’s how to create a channel and add it to Commander. In this example, let’s add a channel called #devops-output  to the custom DevOps app that was created in the Quickstart Guide.

To create a channel in your custom Slack app:

  1. If you want to use a channel other than one that already exists in Slack, create it. In this example, we created a #devops-output  channel.
  2. Go to https://api.slack.com/apps.
  3. Select the DevOps app.
  4. Click Add features and functionality.
  5. Click Incoming Webhooks.
  6. Enable Incoming Webhooks.
  7. Click Add New Webhook to Workspace.
  8. Select the channel you want the task to output to and click Allow.
  9. Click Copy for the webhook URL you just created.
  10. In Slack, run the following command, substituting the values for channel name and webhook URL:
Commander User
User 6:06 PM
/nc channel_add #devops-output <webhook URL> 

Replace <webhook URL> by pasting in the webhook URL that you copied in the previous step.

Example:

Note: After you add the channel, you need to set the channel for your task or trigger. See the Tasks and Triggers sections for example commands.

List channels added to your app

copied

Use the channel_list command.

  • To list all channels added to the current app:
    Commander User
    User 6:06 PM
    /nc channel_list 

Delete a channel

copied

Use the channel_delete command with the channel name as a parameter.

  • Delete the #devops-output  channel from Commander:
    Commander User
    User 6:06 PM
    /nc channel_delete #devops-output 

Note: This command does not delete the channel's incoming webhook from Slack. To delete the channel's incoming webhook, delete it from Slack using api.slack.com.

Tasks

copied

Tasks run commands at scheduled times or at a given rate.

There are several commands to create and manage tasks. After creating a task, you can set its schedule or interval with task_schedule or task_rate and then start the task running with task_start.

Create a task

copied

Use the task_create command with parameters for the task name, output channel, and the command to run.

Create a task called mytask , output to the #general  channel, and run the print  command with the parameter “Hello World ”:

Commander User
User 6:06 PM
/nc task_create mytask #general print "Hello World" 

View or set the task rate

copied

Use task_rate. The command includes the optional parameters <value>  and <unit>  to set the rate, where <value>  is a number and <unit>  is one of: minute, minutes, hour, hours, day or days .

Notes: After you set the rate, use task_start  to start the task. If a task is running, it must be stopped with task_stop  before the rate can be changed.

  • View the task rate for mytask :
    Commander User
    User 6:06 PM
    /nc task_rate mytask 
  • Set the task rate for mytask to 15 minutes:
    Commander User
    User 6:06 PM
    /nc task_rate mytask 15 minutes 
  • Set the task rate for mytask  to one day:
    Commander User
    User 6:06 PM
    /nc task_rate mytask 1 day 

Start the task

copied

Use task_start. You can also restart a task with this command after using task_stop .

  • Start mytask :

    Commander User
    User 6:06 PM
    /nc task_start mytask 

Stop the task

copied

Use task_stop. Stopping a task doesn't delete it or change it, it just stops the task from running. You can view or set the schedule or rate of a task with the task_rate and task_interval commands. A task must be stopped to change its schedule or rate.

  • Stop mytask :

    Commander User
    User 6:06 PM
    /nc task_stop mytask 

List all tasks

copied

Use task_list to output a list of all tasks in the current app and their states.

  • To list all tasks and their states:

    Commander User
    User 6:06 PM
    /nc task_list 

Get info about a task

copied

Use task_info to show the following information about the task:

  • Name
  • Creator
  • Schedule or rate
  • Status (stopped or running).
  • If the task was started or stopped, the time it started running or when it was stopped is shown.

This information appears in the command output.

  • Show the task information for mytask :

    Commander User
    User 6:06 PM
    /nc task_info 

View or set the channel for task

copied

Use task_channel to view or set the channel associated with a task.

  • View the channel used for mytask :

    Commander User
    User 6:06 PM
    /nc task_channel mytask 

If you’re setting or changing the task channel, be sure that the channel has been created in your Slack app and added to Commander.

  • Set or change the task output channel for mytask  to #general :

    Commander User
    User 6:06 PM
    /nc task_channel mytask #general 

Delete a task

copied

Use task_delete to delete a specific task.

  • Delete mytask :

    Commander User
    User 6:06 PM
    /nc task_delete mytask 

Triggers

copied

Triggers allow an external webhook to trigger execution of a command and output the results to a Slack channel. When a trigger is created, an incoming webhook URL is created for the trigger that you have set an external webhook to call when an event takes place.

Like tasks, triggers aren't run by users, so they need a way to output to a Slack channel that you’ve created and added to your app.

Example: Create a trigger for a GitHub webhook with trigger_create

copied

As an example, you might want to set up a webhook for Github push events where a Github push (a transfer of commits to a repository) causes a command to be run to notify users in a Slack channel that a push took place. Here’s the sequence of tasks to set this up, with detailed instructions following:

  1. Choose which Slack output channel you want to use (add a channel to Commander if you haven’t already) and which command to trigger. In this case, we’ll use the existing #general channel and the print command that was in the Quickstart Guide tutorial
  2. Create a trigger with an output channel and output message, using trigger_create. This command outputs an incoming URL in the Nimbella Cloud.
  3. Use this incoming URL to create an external webhook in GitHub that notifies the incoming URL each time there’s a push in the repository.

Github has documentation about their webhooks on developer.github.com, but here are basic instructions:

To set up a trigger for a GitHub webhook to print Slack notifications when there’s a repository push:

  1. In Slack, create a trigger called GHpushTrigger that writes the output from the print  command to the #general channel:

    Commander User
    User 6:06 PM
    /nc trigger_create GHpushTrigger #general print “Hey there’s been a push in your GitHub repo!” 
    Commander Admin
    Commander App 6:06 PM

    created trigger printTrigger with incoming URL https://agigcp.nimbella.com/AHC901230/nc/v1

  2. Copy the incoming URL in the response.

  3. In GitHub, choose your repository.
  4. Click the Settings tab.
  5. Click Webhooks in the left sidebar.
  6. Click Add Webhook.
  7. In the Payload URL field, paste the incoming URL of the trigger you created.
  8. Select application/json as the Content type.
  9. Select Just the push event.
  10. Make sure the Active checkbox is selected and click Save webhook.

Now any Github push event in the GitHub repository will cause the print command to be run and the output sent to the #general channel.

Access GitHub event information

When Github sends an event using a webhook, it puts information about the event in an "X-Github-Event " HTTP header. The params.__trigger  variable in your command has all the HTTP headers and parameters of the incoming request, so you can access the Github event information with params.__trigger.X-Github-Event :

JSON.stringify(params.__trigger.X-Github-Event, null, 2)

Other commands for managing triggers

copied

Disable a trigger

Use trigger_disable. Disabling a trigger doesn't delete it or change it, it just stops the task from running the command.

  • Disable the GHpushTrigger  trigger:
    Commander User
    User 6:06 PM
    /nc trigger_disable GHpushTrigger 

Re-enable a trigger

The trigger_create  command automatically enables the trigger, but if you run the trigger_disable  command, you can re-enable the disabled trigger using trigger_enable.

  • Re-enable GHpushTrigger :
    Commander User
    User 6:06 PM
    /nc trigger_enable GHpushTrigger 

Info about a trigger

The trigger_info command shows information about a trigger.

List all triggers

Use the trigger_list command to get a list of all the triggers in the current app.

  • List all triggers in the current app:
    Commander User
    User 6:06 PM
    /nc trigger_list 

View/set the channel associated with a trigger:

Use trigger_channel.

  • View the channel associated with GHpushTrigger :
    Commander User
    User 6:06 PM
    /nc trigger_channel GHpushTrigger 
  • Set the channel associated with GHpushTrigger :
    Commander User
    User 6:06 PM
    /nc trigger_channel GHpushTrigger #general 

Delete a trigger

Use the trigger_delete command.

Note: If you delete a trigger, you should first delete the external webhook that is calling it so you don't end up with a webhook that continues to call an endpoint that doesn't exist.

  • Delete the GHpushTrigger  trigger:
    Commander User
    User 6:06 PM
    /nc trigger_delete GHpushTrigger 

Command Sets

copied

Command sets can be used to install, manage or publish a set of commands. A command set contains the definition of each command in the set, including the command's name, parameters, and a description. A command set also includes the source code for each command in the set.

Command sets are defined by a YAML file in OpenCSI Specification format. The YAML file includes links to the source code for each command. Put the YAML file in a web-accessible location, along with the source code for each command. Installing the command set using the csm_install command brings in the commands and their source, so the source can be customized at the new location. The process is similar to installing npm (Node Package Manager) packages.

You can install publicly available command sets in several different ways, as shown in the following examples.

Example 1: Install the Nimbella billing command set

copied

Nimbella maintains links to commonly used command sets that can be installed using single-word names. For example, there is a billing  command set that contains billing commands for common cloud services, such as Amazon Web Services. See the Example command sets section for a list of the example command sets available.

Note: Many of the commands in the billing  command set require API keys to allow the command source to obtain billing information from the various cloud providers. For example, to use the awsbill  command, you must create secrets for awsCostExplorerAccessKeyId , awsCostExplorerSecretAccessKeyId , and awsCostExplorerRegion . See the Secrets section for how to access information and API keys that need to be added to run the commands that require them. The various commands will output what API keys are required when they are run and what secrets are missing that they need.

Install a command set

  • Install the billing  command set in the current app, along with the source for the commands:

    Commander User
    User 6:06 PM
    /nc csm_install billing 

Output: List of commands installed.

Use csm_commands at any time to see the list of commands that were installed in this command set:

  • List the commands installed with the billing  command set:

    Commander User
    User 6:06 PM
    /nc csm_commands billing 

Customize and edit the source code of any of the installed commands using command_code to get a link to edit the command's source code.

  • Retrieve a link to the awsbill  command’s source code:

    Commander User
    User 6:06 PM
    /nc command_code awsbill 

Example 2: Install a command set from a GitHub repository

copied

The Github repository has a commands.yaml file in its root directory that contains the OpenCSI YAML definition of the command set. You can publish your own command set for others to use by putting a commands.yaml file for the command set into a GitHub repository. The commands.yaml file contains the definition of each command along with links to the source code for each command.

Anyone Installing this command set from Github would use the following command:

Commander User
User 6:06 PM
/nc csm_install github:<name>/<project> 

Example 3: Install a command set from a URL

copied

A third way to install a command set from an external location is by specifying the full URL of the command set YAML definition.

Commands to manage command sets

copied

Update an externally loaded command set

If an externally loaded command set is updated, you can update the source for all the commands from the source location with csm_update.

  • Update the billing  command set:

    Commander User
    User 6:06 PM
    /nc csm_update billing 

Notes:

  • Any changes you made to the source code of the commands in the set are overwritten by running csm_update .
  • Github runs a caching service in front of the Github web site, so if a command set is updated on Github an update may not immediately reflect the changes to the command set.

List all the command sets and commands in each command set

The csm_list command outputs all the command sets in the current app and also all the commands in each command set. There are no parameters.

  • List all command sets and all commands in each set in the current app:

    Commander User
    User 6:06 PM
    /nc csm_list 
    Commander Admin
    Commander App 6:06 PM

    billing: awsbill, datadogbill

    The output shows there is one command set (billing ) with two commands: awsbill  and datadogbill 

List the commands in a specified command set

Use csm_commands to see the list of commands included in one command set:

  • List the commands installed with the billing  command set:

    Commander User
    User 6:06 PM
    /nc csm_commands billing 

Show information about a command set

The csm_info command provides the following information for a specified command set that was loaded with csm_install :

  • Name of the command set
  • URL location
  • Version number
  • Description of the command set

Note: This command doesn’t work with command sets created with csm_create .

Uninstall a command set

Use csm_uninstall to uninstall a command set.

Note: This command also deletes all the source code for the commands in the set, even if the source has been modified. To prevent this, delete the command set instead.

  • Uninstall the billing  command set:

    Commander User
    User 6:06 PM
    /nc csm_uninstall billing 

Delete a command set

Use csm_delete to delete a named command set. Only the command set is deleted – the commands in the set are unaffected by this command. If you want to delete the commands as well, use the csm_uninstall command instead.

  • Delete the billing command set from the current app:

    Commander User
    User 6:06 PM
    /nc csm_uninstall myset 

Create and manage a custom command set

copied

First, create a command set, then add and remove commands in a second step.

Create a command set

Use the csm_create command to create an internal command set.

  • Create a command set called myset :

    Commander User
    User 6:06 PM
    /nc csm_create myset 

Add and remove commands

Use csm_commands to add and remove commands from a command set. Use plus signs to add and minus signs to remove. Leave a space after the plus or minus sign.

  • Add the commands mycommand1  and mycommand2  to the myset  command set:

    Commander User
    User 6:06 PM
    /nc csm_commands myset + mycommand1 + mycommand2 

The csm_commands  command without the optional parameters lists the commands included in this command set.

Export an OpenCSI definition of your internal command set

The csm_export command outputs an OpenCSI definition for a command set. You can copy that definition to an external location, such as into a commands.yaml file in a Github repository, then put in references to the source code for the commands.

  • Output an OpenCSI definition for the myset  command set:

    Commander User
    User 6:06 PM
    /nc csm_export myset 

Example command sets

copied

A number of command sets are available that contain example commands and source code.

Here's a list of some of them:

  • print - a simple example that outputs a message Commands: print
  • billing - various cloud billing commands Commands: awsbill, datadogbill, gcpbill
  • csm_examples - examples of command parameter types Commands: command1, command2, command3
  • output_examples - examples showing different types of slack output Commands: output1, output2, output3
  • npm_examples - examples showing how to install and list npm packages Commands: npm1, npm2
  • Install the npm_examples  command set:

    Commander User
    User 6:06 PM
    /nc csm_install npm_examples 
  • View the source code of one of the npm1  example command:

    Commander User
    User 6:06 PM
    /nc command_code npm1 

See Example 1 for how to install and view the commands in the billing  command set.

Security

copied

You’ll notice when you install the Commander app in Slack, it doesn’t ask for any special permissions. That’s because Commander can’t connect Slack to a command or post in a channel on its own. All connections from Slack to Commander must be explicitly made by a Slack workspace administrator.

When you install Commander, it doesn’t read any of your messages. It isn’t a bot and it can’t create custom Slack slash commands on its own. It also doesn’t have access to any of your channels unless you explicitly permit it to post in a channel. This is by design to ensure that Commander only does what you explicitly allow it to do.

For example, if you want a Commander task to post a message in a Slack channel, you must create an incoming webhook URL for the channel and give that webhook URL to Commander with the channel_add  command. That isn't necessary for slash commands that users type into a channel. When your custom Slack app is in your workspace and you type custom commands, it has permission to post in the channel the command is run from.

User and team identities are automatically managed by Slack. When Slack slash commands are executed, Commander ensures Slack is the caller using a shared secret key. HTTPS is used for all communications. Internally, Commander uses the Nimbella Cloud. In the Nimbella Cloud, each command function executes in an isolated container, with its environment separated from other containers. Apps in Commander are each separated by namespaces with their own authorization keys.

Manage Accounts

copied

When you add an app to Commander, an account is automatically created for you and tied to your Slack workspace. All apps added to the same Slack workspace share the same account.

Accounts have plan information (paid/unpaid) and various limits associated with them.

  • To view the account information associated with your Slack workspace, including the plan and limits, use account_info.
  • If you want to increase your account limits and upgrade your plan, use the account_upgrade command to start the upgrade process for your Slack workspace. This command outputs a web link that will take you to a web page showing your upgrade options and various plan costs.

Upgrading

copied

The free version of Commander has limitations in terms of commands, tasks, and triggers and only allows commands to be written in JavaScript. Upgrades are available on a Slack workspace (team) basis to give all apps in the workspace higher limits and enable more features. Upgrades include the ability to allow direct development using the Nimbella workbench.

See the pricing page for more information.