Package se.diabol.jenkins.pipeline.model

package se.diabol.jenkins.pipeline.model

The immutable view model of a Delivery Pipeline view and, through Stapler's @Exported, its JSON contract.

Everything a ComponentSource produces is one of these records. They hold no references to Jenkins model objects, so a computed model can be cached and served to any user; the few per-user facts (permissions) are computed while exporting.

JSON contract, as served by <view>/api/json:

 {
   "components": [ {
     "name", "index", "error",
     "firstJob": { "fullName", "displayName", "url", "parameterized" },
     "paging": { "page", "pageSize", "total", "pages" } | null,
     "pipelines": [ {
       "id", "version", "timestamp", "aggregated", "jobFullName", "buildNumber", "rebuildable", "commits",
       "totalBuildTime", "status": { "type", "timestamp", "duration", "progress" },
       "permissions": { "build", "cancel" },
       "triggers": [ { "type", "description" } ],
       "contributors": [ { "name", "url" } ],
       "changes": [ { "author": { "name", "url" }, "message", "commitId", "url" } ],
       "tests": [ { "name", "url", "total", "failed", "skipped" } ],
       "analysis": [ { "name", "url", "high", "normal", "low" } ],
       "stages": [ {
         "id", "name", "row", "column", "version", "downstream": [ stage id ],
         "status": { "type", "timestamp", "duration", "progress" } | null,
         "tasks": [ {
           "id", "name", "url", "jobFullName", "buildNumber", "description", "rebuildable", "restart",
           "requiresInput", "inputUrl",
           "status": { "type", "timestamp", "duration", "progress" },
           "manual": { "upstreamJob", "upstreamBuild", "enabled" } | null,
           "permissions": { "build", "cancel" },
           "tests": [ { "name", "url", "total", "failed", "skipped" } ],
           "analysis": [ { "name", "url", "high", "normal", "low" } ],
           "promotions": [ { "name", "startTime", "duration", "user", "icon", "params" } ],
           "downstream": [ task id ]
         } ]
       } ]
     } ]
   } ],
   "settings": { ... the display and action options of the view ... },
   "serverTime": epoch millis
 }
 

Timestamps are epoch milliseconds and durations are milliseconds; URLs are relative to the Jenkins root URL.

The response carries an ETag made of the model's version and the viewer. A request that sends it back as If-None-Match and finds the model unchanged is answered with 304 Not Modified and no body; the page does this on every poll. The JSON is exported once per model and viewer, only serverTime is written afresh into every response. Requests with Stapler's tree, depth or pretty parameters are exported on the spot instead.

A pipeline's rebuildable runs the whole pipeline again; a task's rebuildable builds the task's job again, or when restart names a stage, restarts the Pipeline run from that stage. Static analysis results sit on the task whose build produced them, or on the pipeline when they belong to a Pipeline run as a whole; test results sit on the task that recorded them, or on the pipeline when they were recorded outside the tasks shown. A task waiting at an input step is proceeded by posting to proceedInput with its id as task, or, when inputUrl is set because the step has parameters, by following that link.

A Pipeline run that started other runs, with the build step, carries their stages too: the stage that started a run lists the run's first stage in downstream, as does the task that holds the step; the started run's stage and task ids carry its job#number/ as a prefix, and its stage names its job's name, as "job: stage". The tasks name their own job and build in jobFullName and buildNumber, which the actions are posted for.

A pipeline's status is that of its own run and a stage's status that of the whole stage block of a Pipeline stage; either can be worse than every task shows when steps outside the tasks failed or went unstable, which the page marks on the stage header and the run heading.

Related Packages

Package	Description
se.diabol.jenkins.pipeline

Class	Description
AnalysisSummary	Static analysis warning counts of a build, by priority.
Change	One commit of a pipeline instance's change log.
Component	One pipeline of the view with its recent instances.
Contributor	The author of a change.
JobRef	The job a component starts with.
ManualStep	A task that a person has to trigger, as the Build Pipeline plugin's manual trigger defines it.
Paging	Where a component's pipelines are in the list of all of them.
Permissions	What the current user may do with a job; computed while exporting, never cached.
Pipeline	One run of a component's pipeline, or the aggregated pipeline that shows each stage's latest version.
Promotion	A promotion of a build.
Stage	A column of tasks in the pipeline grid.
Status	The status of a task.
StatusType	The state of a task, in the order the legend shows them.
Task	One box of a stage: a job of a chain of jobs, or a stage, nested stage or parallel branch of a Pipeline run.
TestSummary	Test result counts of a build.
Trigger	What caused a pipeline instance to start.
ViewModel	What the view's api/json serves: the components and the settings.
ViewSettings	The display and action options of a view, as the sources and the page script need them.