Jenkins

1. Overview

Jenkins is a leading open-source automation server that helps automate the parts of software development related to building, testing, and deploying, facilitating continuous integration and continuous delivery (CI/CD). It provides a vast ecosystem of plugins to support building, deploying, and automating any project.

The GoInsight Jenkins node allows you to integrate your CI/CD pipelines directly into your automation workflows. You can manage the core components of your Jenkins instance, from jobs and builds to server-level operations. This includes:

• Job Lifecycle Management: Create, delete, copy, and trigger Jenkins jobs programmatically.
• Build Information Retrieval: Fetch detailed information about specific builds or a list of recent builds for any job.
• Instance Control: Perform administrative tasks such as restarting, shutting down, or managing the "quiet down" mode of your Jenkins server.

2. Prerequisites

Before using this node, you will need to have:

• A running Jenkins instance that is accessible from the GoInsight platform.
• A user account on the Jenkins instance with the necessary permissions to perform the desired actions (e.g., create/delete jobs, trigger builds).
• An API token generated for your Jenkins user account.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

This node allows you to perform a wide range of operations organized around key Jenkins resources like Jobs, Builds, and the Jenkins instance itself.

Summary

Operation Details

Create a Job

Create a new job in Jenkins using the provided configuration XML.

Input Parameters:

• JobName: Name of the new job to create
• JobData: Dictionary containing XML string of the job configuration. It should include the following keys: description, scm class)

Output:

• Success (bool): True if the operation was successful, False otherwise
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions)
• ErrorMessage (string): Error message description, returns empty string on success

Delete a Job

Delete an existing job in Jenkins. The job and all its build history will be permanently removed.

Input Parameters:

• JobName: Name of the job to delete

Output:

• Success (bool): True if the operation was successful, False otherwise
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions)
• ErrorMessage (string): Error message description, returns empty string on success

Get Many Builds

Get build information for multiple builds from Jenkins. Can get builds for a specific job or from all jobs.

Optional Parameters:

• JobName: Name of the job to get builds for. If not provided, gets builds from all jobs
• Limit: Maximum number of builds to retrieve per job, minimum value is 1

Output:

• Builds (object-array): List of builds in JSON format
• Total (number): Total number of builds retrieved
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions)
• ErrorMessage (string): Error message description, returns empty string on success

Get Many Jobs

Get job information for multiple jobs from Jenkins

Optional Parameters:

• Limit: The number of jobs returned per request, minimum value is 1.
• Offset: Pagination offset, minimum value is 0.

Output:

• Jobs (object-array): List of jobs in JSON format.
• Total (number): Total number of jobs matching the criteria.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Cancel Quiet Down

Cancel Jenkins quiet down mode. When Jenkins is in quiet down mode, it stops accepting new builds and prepares for shutdown or restart. This function cancels that mode.

Output:

• Success (bool): True if the operation was successful, False otherwise
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions)
• ErrorMessage (string): Error message description, returns empty string on success

Copy a Job

Create a new job by copying an existing job in Jenkins. The new job will have the same configuration as the source job.

Input Parameters:

• SourceJobName: Name of the existing job to copy
• NewJobName: Name of the new job to create

Output:

• Success (bool): True if the operation was successful, False otherwise
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions)
• ErrorMessage (string): Error message description, returns empty string on success

Quiet Down

Put Jenkins instance in quiet down mode. When Jenkins is put in quiet down mode, it stops accepting new builds and prepares for shutdown or restart. Existing builds continue to run.

Output:

• Success (bool): True if the operation was successful, False otherwise
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions)
• ErrorMessage (string): Error message description, returns empty string on success

Restart

Restart Jenkins instance. Jenkins can be restarted in two modes: 1. Safe restart (default): Jenkins will wait for existing builds to complete before restarting 2. Immediate restart: Jenkins will restart immediately without waiting for builds to complete

Optional Parameters:

• SafeRestart: If True, performs a safe restart (wait for builds to complete). If False, performs an immediate restart. Defaults to True

Output:

• Success (bool): True if the operation was successful, False otherwise
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions)
• ErrorMessage (string): Error message description, returns empty string on success

Shutdown

Shutdown Jenkins instance. If safe_shutdown is True, Jenkins will enter quiet mode and wait for existing builds to complete before shutting down. If safe_shutdown is False, Jenkins will shut down immediately.

Optional Parameters:

• SafeShutdown: If True, Jenkins will perform a safe shutdown (wait for builds to complete). If False, Jenkins will shut down immediately. Defaults to True

Output:

• Success (bool): True if the operation was successful, False otherwise
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions)
• ErrorMessage (string): Error message description, returns empty string on success

Trigger a Job

Trigger a build for an existing job in Jenkins. Supports both parameterized and non-parameterized jobs.

Input Parameters:

• JobName: Name of the job to trigger

Output:

• Success (bool): True if the operation was successful, False otherwise
• BuildUrl (string): URL of the triggered build, empty if operation failed
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions)
• ErrorMessage (string): Error message description, returns empty string on success

Trigger a Job with Parameter

Trigger a job in Jenkins with parameter.

Input Parameters:

• JobName: Name of the job to trigger.
• Parameters: Dictionary of parameters to pass to the job.

Output:

• Success (bool): True if the operation was successful, False otherwise.
• BuildUrl (string): URL of the triggered build, empty if operation failed.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

5. Example Usage

This section will guide you through creating a simple workflow to create a new job in your Jenkins instance using the Create a Job operation.

The workflow will consist of three nodes: Start -> Jenkins: Create a Job -> Answer.

1. Add the Jenkins Node

• In the workflow canvas, click the "+" icon to add a new node.
• In the panel that appears, select the "Tools" tab.
• Find and select "Jenkins" from the list of tools.
• In the list of supported operations for Jenkins, click on "Create a Job" to add the node to your canvas.

2. Configure the Node

• Click on the newly added "Create a Job" node to open its configuration panel on the right.
• Credentials Configuration: At the top of the panel, find the credentials field. Click the dropdown menu and select the Jenkins credential you have already configured.
• Parameter Configuration: Fill in the required input parameters for the action.
  • JobName: Enter the name for your new Jenkins job, for example, my-automated-test-job.
  • JobData: This field requires the job's configuration in XML format. You can obtain a template by creating a similar job in the Jenkins UI and then accessing its config.xml file (e.g., http://your-jenkins-url/job/your-job-name/config.xml). You would then provide this XML content as a string within a JSON object, like

3. Run and Validate

• Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
• Click the "Run" button in the top-right corner of the canvas to execute the workflow.
• After a successful execution, you can click the logs icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the operation was successful. You can also verify that the new job has been created in your Jenkins UI.

After completing these steps, your workflow is fully configured. When you run it, a new job will be created in your Jenkins instance according to the provided configuration.

6. FAQs

Q: What format does the JobData parameter for the 'Create a Job' action expect?

A: The JobData parameter expects a JSON object containing the job's configuration as an XML string. The standard format is Jenkins' config.xml. The easiest way to get a valid XML structure is to:

• Create a job with the desired configuration manually in the Jenkins UI.
• Navigate to the job's URL and append /config.xml to the end.
• Copy the entire XML content from that page and use it as the value in your JobData input.

Q: I'm receiving a 401 Unauthorized or 403 Forbidden error. What should I do?

A: These errors typically indicate an issue with authentication or permissions. Please check the following:

• API Token: Ensure the API token used in your GoInsight credential is correct and has not expired or been revoked.
• User Permissions: Verify that the Jenkins user associated with the API token has the necessary permissions to perform the action (e.g., Job > Create, Job > Delete).
• Credential Configuration: Double-check that you have selected the correct Jenkins credential in the node's configuration panel.

Q: How can I trigger a parameterized job?

A: Use the Trigger a Job with Parameter action. The Parameters input field expects a JSON object (dictionary) where keys are the parameter names and values are the parameter values you want to pass to the build. For example: {"BRANCH": "develop", "RUN_TESTS": "true"}.

7. Official Documentation

For more in-depth information about the Jenkins API and its capabilities, please refer to the Jenkins Official API Documentation.