Skip to end of metadata
Go to start of metadata

Plugin Information

View Template Workflows on the plugin site for more information.

Definition of a Workflow (AKA Build Flow or Pipeline):

A workflow is a set of jobs, these jobs may be linked (trigger each other) and may share parameters.

Introduction:

Jenkins is all about workflows. But creating, updating, duplicating or deleting these workflows is not easy and takes time.
Think about all the times you had to duplicate a set of jobs: duplicate each job, link the jobs together and modify each job one by one so it will be properly configured, didn't you ask yourself - why can't I just define the workflow once and reuse this definition?
This plugin introduces an easy way of managing workflows using the Jenkins UI.

Plugin main features:

  • Define template workflows
  • Optionally share parameters between jobs in a template workflow
  • Create workflows from templates
  • Update workflows parameters easily
  • Execute workflows
  • Delete workflows
  • Full compatibility with other Jenkins plugins

Defining Template Workflows:

Template workflows can be defined as any type(s) of jobs and each job can be a member of several "template workflows".
The definition is done from the job configuration screen, just mark the job as a building block in a template workflow and state the template workflow name.

Let's say we would like to define a simple template workflow called "template-workflow1" which is made out of 2 jobs where one triggers the other (jobA triggers jobB):

Definition of jobA:

Definition of jobB:

Notes:

  • In order for a job to be a member of several template workflows, simply state all the workflows names (comma separated).
  • By checking the "This is The Workflow Starting Job" check box, this job will be scheduled when the workflow will be executed (more than one job can be selected as a starting point for a single template workflow). 

Defining Parameters for Template Workflows:

Parameters are also defined in the job configuration page and are identified using a unique pattern: @@PARAMETER_NAME@@.

You can define parameters wherever you like on the job configuration page:

      

Notes:

  • In case two or more jobs are building blocks of the same template workflow - they share the same parameters, just define the same parameter name in the jobs configuration pages.  
  • By using this methodology (defining parameters by pattern), we are able to define parameters on any field we like (please refer also to the "Limitations & Workarounds" section).

Create Workflows from Templates:

In order to create workflow we first have to create a new job type called "Template Workflow Job".

After creating the new job, we are now able to create workflows out of our template workflows.

Open the new project and click the "Create Workflow" link, all the defined template workflows will be automatically recognized.

  1. Select a workflow template (automatically shows all the related jobs and related parameters)
  2. Give your workflow a name (Must be unique for the current project)
  3. Select new jobs names for your workflow (These jobs will be created and associated in the current workflow)
  4. Fill the parameter values (these values will be populated in the above jobs configuration)
  5. Click the "Create" button

  

You will see that a new workflow has been added to your project in the "Associated Workflows" side view.
In our example, the workflow named "workflow-test" is made out of 2 jobs: job1 and job2. 
The relation between job1 and job2 has been derived from jobA and jobB, meaning job1 triggers job2. Please notice that job1 and job2 are configured with the workflow parameter values. 

You now have several options:

  • Create other workflows and associate them to your project.
  • Edit created workflow and update the workflow parameters (will update the workflow jobs configuration). 
  • Execute a workflow (Jobs that have been marked as the starting point for the workflow will be added to the build queue).
  • Delete a workflow (will also delete the jobs that were created during the workflow definition).

Version Compatibility

This plugin was tested against Jenkins 1.477, but should work with previous versions of Jenkins.

Advanced configuration:

  • Sometimes you do not want to duplicate a specific job and just include it in your workflow.
    In order to accomplish that, when creating the workflow - enter the existing job name and check the 'Allow the use of existing jobs' checkbox.
  • Explanation on how to configure the Locks and Latches plugin: create a lock with parameter pattern and configure your job with this lock.

Limitations & Workarounds:

Some fields have validation (when submitting the job configuration page), this prevents us from configuring parameter pattern in these fields.
In order to overcome this issue, you will have to manually configure the template job config.xml (one time task) - replacing the specific field value with parameter pattern.

Releases:

* Version 1.2: Initial release

10 Comments

  1. This plugin is great! Very interesting and awaited concept.
    It's now intuitive and easy to configure and maintain workflows with this plugin.

  2. Amazing plugin!
    It really gives you the ability to differentiate between a workflow definition and instantiation of a workflow. All I  (configuration manager) need now is to maintain the template workflows.

  3. It seems that this plugin does not respect the promotions plugin, at minimum.   Tested with Jenkins 1.483

    How to add bugs for this component?  When I try to add a bug in JIRA it claims that template-workflows is not a valid component.

  4. Great plugin, but it has some shortcomings:

    Let's consider that we have a structure of two jobs(jobA, and job1). jobA is a template(interface) job, job1 is Implementation job.

    1. No maintenance of local changes. It means if you decided to add some changes to created implementation workflow job (i.e. job1), you will lost them after next *update* button is pressed.

    2. Unable to update with new parameter.  If we add a new *Workflow parameter* in jobA, we won't be able to update and add value to existing workflow where job1 resides. To do this, we must create new workflow again.

    3. Broken links. When we create an implementation job1, from template job jobA, job1 has a hyperlink: jenkins/job/job1, but this hyperlink does not work if we created our template job, jobA in sectioned view, for example: Test-jobs. Our new implementation job1 exists in: http://.../jenkins/view/Test-jobs/job/job1/ instead of http://.../jenkins/job/job1/

  5. This is a promising plugin !

    I encountered some limitations though :

    • When starting job is a parameterized job, we cannot fill parameterized values when launched through the Workflow UI.
      Workaround : don't launch it from the workflow view and prefer to launch the generated job from standard jenkins UI.
    • When are the generated job re-generated ? It seems it is only re-generated when we update the workflow ?
      That is to say, if I want to change my template and apply this change on my generated jobs, I must :
      • Modify my template and save it
      • Modify my workflows using my template and save them
        Seems like the latter is unnatural and unnecessary :(
    • It would be great to be able to define shared properties across every workflow in a template workflow job.
      For instance, I generally use the scm url as a job template param. And it is generally the same scm url across every workflows for a given template workflow.
  6. I've added few templates jobs with parameters. And it's ok.

    But I have "poll scm" option so jenkins tries to build templates jobs and fails. If I disable template job it clones from workflow as disabled.

    How to pervent jenkins from build these template jobs? 

  7. An "Update all workflows" button would be nice to have

  8. There is a bug when characters like & (ampersand) are being used in the template parameters when creating a new workflow instance. The error message looks like the following:

    hudson.util.IOException2: Failed to persist configuration.xml
            at hudson.model.AbstractItem.updateByXml(AbstractItem.java:584)
    ...
    Caused by: javax.xml.transform.TransformerException: org.xml.sax.SAXParseException: The entity name must immediately follow the '&' in the entity reference.
            at com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transform(TransformerImpl.java:719)
            at com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transform(TransformerImpl.java:313)
            at hudson.model.AbstractItem.updateByXml(AbstractItem.java:580)
            ... 73 more

    By the way, I cant put this issue into JIRA since there is no component for template-workflow, it would be worth fixing that too so that information like this goes to the right place.

  9. I think this plugin has some promise, but to really be affect the workflow template needs to provide an easy way to add inputs between the jobs. Until that is possible I see this as a quick way to create copies of jobs, but not a true workfow template. Additionally the plugin doesn't work with folders.

  10. Dears,

    Could you please provide me a workaround in order to use this plugin without Jenkins Administer Permission enabled for the user ?

    I would like to be able to click on the "Create workflow" link without administrator privilege.

    Thank you in advance for your support.

    Best regards.