Use CWM SDK

Prerequisites

To start using the CWM SDK, you need to install a Golang environment, Docker, and download the SDK executable 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 cwm-sdk 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 SDK

Go to Cisco Software Download page to download the CWM Software Package, where the CWM 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: Remember to replace the /path/to/adapter-dev-binaries with your actual path.

Overview of commands

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

  • cwm-sdk upgrade-adapter - upgrade the adapter to match CWM.
  • cwm-sdk create-installable - create an archive installable by CWM.
  • cwm-sdk version - display the version of cwm-sdk application.
  • cwm-sdk export-lib - creates SDK go module & proto files
  • 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).

Create new adapter

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

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

Note: While 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
-custom-secret string optional generate a stub for custom secret implementation.
-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.
-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).
-product string required provide name for the go module corresponding to the product name you create an adapter for.
target-id string optional create adapter for a specific platform (default is CWM).
-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
  • go/<feature\>/activities_test.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.

The activities_test.go file helps you validate the core functions of your adapter. It includes unit tests to ensure correct behavior, error handling, and expected responses for different scenarios. You can use it to verify that API calls or other operations function as intended.

Note: The test cases generated in activities_test.go will initially fail until you implement the corresponding activities and update the tests accordingly. Failures are expected and serve as a guide to ensure that functionalities are correctly developed and validated.

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

  • -location string - point to location of adapter to upgrade (default: current directory).
  • -target-id string - provide platform to upgrade adapter for.
  • -target-version string - provide the version of platform to upgrade to.
  • -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 can export the SDK go module to use it for creating adapter structure faster and more efficiently. The CWM SDK library is essential for defining secrets, logs, and error handling in your adapter, and it gets exported to your adapter directory when you run the create-adapter command. If needed, you can also use the export-lib command at every stage of adapter developemnt to keep it up to date.

Command syntax

cwm-sdk export-lib -location /path/to/sdk-library -verbose string

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

Note: - A single CWM SDK library can be used for multiple adapters. To share the SDK library among multiple adapters, use the -location option to store it in a common directory outside the adapter directories. - If the SDK library is missing, the adapter might fail to compile due to missing dependencies.

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

  • -include-src - include go and .proto sources.
  • -location string - point to where the installable should be created (default: current directory).
  • -sign-key string - provide path to private RSA key used for signing.
  • -target-arch string - match provided architecture of platform. Options are: amd64, arm64.
  • -target-id string - provide name of the target platform to match the created installable.
  • -target-version string - provide version of the target platform to match the created installable.
  • -verbose string - output progress info. Options are: off, on and very (default "off").

Output

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

Note: By 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.