Share this page

# Jenkins integration

Integration with Jenkins enables you to incorporate data from your Jenkins CI pipelines into your application delivery process.

In this topic:

## Plugin overview

The Application Automation Tools CI plugin enables integrating with a CI server.

The CI plugin provides the following capabilities:

- Retrieve and display the build pipelines that run on the CI server

- Trigger pipeline runs on the CI server

- Retrieve build run results, test run results, and commit information from the CI server

- Retrieve code coverage reports from a Jenkins CI server

- Trigger OpenText Functional Testing test runs on a Jenkins CI server

Note: To integrate with Jenkins, do not install the CI plugin on the Jenkins server. For details, see Upgrade to the Application Automation Tool plugin.

## Supported plugins

You connect to your Jenkins server using the Application Automation Tools plugin. You can then track and analyze builds, automated test results, and SCM data.

For the latest list of plugin dependencies, see Dependencies.

Follow these guideline when preparing the Jenkins integration:

- Make sure that you work with Application Automation Tools plugin version 5.1 or later, and that you do not have the OpenText Software Delivery Management CI plugin installed. For more details, see Install or upgrade the plugin.

- For OpenText Functional Testing integration, make sure that you work with Application Automation Tools plugin version 5.2 or later, and with OpenText Functional Testing 12.50 or later.

- To collect OpenText Enterprise Performance Engineering test results from pipeline runs, make sure that you work with Application Automation Tools plugin version 5.2 or later. For details, see OpenText Enterprise Performance Engineering.

- A pipeline's structure can only be displayed if it is built using one of the following:

  - The built-in Jenkins upstream/downstream mechanism

  - The Multijob plugin

  - The Parameterized plugin

## Prerequisites

Make sure you meet the necessary requirements.

- For setting up an integration with a CI server, see CI integration prerequisites.

- For integrating with Jenkins, see the prerequisites below.

  Prerequisite | Details
  --- | ---
  Java version 8 or later | Verify your Java version.
  OpenText Application Quality Management client | The client must be installed on the machine that runs the tests. To check if you have a client installed, follow the instructions on this page: http://<your_server>:8080/qcbin/TDConnectivity_index.html.
  Node in Jenkins | For running file system scenarios with OpenText Functional Testing, set up a node in Jenkins. For details, see Create an execution node.
  JQuery Plugin and a plugin for publishing test results | For building and tracking pipelines, install the following: JQuery Plugin 1.7.2-1 or later (required to enable the integration). A plugin that enables publishing test results. For example, JUnit Plugin 1.10 or later, or NUnit plugin (required to enable collection of your automated test results).
  Jenkins Git plugin | For integration with OpenText Functional Testing, install Jenkins Git plugin (version 2.4.4 or later).

## Install or upgrade the plugin

In your Jenkins server's user interface, open the plugin management area and upload the Application Automation Tools plugin.

To install the plugin:

1. Go to the Jenkins Server home page.

2. Click Manage Jenkins.

3. Click Manage Plugins, select the Advanced tab, and scroll down to Upload Plugin.

4. Browse to the plugin file that you downloaded and click Upload.

5. Select the option to restart Jenkins when installation is complete and no jobs are running.

Note: If you activate or deactivate the plugin at any time after installation, you must restart your CI server.

### Upgrade to the Application Automation Tool plugin

If you are currently using the OpenText Software Delivery Management CI plugin, you must remove it and replace it with the Application Automation Tools plugin.

1. Go to the Jenkins Server home page.

2. Click the Manage Plugins.

3. Select the Installed tab and uninstall the OpenText Software Delivery Management CI plugin.

4. Restart Jenkins.

5. Install the Application Automation Tools plugin, version 5.1 or later.

6. Restart Jenkins.

## Configure the connection

This section describes how to set up the connection to the Jenkins machine.

### Before you configure the connection:

1. Ask the shared space admin for an API access client ID and client secret. The plugin uses these for authentication when communicating with OpenText Software Delivery Management. The access keys must be assigned with the CI/CD Integration role in all the relevant workspaces. For details, see API access.

2. If your network requires a proxy to connect to the Internet, set up the proxy configuration.

   Action | Details
   --- | ---
   Define the HTTP Proxy Configuration | Go to Manage Jenkins > Manage Plugins > Advanced and define the necessary HTTP Proxy Configuration details. If the OpenText Software Delivery Management server is located outside of the Jenkins server's private network: Define the proxy server's details to enable Jenkins to communicate with OpenText Software Delivery Management. If the OpenText Software Delivery Management server and the Jenkins server are both in the same private network (common if you are using OpenText Software Delivery Management on‑premises): Instruct Jenkins not to use the proxy to reach OpenText Software Delivery Management. To do this, add the OpenText Software Delivery Management URL to the No Proxy Host list using its Fully Qualified Domain Name (FQDN). Note: You might still need the proxy server details defined to enable Jenkins to access other external resources, such as Git.
   Test connection | Click the Advanced button beneath the HTTP Proxy Configuration details. Enter OpenText Software Delivery Management's URL using its Fully Qualified Domain Name (FQDN), and click Test URL.
   Restart the Jenkins server | Restarting is necessary for the plugin to use the new proxy settings.

3. Decide which Jenkins user should be used to run jobs on the server.

   Caution: We recommend that you set this user’s permissions to the minimum required for this integration. The Jenkins user must have the following permissions:

   - Job Build: For working with OpenText Software Delivery Management pipelines

   - Job Create, Delete, and Read: For OpenText Functional Testing integration

   - Credentials create and Update: If your Git repository requires credentials

### Configure the connection

To set up the connection to Jenkins:

1. Go to the Jenkins Server home page.
2. Click the Manage Jenkins link.
3. Click Configure System.
4. Scroll down to the OpenText Software Delivery Management CI section.
5. Click Add OpenText Software Delivery Management server.

6. Follow the instructions on the screen to complete the configuration.

   Field | Details
   --- | ---
   Location | Enter the URL of the OpenText Software Delivery Management server using its fully qualified domain name (FQDN). Use the following format: `http://<OpenText Software Delivery Management hostname / IP address> {:<port number>}/ui/?p=<shared space ID>` For example, in this URL, the shared space ID is 1002: `http://myServer.myCompany.com:8081/ui/?p=1002` If the port is 80, you do not need to add the port number. You can copy the URL from the address bar of the browser in which you opened OpenText Software Delivery Management. For example, if this is your workspace URL, copy the full address: `https://almoctane.saas.microfocus.com/ui/?p=100101/1002#/`
   Client ID and Client secret | Make sure to enter the exact text without leading or trailing spaces.
   Jenkins user | Enter the Jenkins user that OpenText Software Delivery Management should use to run jobs on the server. Make sure the user can log in to Jenkins and has the minimum permission required for this integration: Job Build permissions. Note: We recommend that you specify a Jenkins user for OpenText Software Delivery Management. If you do not specify a Jenkins user, OpenText Software Delivery Management uses the Anonymous user, and is limited to the Anonymous user permissions. In some environments, you might want users in OpenText Software Delivery Management to only have access to a subset of jobs in specific workspaces. To define a user in Jenkins that only has access to a subset of jobs, click Advanced, and enter one or more sets of users per workspace in the Jenkins user for specific workspaces box. When creating a pipeline, you only see the jobs that can be accessed by the Jenkins user assigned to the current workspace. For details, see the plugin help.

7. To connect additional shared spaces, click Add OpenText Software Delivery Management server and enter the details.
8. Click Test Connection to validate the configuration.
9. Click Submit to save your changes.

### Next steps

After the connection is set up, you can do any of the following:

- Create pipelines from within OpenText Software Delivery Management. To do this, define a CI server in Settings, and then create pipelines. For details, see CI integration prerequisites.
- Create pipelines from within Jenkins. For details, see Create and configure pipelines in Jenkins.
- Set up the integration with OpenText Functional Testing. To do this, define a CI server in Settings, and then create a testing tool connection. For details, see Set up OpenText Functional Testing integration.
- Set up a security integration with Fortify Software Security Center (SSC) to display data on vulnerabilities. For details, see Fortify integration.

## Move an existing CI server to a new address

If you move your Jenkins server and reinstall the plugin, use the following steps to adjust the plugin's configuration and continue working with your existing pipelines.

To configure the Jenkins plugin to work with existing pipelines:

1. Get the plugin instance ID originally used to set up the CI server on OpenText Software Delivery Management:

   1. Open the global menu and select Administration > General Settings.

   2. In the spaces sidebar, select a workspace.

   3. Open the DevOps tab, and select CI servers.

   4. In the grid, locate the Instance ID column and copy your CI server's Instance ID.

2. In Jenkins, update the new plugin to use the original instance ID.

   1. Click Manage Plugins.

   2. Click Configure System.

   3. Scroll down to the CI configuration area.

   4. Click Show plugin instance ID.

   5. In the Instance ID box, enter the Instance ID you copied in the previous step.

## Create and configure pipelines in Jenkins

Before you can create a pipeline, make sure that you have configured the connection to your OpenText Software Delivery Management server. For details, see Configure the connection.

To create a pipeline in Jenkins:

1. Go to the Jenkins server home page.

2. Click the job that you want to use as the root job for your pipeline.

   Note: Select a job that is not already part on an existing pipeline.

3. In the menu, click OpenText Software Delivery Management Pipelines.

4. Click Create Pipeline.

5. Select the configuration of the OpenText Software Delivery Management server configured in Jenkins.

6. Enter the details for the pipeline.

   1. Provide a name for the pipeline.

   2. Select a workspace for your pipeline. The list displays all the workspaces on the OpenText Software Delivery Management server that you configured in the CI section.

   3. (Optional) Select a release and milestone to associate with the pipeline. You can select only releases defined in the workspace and only milestones defined in the release.

      Note: If you change the release or milestone values after the pipeline runs for the first time, a new set of runs is created in OpenText Software Delivery Management, with a new run history.

7. Click Create.

8. For details on tracking the pipelines in OpenText Software Delivery Management, see Run pipelines.

Caution: If you delete a pipeline, all its labels and configuration information are lost.

To configure a pipeline with parameterized tests (optional):

1. If your tests are parameterized, each run result is displayed as a separate test. To see run results under a single test with a separate run for each parameter value, add a parameter to your pipeline job called octane_test_result_name_run_regex_pattern.

2. Define the parameter value using a regular expression which splits the test name into two parts: one for the test name, and the other (representing the parameter value) for the external run ID.

   Example: If your test uses the format `Test name [parameter1,parameter2]`, define the regex as `\[,*\]`

3. When you run the pipeline with parameters, define the parameter name as octane_test_result_name_run_regex_pattern. Define its value as the regex you defined in the job.

   Example: In the above example, the result is two test runs whose name is the `test name`, and whose external run IDs are `parameter1` and `parameter2`.

## Configure commit ownership

The pipeline SCM information that OpenText Software Delivery Management collects from Jenkins CI jobs includes the users attributed to the Git commits. The user information is used, for example, to alert team members about failed runs that involved their commits.

By default, Jenkins uses the committer role to attribute to the commits. If the committer is not the same persona as the actual code author, you can configure the Jenkins job to attribute changes to the commit author.

To set the author as the commit owner:

1. In Jenkins, open the job's configuration page.

2. In the Source Code Management > Git section, under Additional Behaviors, expand the Add list.

3. Select Use commit author in changelog.

## Trigger suite runs from Jenkins

You can use automated test execution modes in the Jenkins plugin to enable Jenkins to trigger suite runs. This can be useful in a number of scenarios. For example:

- Defining a schedule in Jenkins, if you do not use Functional Test Execution.

- Triggering suite runs from an auto action in a release process.

- Triggering suite runs as a step in a bigger pipeline.

The following automated test execution modes are available.

Mode | Description
--- | ---
Suite context | You provide suite IDs. The Jenkins job creates a suite run for each one, and triggers the test runs as if you ran the suite from OpenText Software Delivery Management. The job does not need to be defined as a pipeline in OpenText Software Delivery Management. To see and analyze results, go to the suite run.
Pipeline context | You provide suite IDs. The Jenkins job fetches all tests from the selected suites. The job runs them by triggering the correct sub-job based on the assigned test runner. The job should be defined as a pipeline in OpenText Software Delivery Management. To see and analyze results, go to the Pipeline module. For details, see Application Automation Tools.

## Troubleshoot the Jenkins integration

If you are working with Application Automation Tools plugin version 5.1 or later, make sure that you do not have the old OpenText Software Delivery Management CI plugin installed on your Jenkins server.

The following table provides suggestions for solving integration issues:

Issue | Possible solutions
--- | ---
Test Connection fails | Verify that you are not using an outdated sdk version of the CI plugin.
Cannot run pipelines from OpenText Software Delivery Management. The Run button is unavailable. | The Jenkins server might be down, or it is not communicating with OpenText Software Delivery Management. If this occurred after upgrading from the CI Plugin: Make sure that in the plugin's OpenText Software Delivery Management CI configuration, you updated the Instance ID with the ID defined in OpenText Software Delivery Management for the CI server.
When creating a new pipeline in OpenText Software Delivery Management, the message "Failed to fetch Jenkins job" is displayed in the Job field after you select a CI server. | This happens when a Jenkins job indirectly calls itself. Try creating the pipeline from Jenkins. In this case, the log files do not indicate any problem. Version 5.2 of this plugin introduced a fix for this issue. See the next issue, "Errors occur when OpenText Software Delivery Management requests something from Jenkins".
Errors occur when OpenText Software Delivery Management requests something from Jenkins. When running a pipeline from OpenText Software Delivery Management, the message "Run pipeline: an Error occurred while running the pipeline” is displayed. When creating a new pipeline in OpenText Software Delivery Management, the message "Failed to fetch Jenkins jobs - Error 403 forbidden" is displayed in the Job field after you select a CI server. | This is an issue with the permissions of the Jenkins user that OpenText Software Delivery Management uses to execute jobs on the server. In the Jenkins configuration, in the OpenText Software Delivery Management CI section, define a Jenkins user. This user must have Job Build permissions.
When creating a new CI server in OpenText Software Delivery Management, the Jenkins server is not displayed in the list of connected servers even though Test Connection on Jenkins worked. | Make sure that the Jenkins proxy settings are correct and that you restarted the Jenkins server after changing proxy settings. For details, see CI integration prerequisites.
Test results from the pipelines are not reflected in OpenText Software Delivery Management. | Test results from Maven jobs are not reported if the job is under a folder. Version 5.2 of this plugin introduced a fix for this issue. Free style and pipeline jobs report results as expected.

### Using log files to troubleshoot

Jenkins sends various events and data to OpenText Software Delivery Management. For example, Start job, Finish job, SCM data, and test results.

When an error occurs, check the communication with Jenkins.

Also check the log file on the Jenkins server for connectivity and security issues.

The log files are located in the following locations:

- Jenkins system logs: http://<Jenkins url>/log/all
- Plugin logs: http://<Jenkins url>/userContent/nga/logs/nga.log

### Understanding the plugin's log messages

- At the end of a successful flow, Jenkins sends: done, left to send 0 events. For example:

  - `INFO - EventsClient: sending events [job\-name:STARTED] to 'http://localhost:8080'...`
  - `INFO - EventsClient: sending events [job\-name:FINISHED] to 'https://mqast010pngx.saas.mf.com'...`
  - `INFO - EventsClient: ... done, left to send 0 events`
  - `INFO - TestDispatcher: There are pending test results, connecting to the MQM server`
  - `INFO - TestDispatcher: Successfully pushed test results of build job-name#10`

- When the OpenText Software Delivery Management server is not available, log messages may look like this:

  `ERROR - BridgeClient: connection to MQM Server temporary failed: authentication error com.hp.mqm.client.exception.AuthenticationException: Authentication failed: code=503; reason=Service Unavailable`

- When an error occurs in the Jenkins–OpenText Software Delivery Management communication, log messages may look like this:

  `ERROR - EventsClient: max number of retries reached TestDispatcher: There are pending test results, but we are in quiet period`

## Troubleshoot creating pipelines

Use this table to solve your integration issues.

Issue | Possible solutions
--- | ---
Error when trying to create a pipeline: Unable to create pipeline | Make sure that the workspace you selected is included in the list of workspaces defined for the access keys that you used to connect the OpenText Software Delivery Management CI to OpenText Software Delivery Management. If you still encounter an error, select a different workspace, or ask a shared space admin to add the workspace to the list. For details, see API access.
Error when trying to configure a job: Unable to retrieve job configuration | The pipeline containing this job might have been created in a workspace that is not accessible from the CI plugin. Make sure that the workspace is included in the list of workspaces defined for the access keys that you used to connect the OpenText Software Delivery Management CI to OpenText Software Delivery Management. If you still encounter an error, ask a shared space admin to add the workspace to the list. For details, see API access.

## See also

- Run pipelines
- API access
- OpenText Application Automation Tools

https://admhelp.microfocus.com Software Delivery Management 8942
Tips to improve your search results... OpenText™ Software Delivery Management Help Center OpenText™ Software Delivery Management Help 26.3 All View Local Help Center View Online Help Center Version: