Skip to main content
System StatusContact Support Agility Community

Tutorial - Artifacts


Learn how to register and use Continuum Flow artifacts.

In the Running a Task from a Pipeline tutorial, we ran a sample Hello World type Task and passed it parameters.

Artifacts in Flow Explained

In Continuum Flow the concept of an artifact can mean just about anything, from the traditional Java sense of a built WAR file or installable Microsoft package, but also tar / zip files, SQL scripts, data, etc. Essentially an artifact is the output of a delivery pipeline. Sometimes that will be a single file but many times especially in downstream integration pipelines there may be multiple files of different types and different purposes. Database DDL and data load scripts will be targeted towards the database whereas WAR files will be targeted at application servers. HTML, Javascript and CSS will go to web servers; images may end up on CDN. Each type of artifact will flow through a different path to ultimately get to production.

Within Flow, Artifacts are usually created or established during a Pipeline Instance. The are associated as a record consisting of a name and location. The location can be a URL, but also can be a file system address or object storage location (such as AWS S3). Continuum does not store the artifact itself but simply the record.

When the output of one Pipeline flows downstream to another Pipeline, these Artifact records are passed down as well as input. The downstream Pipeline may combine several Artifacts from several upstream Pipelines and pass down a single Artifact. Regardless of what a particular use case may need, Continuum is flexible enough to fit many scenarios.

Presently there are two ways to get Artifacts registered with Pipeline Instances. The first is using the Jenkins plugin, the second is explicitly specifying the Name and Location. We will explore both in this tutorial.

Jenkins Plugin Artifact Usage

Since there are various ways to produce artifacts in Jenkins, Flow uses the build log to find the artifact. It looks for a specific pattern in the log output for the the artifact so this pattern must be used in the Jenkins configuration. This pattern is as follows:

 [V1ARTIFACT:{"name": "artifact name", "location": "location of artifact"}]

Where a single square open bracket and the word V1ARTIFACT (upper case) with a colon starts the line and a square closed bracket terminates the line. To the right of the colon is a JSON object with the name and location keys along with the data for each.

An example:

 [V1ARTIFACT:{"name": "warfile", "location": ""}]

In this example the name of the artifact is "warfile" and the location is a URL of it's place on an Artifactory server. Presumably the Jenkins job was responsibly for getting the file there, most like via the Artifactory plugin. Regardless, in the Jenkins job this definition needs to be output to the log in this format.

One way to do this is using a command line shell and echoing the string above using variables for the build number. For example:

 echo "[V1ARTIFACT:{\"name\": \"warfile\", \"location\": \"$BUILD_NUMBER/spring-petclinic-$BUILD_NUMBER.war\"}]"

Notice how the double quotes inside of the echo's double quotes are escaped. The Jenkins build number is used as a variable.

This echo statement would ideally be located as part of a post build task in Jenkins. However it could really happen at any stage of the build as long as it appears in the log.

If more than one V1ARTIFACT line appears in the log with the same name, only one entry will be associated with the Pipeline Instance.

After the artifacts as found in the log and associated with the Pipeline Instance they can be found on the Pipeline Instance page, Manifest tab on the left, under Output Artifacts.

Add Artifact to your Jenkins Job

Return to your Jenkins job definition and add the following line to an existing build or post build execute shell step.

 echo "[V1ARTIFACT:{\"name\": \"myartifact\", \"location\": \"thefile-$BUILD_NUMBER.tar.gz\"}]"

This will simulate specifying an artifact in the log. Make another commit and push to your repository. Once the Pipeline Instance completes, check the Manifest tab for the Output Artifact. Next check the Data tab and expand the "artifacts" node. You should see a node called "myartifact". Expand this and you will see the artifact file.

Referencing the Artifact in the Pipeline

Once the Artifact is associated with the Pipeline Instance it can be used to populate variables later on in the pipeline or passed downstream to other pipelines. For this example we will perform variable substitution and use it within the same pipeline.

After the Jenkins Build step, add a Flow, Utility - Log step. In the Message box, add the following line.

      The artifact is [$artifacts['myartifact']['location']$]

Make another commit and push. When the Pipeline Instance completes, check the Progress Log in the upper right on the Pipeline Instance page. You should see the Artifact mention in the log as above.

Register Artifact Outside of Jenkins

Another way to register the artifact is using a Flow plugin function. Drag Flow, Pipeline - Register Artifact into the Stage. You can specify an Artifact Name and Artifact Location here. Variable substitution can be used in both inputs.

This is an alternate way to register artifacts outside of Jenkins and can be useful as long as the name and location can be inferred.

Wrapping Up

In future tutorials we will use the artifact information to deploy the artifact.