Configuring the Perforce ALM Jenkins Plugin

After installing the Perforce ALM Jenkins Plugin, you need to complete a few tasks to set up ALM to work with the plugin and then configure the plugin to connect to the ALM REST API.

Before configuring the plugin

For best results, we recommend completing the following tasks before configuring the plugin in Jenkins.

1. Make sure that Jenkins and ALM meet the requirements for using the plugin. See Using the Perforce ALM Jenkins Plugin

2. Add a dedicated user in ALM to use for interactions between Jenkins and ALM. Depending on your environment and testing process, you may need more than one dedicated ALM user. If you use multiple projects, make sure you add the user to each project Jenkins will access. See Adding users and customers for information adding users in the ALM desktop client.

3. Make sure the user has a Test Case Management license assigned.

4. Add the new user you added to a security group that has the following commands enabled. You may want to add a new security group specifically for use with Jenkins. See Adding security groups and Editing security groups for information about managing security groups in the ALM desktop client.

  • General category:
    • Allow Login via SOAP
  • Automated Testing category:
    • Associate Test Cases With Automated Test Results
    • Submit Automated Test Results
    • View Automation Suites
    • Add Automation Suites – Optional. Only required if the user will add automation suites in ALM.
    • Edit Automation Suites – Optional. Only required if the user will edit automation suites in ALM.
    • Run Automated Tests – Optional. Only required if the user will run automation suites in Jenkins from ALM.

5. Make sure the ALM REST API Server is running and can connect to the ALM Server.

6. Make sure that Jenkins can communicate with the ALM REST API Server. You can test the connection when you configure it in Jenkins. If ALM is hosted in the cloud, you may need to move the REST API Server to a different location than the ALM Server and then make sure the servers can communicate with each other.

7. Add any automation suites you need in Perforce ALM. See Adding automation suites.

Configuring an ALM REST API Server connection

Configure a connection to the ALM REST API Server so that Jenkins can communicate with ALM to submit test results.

1. Go to the Dashboard in the Jenkins instance to use with ALM.

2. Click Manage Jenkins.

3. Click Configure System.

The Configure System page opens.

4. Find the Perforce ALM Connection Configuration area.

5. If there are no existing connections, click Add.

6. Enter a Connection name that uniquely identifies the connection.

7. Enter the Perforce ALM REST API address. This is the URL to connect to the REST API Server. It must start with http:// or https://. HTTPS is highly recommended. For example, https://perforcealm.api.example.com.

8. Select the Authentication type used to connect to the ALM REST API Server.

  • Username and Password – Select to authenticate with ALM using a username and password.
  • API Key – Select to authenticate with ALM using an API key. We recommend using this authentication type for more secure authentication. An API consists of a key ID and key secret. See Managing API keys for information about using API keys.

9. Select the Credentials to use to log in to ALM. You can use a username and password or API key. We recommend using an API key.

If the credentials have not been added to Jenkins, click Add and select Jenkins to add the credentials used to log in to ALM.

  • If Jenkins will authenticate with the ALM REST API Server using a username and password, choose Username with password as the Kind. Enter the ALM Username and Password. Click Add. You return to the Configure System page. Select the username and password you added in the Credentials field.
  • If Jenkins will authenticate with the ALM REST API Server using an API key, select Secret text as the Kind. Paste the ALM API key and secret in the Secret field. Make sure it is in the following format: <KeyID>:<KeySecret>. Enter a Description to easily identify the key. Click Add. You return to the Configure System page. Select the API key you added in the Credentials field.

10. If you are connecting via HTTPS and have not configured a valid SSL certificate for your REST API Server, select Show optional settings and then select Accept SSL certificates.

If this option is selected, the first time Jenkins connects to ALM, the SSL certificate used by the host is accepted. Subsequent connections expect that the SSL certificate matches the accepted certificate. Information about the certificate is stored securely in Jenkins.

11. Click Test Connection to test the connection to the ALM REST API Server.

If the connection is successful, 'Connection successful' is displayed. If the connection fails, errors are displayed. Correct any problems and test the connection again. See Troubleshooting Jenkins configuration issues for help with common and certificate-related errors.

12. To add another ALM REST API Server connection, click Add REST API Connection and enter follow the same steps as above to add the connection information. For example, you need to do this if you use multiple ALM Servers.

13. To delete a connection, click the X on the right in the connection information area.

14. Click Save when you finish.

The information is saved. If any required fields are missing information, an error page is displayed with information. Make any changes and save the information again.

What to do next

Next, add a post-build step to a Jenkins Freestyle project or Pipeline that submits automated test results to ALM. See Adding post-build steps to automatically submit build and automated test results from Jenkins to Perforce ALM.