In this post I want to show how easy it is to integrate Crosswork Workflow Manager (CWM) with a system that has a swagger/openapi spec api and I will be using Netbox as an example. For brevity I will assume some prerequisite knowledge about CWM, but in short when CWM needs to communicate with the outside world an adapter is required. Cisco provides a number of adapters out-of-box but in addition we have also developed an SDK allowing users to create integrations independently. The extended SDK (XDK) enables fast adapter creation without having to write a single line of code.
Netbox setup
In preparation I have Netbox set up and configured 3 IP addresses.
Creating a new adapter
A new adapter can be created using the XDK cli application. After the create command completes the foundational pieces of the new adapter have been created.
A new adapter can be created using the XDK cli application. After the create command completes the foundational pieces of the new adapter have been created.
$ cwm-oasx create-adapter -vendor netbox -product rest
Inspecting the openapi schema
Besides the GUI Netbox has an OpenApi Specification implementation, which we will use as input for the XDK in order to generate adapter activities. I've downloaded the OpenApi schema for Netbox and added it to the docs directory of the adapter.
The first step is to use the XDK to inspect the schema to see what 'points of interest' are available. The command will print all available end-points that can be used to extend the functionality of the adapter. The output of this command will be used as input for extending the adapter.
$ cwm-oasx display-pois -src docs/netbox.v4.2.yaml
Generating activities for ipam & status
The structure of an adapter is divided into features. How to a design choice up to the adapter developer. I want to add an 'ipam' feature in one go. I can do this using the 'generate-feature' command and specifying the point-of-interest as a prefix of a collection of end-points. I'll throw in a 'status' feature just to highlight the concept.
$ cwm-oasx generate-feature -feature ipam -poi /api/ipam/ -src docs/netbox.v4.2.yaml
$ cwm-oasx generate-feature -feature status -poi /api/status/ -src docs/netbox.v4.2.yaml
The XDK has now generated two additional .proto files defining the interfaces of the added adapter features. You will also notice that the go module has been updated with 2 additional packages.
Creating the installable
The SDK also has the functionality to compile the adapter and create an archive the can be installed and deployed in CWM.
$ cwm-sdk create-installable
Deploying the adapter
The administration view of the CWM GUI allows me to install the adapter. When deploying the adapter I can select to create a corresponding worker that will execute the adapter activities when triggered from a job executing a workflow.
I can also enter the details view to see additional information regarding the adapter.
Adding connection details
Before running a workflow using this adapter to communicate with Netbox I need to add a resource and secret containing information about how to connect. This is also handled under the Administration view.
Executing a workflow
I've created a very simple workflow to test one of the generated activities. It has a single state with a single action to retrieve IP address information from Netbox using the netbox.rest.v1.0.0.ipam.GetIpAddresses activity.
After executing the workflow I can enter the job details view and inspect the result...
...which contains the information from Netbox I showed at the beginning of this article. All without writing a single line of code!
