This article was originally published in 2021.05.24

Using plug-ins in UrbanCode Velocity

UrbanCode Velocity (now DevOps Velocity) uses a containerized microservices architecture. Containerization means that plug-ins do not run directly from a host operating system but from containerized instances or pods managed by a containerization platform. Runtime instances or pods are created from images, which serve as a template. These images are available from the UrbanCode Docker Hub repository. UrbanCode Velocity retrieves images from this repository and creates instances as needed. UrbanCode Velocity is able to manage plug-in installation and versioning without interrupting the user. To use a plug-in, complete the following steps:

1. Load the plug-in
2. Create an instance
3. Configure the plug-in integration

Some plug-ins do not need to be configured to create an integration, such as the Cucumber plug-in. They are listed on the Plug-ins page and the Actions column is empty for them. Plug-ins that are used to parse data are basically used for gathering metrics data and do not require integration. There are several plug-ins that support UrbanCode Velocity functions and are required integrations. The following plug-ins require integration:

• Bottleneck Detection
• Handlebar
• Jenkins

Load the plug-in

A plug-in is loaded when UrbanCode Velocity codes retrieves the plug-in image from the UrbanCode DockerHub repository. During the load function, the latest version of the plug-in is retrieved and used when an integration is defined.

• If you need to use a previous version of the plug-in, use the JSON file method to create the integration.
• If a plug-in is not loaded, the Load Plugin action is listed in the Action column for the plug-in.

Each UrbanCode plug-in has a unique image name. User created plug-ins can be added to the plug-in list by clicking Load Plugin.

Create an instance

1. Click Settings > Integrations > Plugins. A table of available plug-ins are displayed along with the version of the plug-in. The Actions column reflects whether a plug-in instance is available or not.
2. If there is no instance of a plug-in already installed, click Install under the Actions column for the plug-in. The instance or pod is created in UrbanCode Velocity. The plug-in is now available to create an integration.

Adding an user created plug-in

1. Click Settings > Integrations > Plugins.
2. Click Load Plugin.
3. In the Load a Custom Plugin window, type the docker image identifier. Specify the docker image name and tag. The tag value is the semantic-version of the plug-in to be loaded. You can also specify latest for the tag value. Use the format: image_name:tag.
4. Click Submit.

Configure the plug-in integration

To use a plug-in, you must integrate it into UrbanCode Velocity. Integration defines the record type and communication method that the plug-in provides access. There are two methods for integrating a plug-in:

• User interface
• JSON file

Configure the plug-in integration using the user interface

The user interface is a simple method to create an integration.

1. Obtain user access key, consider a different access key for each integration. It is not necessary but helps to maintain security. You create an access key by clicking Settings > Profile. On the User Access Keys page, click Create. It is important to copy the key and keep in it in a safe place. Once you leave the page with the key you can no longer retrieve the key.
2. Go to the Plugins page, click Settings > Integrations > Plugins.
3. Under the Action column for the plug-in, click Add Integration. On the Add Integration page enter values for the fields used to configure the integration and define communication. The fields vary based on the plug-in. See the plug-in documentation for field descriptions.
4. Click Save.

Configure the plug-in integration using a JSON file

You can configure a plug-in integration within a value stream map. Use the JSON file defining the value stream to also define the plug-in configuration properties. Plug-in properties vary based on the plug-in. Using the JSON file, you need to know the property names for all fields that can be specified. One advantage of using the JSON file is to specify a plug-in version other than the one listed on the Integrations page. To configure using a JSON file, the basic flow includes:

1. Download the value stream map. The value stream map is a JSON file used to define integrations.
2. Edit the JSON file to include the plug-in configuration properties. Within the JSON file is an Integrations section. Locate this section within the file. The following shows what this section looks like before adding properties. "integrations": [],
3. Type the plug-in properties within the square brackets ([]) that define your integration. The following properties are common regardless of plug-in. See the plug-in documentation for required and optional properties that are specific to the plug-in.

   Value stream map information

   Name	Property Name	Description	Required
   NA	image	The version of the plug-in that you want to use. To view available versions, see the UrbanCode DockerHub or on UrbanCode GitHub Plug-in Repository and locate the plug-in. If a value is not specified, the latest version is used.	No
   Integration Name	name	The name assigned to the integration.	Yes
   Logging Level	loggingLevel	The level of Log4j messages to display in the log file. Valid values are: all, debug, info, warn, error, fatal, off, and trace.	No
   NA	properties	List of configuration properties used to connect and communicate with the Digital.io Agility server. Enclose the properties within braces.	Yes
   NA	tenant_id	The name of the tenant.	Yes
   NA	type	Unique identifier assigned to the plug-in. Each plug-in has a unique identifier. You can locate the identifier by xxx	Yes

   The following example shows the BitBucket Server plug-in integration using a JSON file.

   
   "integrations": [
   { 
          "image": "1.0.22",
          "type": "ucv-ext-bitbucket-server", 
         "tenant_id": "5ade13625558f2c6688d15ce", 
         "name": "my-bitbucket", 
         "loggingLevel": "info",
         "disabled": false, 
         "properties": { 
           "baseApiUrl": "[Base URL ex: http://10.134.116.110:7990/rest/api/1.0]", 
           "username": "admin", 
           "password": "[Basic user password]", 
           "projectName": "[Full project name ex: JKE Mortgage Application]", 
           "projectKey": "[Project key ex: JMA]", 
           "repositoryName": "[app repository name ex: web-application]", 
           "repositorySlug": "[app repository name ex: web-application]" 
         } 
       }
                 ],
   

4. Save and upload the JSON file. This replaces the current JSON file with the new content.
5. View the new integration on the Integration page in the user interface. Click Settings > Integrations.

Tagging

Plug-ins created by UrbanCode developers use semantic versioning. As new versions are made available, the tagging follows the major.minor.patch format. If the tag is not specified when creating the plug-in the default value is latest.

#UrbanCodeVelocity