How To

Installing plug-ins in UrbanCode products

Print

For products other than UrbanCode Velocity, the basic process for installing a plug-in is to download the installation file to your computer and then upload it to the server. After a plug-in is loaded on the server, it is available for use. You do not need to restart the server after you install a plug-in. UrbanCode Velocity are a different breed of plug-ins, they do not require any installation process.

The specific procedure varies depending on the UrbanCode product. See the appropriate instructions for the product that you are using:

Installing plug-ins in UrbanCode Velocity

UrbanCode 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.

If your environment does not allow access to the UrbanCode Docker Hub repository, you need to obtain the latest docker hub image into your private docker registry.

Using UrbanCode Velocity plugs-in when you don’t have access to the UrbanCode Docker

UrbanCode Velocity polls the Urbancode GitHub respository index file and displays available plug-in on the Integrations page. If your UrbanCode Velocity environment doesn’t allow access to GitHub or Docker Hub either because of Firewall restriction or lack of internet access, you can still use UrbanCode Velocity plug-ins with some additional setup. Access though a computer is necessary to access the plug-ins and import them into your environment.

The process to incorporate plug-ins is dependent on whether UrbanCode Velocity is running with a private Docker registry or not. First, you’ll want to determine the avaliable plug-ins and availabe versions. See the UrbanCode Velocity plug-ins website to view the available plug-ins. The documentation for each plug-in, contains a link to the UrbanCode Docker Hub repository where you can view the available plug-in versions. It also contains the plug-in type value you’ll need to obtain the plug-in image.

For example:
Using the BitBucket plug-in as an example, the Overview page of the plug-in documentation contains a link to the Docker Hub repository for the plug-in under the Versions heading. The following text below show the link as highlighted text.

The links takes you to the Docker Hub repository page that displays the available version for the plug-in. On the right of each version is a copy icon that copies the Pull command needed to pull that specific version from the repository.

You can also find the plug-in type value from the Integration table on the Usage page of the plug-in documentation as shown below.

Moving a plug-in image into a private Docker Hub registry

To move the plug-in Docker images to your private repository, complete the following steps using several Docker commands.

1. Pull the plug-in Docker image to your local Dock registry by using the following command.

docker pull urbancode/ucv-ext-<plugin_type>:<plugin_version>

Where <plugin_type> is the unique type assigned to each plug-in and <plugin_version> is the version of the plug-in to pull.

Note: A quick way to form the command is from the Docker Hub Tag page containing the list of plug-in images. Use the copy icon to copy the pull command for the desired image.

2. Tag the local Docker image to point to your private Docker registry. The parameter identifies the private registry, optionaly including any path to group all UrbanCode Velocity related images together, for example: my-company-private-docker-registry.com/velocity.
docker tag urbancode/ucv-ext-<plugin_type>:<plugin_version> <private-repo>/ucv-ext-<plugin_type>:<plugin_version>

3. Push the image to the private registry.
docker push <private-repo>/ucv-ext-<plugin_type>:<plugin_version>

4. After the image is uploaded to the private registry, you can create a value stream JSON file to integrate the plug-in. The first integration you must manually create the integration by downloading a value stream JSON file, make the necessary changes to define the integration, and upload the JSON file to the UrbanCode Velocity server. See the plug-in documentation for details on creating a value stream JSON file.

After an initial value stream has been created for a plug-in, to create other integrations using the plug-in, you can use the Create Integration button on the Integrations page of the user interface.


Installing plug-ins in IBM UrbanCode Deploy

Procedure

  1. Download the installation files for one or more plug-ins from the following site: https://developer.ibm.com/urbancode/plugins/ibm-urbancode-deploy/
  2. Load the plug-ins:
    1. For automation plug-ins, click Settings > Automation Plugins, then click Load Plugin.
    2. For source plug-ins, click Settings > Source Config Plugins, then click Load Plugin.
    3. Enter the path to the compressed plug-in file, and then click Submit.

Results

The plug-in is listed on either the Automation Plugins pane or the Source Config Plugins pane. After the plug-in is installed, it is available immediately.

Uninstalling a plug-in

To uninstall a plug-in, click Settings > Automation Plugins, find the plug-in, and then click Delete.

Note: Before uninstalling a plug-in, verify that it is no longer in use. Deleting a plug-in which is being used by existing processes causes those processes to be invalid.

Rolling back plug-ins

You cannot roll back a plug-in version to a previous version. If you have mistakenly deleted a version of a plug-in being used in processes, the step will display “PLUGIN DELETED”. The server retains the pertinent steps to avoid breaking persistent processes and snapshots, but the configuration should be updated according to intention. If the intention is to use an earlier version of the plug-in, perform the following steps:

    1. Uninstall (Delete) the later version of the plug-in. Now, in all processes, steps from that plug-in are shown with the text “PLUGIN DELETED”. These steps should never be left in this state.Note: The server retains the later version steps to avoid breaking snapshots. However, you cannot add these steps to processes after you delete the plug-in. All deleted steps should be updated immediately.
    2. Install the earlier version of the plug-in (if not already installed).Note: If an earlier plug-in version was installed and previously upgraded, this step is not necessary, as the previous version will be now be usable again.
    3. In each process that used steps from the later plug-in, re-create and delete the steps that are labeled “PLUGIN DELETED.” This will “roll back” the step from the later to earlier version. The process steps cannot be changed until you re-create them, even if you installed another version of the plug-in.

Note: Re-installing the later version of the plug-in will restore the processes.

See also

IBM Knowledge Center for IBM UrbanCode Deploy


Installing plug-ins in IBM UrbanCode Release

Procedure

  1. Download the installation files for one or more plug-ins from the following site: https://developer.ibm.com/urbancode/plugins/ibm-urbancode-release/. Do not extract the compressed files.
  2. Load the plug-ins:
    1. From the IBM UrbanCode Release user interface, click Integrations > Plug-in > Upload plugin.
    2. On the Upload Plugins dialog box, click Upload plugin.
    3. Click Browse and locate the plug-in installation file, and then click Save.

Results

After the upload to the server is complete, the plug-in is listed on the Plugins page and available for immediate use.

Uninstalling a plug-in

To uninstall a plug-in, click Integrations > Plug-in, locate the plug-in, and then click the Delete icon.

Note: Before uninstalling a plug-in, verify that it is no longer in use. Deleting a plug-in which is being used by existing processes causes those processes to be invalid.


Installing plug-ins in IBM UrbanCode Build

Procedure

  1. Download the installation files for one or more plug-ins from the following site: https://developer.ibm.com/urbancode/plugins/ibm-urbancode-build/. Do not extract the compressed files.
  2. Load the plug-ins:
    1. From the IBM UrbanCode Build user interface, click the System tab.
    2. In the Server group, click Plug-ins.
    3. On the Plugins page, Browse and locate the plug-in installation file and then click Open.
    4. On the Plugins page, click Load.

Results

After the upload to the server is complete, the plug-in is listed on the Plugins page and available for immediate use.

Uninstalling a plug-in

To uninstall a plug-in, click System > Plug-ins, locate the plug-in, and then click the Delete icon.

Note: Before uninstalling a plug-in, verify that it is no longer in use. Deleting a plug-in which is being used by existing processes causes those processes to be invalid.


Upgrading plug-ins

To upgrade plug-ins, install a higher version.

Important: Do not delete the currently installed version before installing the new one.


Upgrading UrbanCode Velocity plug-ins

Updates to UrbanCode plug-ins are placed on the UrbanCode DockerHub repository. Plug-in updates contain bug fixes, introduce new properties, and expanded functions. The UrbanCode Velocity plug-ins do not require additional process to access the upgraded plug-in code. However, you might want to know when a new version of a plug-in is released and determine if it introduces or enhances a feature that you want to include in your integration. You can continue to use the plug-in as-is or upgrade to the latest version. Your current integration continues to function as it currently does.

To upgrade an integration to the latest version of a plug-in:

  1. From the Settings page, click Integrations.
  2. Click Check for upgrades. Integrations that are using plug-in which have been upgraded contain a blue dot next to the integration name.
  3. Click the context menu ( ) and select Upgrade.

Version numbering

On Developer Center, plug-in versions are typically shown as integers. For example, version 6. A longer version number is displayed on the Settings page in the product, and in the name of the .zip file that contains the plug-in. For example, 6.714241.


Basic troubleshooting

Specific troubleshooting information is available in the documentation pages for some plug-ins. You can also ask questions on the UrbanCode forum on dW Answers. For any plug-in, the first troubleshooting step is to attempt, on the agent computer, to manually complete the task that you want to automate by using a plug-in. Often this procedure reveals that the problem is not due to the plug-in itself but caused by some other configuration issue.