Structure

The Jenkins DevOps pipeline is defined in a “Jenkinsfile” ‘Jenkinsfile’ (by with the default named filename Jenkinsfile ) and has the following structure (most detail omitted). Paired curly braces ”{ }" an overall structure summarised below. Note that paired curly braces - { } - denote the start and end of a scoped section. Comments are “can be created in a block (/* comment like this */” (inline) or “inline (// ” (til end of line)comment like this).

pipeline {                    /* outermost scope    # Outermost scope
    agent { ... }      */     agent { ... }     # What are the default agent(s) upon which /* where will this run?               */ Stages execute?
    parameters { ... }        /* What is it being fed?    # What values are required if the pipeline is invoked */interactively?
    environment { ... }            /* # whatWhat other(global) variables are needed?   */
    stages {                  /* operational container    #          */
Operational container
         stage { ... }       /* first sequence of steps    # First Stage (sequence of executable steps)
 */           stageagent { ... }       /* next   # Which agent is used to execute this Stage?
            environment { ... }    */ # What variables are needed? (local to this stage)
 ...     }      steps {
                { /*step end} of stages          # Executable step
         */ }      ...
        }                           //# endEnd of pipeline

To understand these sections in more detail, refer to your Jenkins documentation. We present only the MettleCI specific things you need to know. Note that Jenkins offers flexibility in where some of these sections are placed, and in some cases, allows repetition at different scopes. Note also that there are additional things you could put in to just about every section, and that some sections may be repeated at a given scope level.

Sections before “stages”

Agent section

The agent section denotes what class of machines your pipeline can be executed on. For a CI/CD pipeline, you only need to specify this once since all projects are at the same release level. For an upgrade pipeline you may want to specify the agents within the stage so that different stages run on different release levels. In the example below the label should match the label you gave your agent on the MettleCI host when you set it up. Pipelines will stall if no running agent with the (matching set of) label(s) is found.

    agent {
 first Stage
        stage { ... }               # Second Stage
       label 'mettleci:datastage11..7.1'

   }

Parameters section

The parameters section enumerates the parameters to the pipeline with their default values. The four parameters used in the template, and their meanings are discussed in /wiki/spaces/MCIDOC/pages/2244149249

 }      parameters {         string(name: 'domainName', defaultValue: 'demo4-svcs.datamigrators.io:59445', description: 'DataStage Service Tier')        # string(name: 'serverName', defaultValue: 'demo4-engn.datamigrators.io', description: 'DataStage Engine Tier')End of Stage definitions
}            string(name: 'projectName', defaultValue: 'wwi_jenkins_ds117', description: 'Logical (unsuffixed) Project Name')                  string(name: 'environmentId', defaultValue: 'ci', description: 'Environment Identifer')
    }

When run interactively, the user will be prompted for these at pipeline start time like so:

...

 # End of Pipeline

Note that Jenkins offers some flexibility in the structure of the pipeline, and in some cases allows repetition at different scopes. For example, a single Step can optionally contain another Stages {...} container which defines more sub-Stages). To understand these sections in more detail refer to the Jenkins documentation.

Input Values

Parameters section

The parameters section enumerates the parameters to the pipeline with their default values. Note that parameters values are immutable, and once a pipeline is invoked with parameter values those values cannot be changed.

Environment Section

The environment section allows you to derive and set further useful variables. The template pipeline composes the suffixed DataStage project and copies one of the parameters to an all uppercased variable for convenience later.

...

Stages Section

The stages Stages section (see terminology) is a container for an arbitrary number of individual stages, Stage containers, which

Contains Steps - the executable actions

which are normally run in sequence . In the template pipeline there are three, “Deploy”, “Test”, and “Promote”(but can be configure to run in parallel).

Stage section notes

Each stage section begins with a label, which is a quoted arbitrary text string displayed on the pipeline diagram in Blue Ocean when viewing the pipeline,

...

This is the first stage in the pipeline and it is tasked with deploying changed project assets to the CI (continuous integration) project. WithCredentialsprovides appropriate credentials (using the credentials plugin) to the rest of the steps. change from mci-user if you are using a different user. Each bat step invokes the MettleCI CLI to perform one of the deployment tasks. Refer to the MettleCI - Auto-Generated CLI Command Syntax Reference for details of what each step is doing. The label, chosen to be descriptive of the step task, becomes the step text in the Blue Ocean display of the pipeline. If a step aborts that ends the steps part of the stage. After the steps conclude, by error or by reaching the end, the post section is evaluated. Although there are other values such as changed, fixed, etc, using always ensures the section is always executed to process test results (here, the result of the compilations) and then cleanup.

...

After a successful deployment the pipeline will perform some tests, compliance and the unit tests. These can be performed in parallel as there is no interdependence, so we use the parallel{} construct to nest the stage invocations. As before, refer to the MettleCI - Auto-Generated CLI Command Syntax Reference for details of what each step is doing.

...

The template pipeline has three promotion deployments, each of which is essentially the same as the initial deploy but directed at a different project. Our template assumes that all three deployments are to the same DataStage server, but the parameter blocks are at the individual promotion level so you can change these as necessary. You can reduce or increase (by deleting or copying code blocks) the number as necessary. These can be performed in parallel as there is no interdependence, so we again use the parallel{} construct to nest the stage invocations. As before, refer to the MettleCI - Auto-Generated CLI Command Syntax Reference for details of what each step is doing. The “innards” of each promotion step, save the first are elided in the following code snippet to focus on the structure.

...