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,
     "consolidated": { "state", "active", "permitted", "number", "batch", "batches", "finished", "failed", "total",
                       "concurrentPipelines", "sleepSeconds", "nextBatchAt", "startedAt", "finishedAt",
                       "estimatedEnd", "estimatedDuration", "startedBy", "stoppedBy" } | 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 view that shows its consolidated pipeline lists it first, with index 0 and consolidated set: its one pipeline has a stage per batch, each leading to the next, and a task per pipeline of the view, whose status is that of the pipeline as a whole, jobFullName and buildNumber the build that started it and url where that build is. state is IDLE before the first run, then RUNNING, SLEEPING until nextBatchAt, STOPPING, and at last FINISHED or STOPPED, which stay until the next run; active tells the first three apart from the rest. While a run is going the numbers and the tasks are those of the run, afterwards the tasks are what a run started now would do, each with the outcome it had in the last run. estimatedEnd is when the run going on is expected to end and estimatedDuration how long a run started now would take, going by how long the pipelines took the last time; either is null when nothing is known, and the first moves with every computation of the model, so the page leaves it out of what it compares to decide whether to draw again. permitted says whether the caller may post to startConsolidated and stopConsolidated. A pipeline that such a run started lists a trigger of type CONSOLIDATED.

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.
Consolidated	What marks a component as the consolidated pipeline of its view, the parent that runs the view's pipelines a few at a time, and tells where its run stands.
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.