OpenCSI

copied

Background

copied

OpenCSI stands for Open Command Set Interface. Similar to how OpenAPI describes an API, OpenCSI describes a set of commands.

An OpenCSI description is YAML format file that describes a set of commands and the parameters they take.

The YAML file is expected to be placed in a directory structure that includes the source for the commands described in the YAML file under a "packages" subdirectory.

As an example, if we created a command set called "hoststuff" that included commands "host_add", "host_delete" and "host_list", we would put the commands.yaml in the top level directory.

We would then create a "packages" subdirectory and another subdirectory under it with the name of the command set. In that subdirectory, we could create a subdirectory with the name of each command. The files in that subdirectory would contain the source for the command and for Javascript, it can include package.json and related files.

The full directory structure of the "hoststuff" command set would be:

/commands.yaml /packages/hoststuff/host_add/index.js /packages/hoststuff/host_add/package.json /packages/hoststuff/host_delete/index.js /packages/hoststuff/host_delete/package.json /packages/hoststuff/host_list/index.js /packages/hoststuff/host_list/package.json

With the commands.yaml containing the OpenCSI specification describing the commands and the other files being the source code and dependent packages for each command.

One quick way to start creating your own command set is with one of the examples in the command set registry here:

https://github.com/nimbella/command-sets

You can install an OpenCSI-described command set into Teams with Commander using the csm install command.

This command set containing these 3 commands:

  1. host_add <hostname> <ip_address> [-just_a_flag] This first command requires a hostname parameter, has an optional ip address parameter and 2 options. It has a description of "Adds a host"
  2. host_delete <hostname> This second command requires a single hostname parameter. It has a description of "Deletes a host"
  3. host_list <match> This third command requires a single match parameter. It has a description of host_list "Lists hosts"

Can be described in OpenCSI with:

OpenCSI: 1.0
info:
  description: This is the description of the Command Set
  version: 1.0.0
  title: My Command Set
  termsOfService: 'http://nimbella.com/demo/terms'
  contact: demo@nimbella.com
  license:
     name: Apache 2.0
     url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
commands:
  host_add:
     description: Adds a host
     parameters:
        - name: hostname
        - name: ip_address
          optional: true
     options:
        - name: ttl
          value: seconds
        - name: just_a_flag
  host_delete:
     description: Deletes a host
     parameters:
        - name: hostname
  host_list:
     description: Lists hosts
     parameters:
        - name: match