Use Adapter SDK

Prerequisites

To start using the CWM Adapter SDK, you need to install a Golang environment, Docker Desktop, and download the Adapter SDK contained in the CWM software package.

Install Go

To develop and test an adapter, you need to install the Golang environment. Follow the installation instructions dedicated for your OS: https://go.dev/doc/install.

Install Docker

Docker is required by the SDK to run the adapter builder container which parses the .proto files and generates .go files and installables. Download and install the Docker engine dedicated for your system from here [https://docs.docker.com/engine/install/]. Alternatively, if you have a Docker business license, you can use Docker Desktop.

Get CWM Adapter SDK

Go to Cisco Software Download page to download the CWM Software Package, where the Adapter SDK binary resides.

Include the location of adapter developer binaries by setting the environment variable path:

export PATH=/path/to/adapter-dev-binaries:$PATH

note.gif

Noteblank.gifRemember to replace the /path/to/adapter-dev-binaries with your actual path.

Overview of commands

The Adapter SDK application offers the following set of commands for managing an adapter:

  • cwm-sdk version - display the version of cwm-sdk application.
  • cwm-sdk create-adapter - create a go module with a package and the corresponding .proto files.
  • cwm-sdk extend-adapter - add a new feature to an existing adapter (go package and .proto files).
  • cwm-sdk update-adapter - update activities, input and output (go code).
  • cwm-sdk upgrade-adapter - upgrade the adapter to match CWM.
  • cwm-sdk create-installable - create an archive installable by CWM.

Create new adapter

To create an adapter, open a command-line terminal and run:

cwm-sdk create-adapter [options] -product <product-name>

note.gif

Noteblank.gifWhile the -product parameter is required for adapter creation, other options can be skipped.

Options

These are the options you can add to the create-adapter command:

Option
Data type Requirement Description
-exclude-resource string optional skip creation of the .resource.proto file from template.
-feature string optional provide name for the go package assigned to activities (default: "<adapter-name>").
-go-module string optional provide name for the module assigned to the go.mod file (default: "www.cisco.com/cwm/adapters/<vendor>/<adapter-name>").
-ignore-template optional skip generation of example code in the go and proto files.
-location string optional point to adapter location (default: current directory).
-os-architecture string optional define architecture in which adapter is developed. Valid options are: 'linux','mac-intel','mac-arm' and 'windows' (default: "linux").
-product string required provide name for the go module corresponding to the product name you create an adapter for.
-vendor string optional provide unique name for the company creating the adapter (default "cisco").
-verbose string optional output progress info. Options are: off, on and very (default "off").

Output

Once the command is executed, verify the generated output inside the new adapter directory:

  • <adapter-name>/adapter.properties
  • <adapter-name>/go/go.mod
  • <adapter-name>/proto/<vendor\>.<product\>.common.adapter.proto
  • <adapter-name>/proto/<vendor\>.<product\>.<feature\>.adapter.proto (if you defined the -feature option)
  • <adapter-name>/Makefile

Extend adapter with features

To add a feature (a go package) for an adapter, open a terminal and from your main adapter directory, run:

cwm-sdk extend-adapter [options] -feature <feature_name>

Options

Option
Data type Requirement Description
-activity string optional Provide name for a new activity to add.
-feature string required Provide name for the feature to add (default: "<adapter-name>").
-ignore-template optional Skip generation of example code in the go and proto files.
-location string optional Point to the location of adapter to which you add the feature (default: current directory).
-verbose string optional Output progress info. Options are: off, on and very (default "off").

Output

Once the command is executed, verify the generated output inside the new adapter directory:

  • <adapter-name>/proto/<vendor>.<module>.<package>.adapter.proto

Generate/update activity

Once you have an adapter with at least one feature added, you can proceed to creating activities. Activities are defined within the .proto file for a specific feature (go package). You can do this manually or use the OASX extension for OpenAPI-enabled services to automatically build of message logic in the .proto files.

Once the activities are defined, you can generate the input and output files for the adapter. Go to your main adapter directory and run:

cwm-sdk update-adapter

Options

  • -features string - provide a comma-separated list of features to update.
  • -location string - point to location of adapter to update (default: current directory).
  • -verbose string - output progress info. Options are: off, on and very (default "off").

Output

Once the command is executed, verify the generated output inside the adapter directory:

  • go/<feature\>/<vendor>.<product>.<feature>.adapter.pb.go
  • go/common/<vendor>.<product>.common.adapter.pb.go

The .pb.go files contain go structs defining the input and output parameters of the adapter. They shouldn't be altered manually.

Once the command is executed, verify the generated output inside the adapter directory:

  • go/<feature\>/activities.go

The activities.go file contains stubs for the gRPCs defined in the .adapter.proto. Once generated, you can add functionality to the activities by defining the message.

Upgrade adapter

To upgrade the go module to contain matching versions for go and required imports, go to the root directory of your adapter and run:

cwm-sdk upgrade-adapter [options]

Options

  • -cwm-version string - provide the version of CWM to upgrade to (default is latest).
  • -location string - point to location of adapter to upgrade (default: current directory).
  • -verbose string - output progress info. Options are: off, on and very (default "off").

Output

  • go/go.mod

The go.mod file module will be modifed allowing the adapter to be installed correctly.

Export library to local directory

The cwm-sdk uses the SDK go module for performing tasks. In certain cases you might want to have the SDK go module created in the adapter directory beforehand. For this purpose, use the export-lib command.

The export-lib command comes with the following options:

Option Data type Description Status
-location string Provide location where SDK lib should be created. (default: current directory) optional
-verbose string Show command progress info. Options are: off, on, or very. optional

Create adapter installable version

To create a tar.gz archive for installing your adapter for different operating systems, go to the root directory of your adapter and run:

cwm-sdk create-installable [options]

Generates code based on the proto file.

Options

  • -cwm-arch string - match provided architecture of CWM. Options are: amd64, arm64.
  • -cwm-version string - provide a CWM version to match the created installable (default is latest).
  • -include-src - include go and .proto sources.
  • -location string - point to where the installable should be created (default: current directory).
  • -verbose string - output progress info. Options are: off, on and very (default "off").

Output

  • out/<vendor>-<product>-v<X.Y.Z>.tar.gz
note.gif

Noteblank.gifBy default, the generated archive doesn't contain the adapter go module and proto files. To include them, use the -include-src option while running cwm-sdk create-installable. Note that the go module is modified using the go vendor command in order to not have any external dependencies.