Ontrack Reference Guide 3.42...2.3.3. Bulk update of validation stamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 2.4. Managing

Ontrack Reference Guide 3.43.3Damien Coraboeuf

Version 3.43.3

Table of Contents1. Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1. Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2. Quick start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.3. Postgres database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.4. Installing using Docker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.4.2. Basic deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.4.3. Docker Compose deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.5. RPM installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.6. Debian installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.7. Standalone installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.8. Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2. Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.1. Managing projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.1.1. Project favorites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.1.2. Project labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Using the labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Assigning labels to a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Management of labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Automation of labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.2. Managing branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.2.1. Managing the branches in the project page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.2.2. Branch favorites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.2.3. Branch templating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.2.4. Managing stale branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.2.5. Validation stamp filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Using filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Editing filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Authorisations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.3. Managing validation stamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.3.1. Validation stamp data configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.3.2. Auto creation of validation stamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Predefined validation stamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Configuring projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Auto creation of validation stamps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Auto creation of validation stamps when not predefined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Predefined validation stamps and validation data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

2.3.3. Bulk update of validation stamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

2.4. Managing promotion levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

2.4.1. Auto promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

2.4.2. Promotion checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Previous promotion check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Previous dependencies check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

2.4.3. Auto creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Predefined promotion levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Configuring projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Auto creation of promotion levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

2.5. Managing the builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

2.5.1. Filtering the builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Sharing filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

2.5.2. Build links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Definition of links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Decorations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Querying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Filtering the build links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

2.5.3. Run info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

2.6. Managing validation runs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

2.6.1. Validation run status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

2.6.2. Validation run status comment edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

2.6.3. Hyperlinks in descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

2.6.4. Validation run data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Run data metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

2.7. Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

2.7.1. Build link display options property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

2.7.2. Message property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

2.7.3. Meta information property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Input. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Representation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Querying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

2.7.4. Release property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

3. Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.1. Branch templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.1.1. Template Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.1.2. Template Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.1.3. Template expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

3.2. Working with SCM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

3.2.1. SCM Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

SCM Catalog list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Orphan project decoration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Project labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

GraphQL schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Specific configuration for GitHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

3.3. Working with Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

3.3.1. Working with GitHub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

General configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Project configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

SCM Catalog configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

3.3.2. Working with GitLab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47



3.3.3. Working with BitBucket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47



3.3.4. Git searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

3.3.5. Working with Subversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Subversion configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Indexation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49


Branch configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Tag name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Tag pattern name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Revision name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Revision pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Build / tag synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

3.4. Change logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

3.4.1. Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

3.4.2. Commits/revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

3.4.3. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

4. File changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

4.1. Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

4.1.1. Searching engine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

4.2. Project indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

4.2.1. Indicators authorization model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

4.2.2. Indicator types management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Value types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

4.2.3. Indicator edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

4.2.4. Indicator portfolios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Global indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Management of portfolios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Portfolio page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Portfolio edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

4.2.5. Importing categories and types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

4.2.6. Computing indicators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

5. Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

5.1. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

5.1.1. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

5.1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Global roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Project roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

5.1.3. Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Built-in accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

LDAP accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

5.1.4. Account groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

5.1.5. General settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

5.1.6. Extending the security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

5.2. LDAP setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

5.2.1. LDAP general setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

5.2.2. LDAP group mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

5.3. Administration console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

5.3.1. Managing running jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Filtering the jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Controlling the jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

5.3.2. External connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

5.3.3. List of extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

5.4. Application log messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

5.5. Status page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

6. Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

6.1. ElasticSearch search engine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

6.1.1. ElasticSearch configuration properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

6.1.2. ElasticSearch indexers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

6.2. Integration with Jenkins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

6.3. Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

6.3.1. Health . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

6.3.2. Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

List of metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

InfluxDB metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

6.4. Management end point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

6.4.1. Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

6.5. GraphQL support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

6.6. Calling with Curl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

6.7. Using the DSL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

6.8. GraphiQL support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

6.9. Extending the GraphQL schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

6.10. Encryption service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

6.10.1. Selection of the confidential store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

6.10.2. File confidential store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

6.10.3. JDBC confidential store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

6.10.4. Vault confidential store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

6.10.5. Migrating encryption keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

6.10.6. Losing the encryption keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

6.10.7. Adding custom confidential store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

6.11. Run info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

6.11.1. Collection of run info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

6.11.2. Displaying the run info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

6.11.3. Exporting the run info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Exporting the run info to InfluxDB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Exporting the run info using extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Restoring the exported run info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

6.12. Integration with SonarQube . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

6.12.1. General configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

6.12.2. Global settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

6.12.3. Project configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

6.12.4. Build measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

6.12.5. Export of measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Collection metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Missing measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

7. DSL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

7.1. DSL Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

7.1.1. Embedded. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

7.1.2. Standalone shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

7.1.3. Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

7.1.4. Retry mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

7.1.5. Calling the DSL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

7.2. DSL Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

7.2.1. DSL Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Management of accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Account permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Management of account groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Account group permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

DSL LDAP mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

7.2.2. DSL Images and documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

7.2.3. DSL Change logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Getting the change log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Commits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Exporting the change log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

File changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

7.2.4. DSL Branch template definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

7.2.5. DSL SCM extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

7.3. DSL Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

7.4. DSL Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

7.5. DSL Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

8. Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

8.1. Branching strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

8.2. Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

8.2.1. Environment set-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Postgres set-up. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

8.2.2. Building locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

8.2.3. Launching the application from the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

8.2.4. Launching the application in the IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

8.2.5. Developing for the web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

8.2.6. Running the tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

8.2.7. Integration with IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

With Intellij . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

8.2.8. Delivery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Versioning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Deploying in production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

8.2.9. Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

8.3. Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

8.3.1. Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

8.3.2. UI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Resource decorators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

8.3.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Form object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Common field properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

help property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

visibleIf property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

text field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

password field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

memo field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

email field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

url field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

namedEntries field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

date field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

yesno field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

dateTime field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

int field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

selection field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

multi-strings field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

multi-selection field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

multi-form field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Creating your custom fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Form usage on the client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Fields rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

8.3.4. Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

8.3.5. Model filtering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

8.3.6. Jobs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Job architecture overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Job registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

8.3.7. Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

8.3.8. Build filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

8.3.9. Reference services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117EntityDataStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

8.3.10. Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Client side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Server side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

8.4. Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

8.4.1. Running the unit and integration tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

8.4.2. Acceptance tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

On the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

From the IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Standalone mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

8.4.3. Developing tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Unit test context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Integration test context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

8.5. Extending Ontrack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

8.5.1. Preparing an extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

8.5.2. Extension ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

8.5.3. Coding an extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

8.5.4. Extension options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

8.5.5. Writing tests for your extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

8.5.6. List of extension points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

8.5.7. Running an extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Using Gradle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

8.5.8. Packaging an extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

8.5.9. Extension dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

8.5.10. Deploying an extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Using the Docker image. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Using the CentOS or Debian/Ubuntu package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

In standalone mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

8.5.11. Extending properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Java components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Web components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Property search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

8.5.12. Extending decorators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Java components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Web components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

8.5.13. Extending the user menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Extension component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

8.5.14. Extending pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Extension menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

From the global user menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

From an entity page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Extension global settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Extension page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Extension API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Extension API resource decorators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

8.5.15. Extending event types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

8.5.16. Extending validation data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

8.5.17. Extending GraphQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Preparing the extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Custom types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Root queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Extra fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Built-in scalar fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Testing GraphQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

8.5.18. Extending cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

8.5.19. Extending metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Meter registry direct usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Validation run metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Run info listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Metrics export service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

8.5.20. Using Kotlin in extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

8.5.21. Extending the settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

8.5.22. Extending the security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Adding functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Adding roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

8.5.23. Extending confidential stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

8.5.24. Free text annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

8.5.25. Label providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

8.5.26. Extending promotion checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

8.5.27. Extending the search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Search indexer overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Search indexation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Search results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Search index items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Search indexation mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Search indexation jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Search result icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Search indexing on events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

9. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

9.1. Configuration properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

9.2. Deprecations and migration notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

9.2.1. Since 3.38 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

9.2.2. Since 3.35 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

9.2.3. Since 2.28 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

9.2.4. Since 2.16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

9.3. Roadmap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

9.3.1. Use JPA / Hibernate for SQL queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

9.3.2. Using Neo4J as backend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

9.3.3. Global DSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

9.3.4. Web hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

9.4. Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

9.4.1. Registering a certificate in the JDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

9.4.2. Saving the certificate on MacOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

9.5. Metrics migration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

9.6. Migration from H2 to Postgres . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

9.6.1. Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

9.6.2. Migration tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

9.6.3. Running the migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

9.6.4. Migration tool options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

9.6.5. Secret files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

9.7. Postgres and Flyway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

9.8. Using production data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

9.9. DSL Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

9.9.1. Ontrack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

9.9.2. AbstractProjectResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

9.9.3. AbstractResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

9.9.4. Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

9.9.5. AccountGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

9.9.6. Admin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

9.9.7. AuthenticationSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

9.9.8. Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

9.9.9. Build. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

9.9.10. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

9.9.11. ChangeLogCommit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

9.9.12. ChangeLogFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

9.9.13. ChangeLogIssue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

9.9.14. Config. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

9.9.15. Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

9.9.16. GroupMapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

9.9.17. LDAPSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

9.9.18. Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

9.9.19. MainBuildLinks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

9.9.20. PredefinedPromotionLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

9.9.21. PredefinedValidationStamp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

9.9.22. Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

9.9.23. ProjectEntityProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

9.9.24. PromotionLevel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

9.9.25. PromotionRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

9.9.26. SearchResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

9.9.27. SonarQubeMeasuresSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

9.9.28. ValidationRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

9.9.29. ValidationRunStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

9.9.30. ValidationStamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Chapter 1. InstallationThere are several ways to install Ontrack.

1.1. PrerequisitesOntrack has been tested on different Linux variants (Ubuntu, Debian, CentOS) and should also workon Windows.

Ontrack relies on at least a JDK 8 build 25. More recent versions of the JDK8 are OK. However, notest has been done yet using JDK 9 and older versions.

Ontrack runs fine with 512 Mb of memory. However, think of upgrading to 2 Gb of memory if youintend to host a lot of projects. See the different installation modes (Docker, RPM, etc.) to know howto setup the memory settings.

Ontrack stores its data in a Postgres database and can optionally use ElasticSearch for searchindexes.

1.2. Quick startThe fastest way to start Ontrack is to use Docker Compose:

curl -fsSLO https://raw.githubusercontent.com/nemerosa/ontrack/master/compose/docker-compose.ymldocker-compose up -d

This sets up:

• a Postgres database

• an ElasticSearch (single node)

• Ontrack running on port 8080

Go to http://localhost:8080 and start using Ontrack. The initial administrator credentials are admin /admin.

See [usage] to start using Ontrack.

1.3. Postgres databaseUnless you choose to deploy with Docker Compose, you will need to have a Postgres databaseaccessible by Ontrack.

Version 9.5 of Postgres has been tested successfully with Ontrack, but any later 9.x version shouldbe OK as well.

No test with Postgres 10.x has been performed yet.

1

http://localhost:8080

Ontrack will by default try to connect to jdbc:postgresql://postgresql/ontrack, using ontrack /ontrack as credentials.

Those parameters can be configured using normal Spring Boot JDBC configuration, for exampleusing arguments at startup:

--spring.datasource.url=jdbc:postgresql://localhost:5432/ontrack--spring.datasource.username=myuser--spring.datasource.password=password

See the Spring Boot documentation to see other and better ways to pass those configurationparameters.

1.4. Installing using DockerOntrack is distributed as a Docker image on the Docker Hub, as nemerosa/ontrack:3.43.3.

1.4.1. Overview

The Ontrack image exposes the port 8080.

Two volumes are defined:

• /var/ontrack/data - contains some working files but also the log files.

• /var/ontrack/conf - contains the configuration files for Ontrack (see later).

Several modes of database setup can be done:

• database persisted in volume

• using a H2 server database

1.4.2. Basic deployment

You can start Ontrack as a container and a shared database and configuration on the host using:

docker run --detach \ --publish=8080:8080 \ --volume=/var/ontrack/data:/var/ontrack/data \ --volume=/var/ontrack/conf:/var/ontrack/conf \ nemerosa/ontrack

The configuration files for Ontrack can be put on the host in /var/ontrack/conf and the databaseand working files will be available in /var/ontrack/data. The application will be available on port8080 of the host.

Java options, like memory settings, can be passed to the Docker container using the JAVA_OPTIONSenvironment variable:

2

https://docs.spring.io/spring-boot/docs/1.5.8.RELEASE/reference/htmlsingle/#boot-features-external-config

https://hub.docker.com

docker run \ ... --env "JAVA_OPTIONS=-Xmx2048m" \ ...

Additional arguments to the Ontrack process, like configuration arguments passed on the commandline, can use the ONTRACK_ARGS environment variable.

docker run \ ... --env "ONTRACK_ARGS=..." ...

1.4.3. Docker Compose deployment

Create the following file:

docker-compose.yml

version: "2.1"

services: # Ontrack container ontrack: image: nemerosa/ontrack:3 environment: PROFILE: prod links: - "postgresql:postgresql" ports: - "8080:8080"

# Postgresql database postgresql: image: postgres:9.5.2 environment: POSTGRES_DB : ontrack POSTGRES_USER : ontrack POSTGRES_PASSWORD: ontrack ports: - "5432"

In the same directory, run:

docker-compose up -d

3

After some time, Ontrack becomes available at http://localhost:8080

1.5. RPM installationYou can install Ontrack using a RPM file you can download from the releases page.

The RPM is continuously tested on CentOS 6.7 and CentOS 7.1.

To install Ontrack:

rpm -i ontrack.rpm

The following directories are created:

Directory Description

/opt/ontrack Binaries and scripts

/usr/lib/ontrack Working and configuration directory

/var/log/ontrack Logging directory

You can optionally create an application.yml configuration file in /usr/lib/ontrack. For example, tocustomise the port Ontrack is running on:

server: port: 9080

Ontrack is installed as a service using /etc/init.d/ontrack.

# Starting Ontrackservice ontrack start# Status of Ontrackservice ontrack status# Stopping Ontrackservice ontrack stop

To upgrade Ontrack:

# Stopping Ontracksudo service ontrack stop# Updatingsudo rpm --upgrade ontrack.rpm# Starting Ontracksudo service ontrack start

The optional /etc/default/ontrack file can be used to define environment variables like

4


https://github.com/nemerosa/ontrack/releases

JAVA_OPTIONS or ONTRACK_DB_URL (to use the H2 server mode). For example:

/etc/default/ontrack

JAVA_OPTIONS=-Xmx2048mONTRACK_DB_URL=jdbc:h2:tcp://h2:9082/ontrack;MODE=MYSQL

The ONTRACK_ARGS environment variable can be use to pass additional application parameters.

1.6. Debian installationYou can install Ontrack using a Debian file (.deb) you can download from the releases page.

To install Ontrack:

dpkg -i ontrack.deb

The following directories are created:

Directory Description

/opt/ontrack Binaries and scripts

/usr/lib/ontrack Working and configuration directory

/var/log/ontrack Logging directory

Ontrack is installed as a service using /etc/init.d/ontrack.

# Starting Ontrackservice ontrack start# Status of Ontrackservice ontrack status# Stopping Ontrackservice ontrack stop

The optional /etc/default/ontrack file can be used to define environment variables likeJAVA_OPTIONS or ONTRACK_DB_URL (to use the H2 server mode). For example:

/etc/default/ontrack

JAVA_OPTIONS=-Xmx2048mONTRACK_DB_URL=jdbc:h2:tcp://h2:9082/ontrack;MODE=MYSQL

The ONTRACK_ARGS environment variable can be use to pass additional application parameters.

5


1.7. Standalone installationOntrack can be downloaded as a JAR and started as a Spring Boot application.

Download the JAR from the Ontrack release page

Start it using java -jar ontrack.jar.

Options can be passed on the command line.

See the Docker installation section for information on how to connect to thedatabase.

1.8. ConfigurationAs a regular Spring Boot application, Ontrack can be configured using system properties and/orproperty files and/or YAML files. See the Spring Boot documentation for more details.

The way to provide a YAML application.yml configuration file or command linearguments will vary according to the installation (Docker, RPM, etc.). See thecorresponding section above for more details.

For example, to setup the port Ontrack is running on, you can use the server.port property. Using aYAML file:

application.yml

server.port=9999

or the command line option:

--server.port=9999

See Configuration properties for the list of all available properties.

6


http://projects.spring.io/spring-boot/

http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#howto-properties-and-configuration

Chapter 2. Basics

2.1. Managing projects

2.1.1. Project favorites

When the list of projects becomes too important to be manageable, the user can select some of themas favorite projects.

The user must be logged in to select and see his favorite projects.

The list of favorite projects appears at the top of the home page and each of them displays the statusof its branches:

• name of the branch

• highest promotion for the branch with its associated build

The list of branches, for a Git-based project is restricted by its associated branchingmodel (only "main" branches are displayed).

For non-Git-based projects, as-of now, no restriction on the branches is done.

In order to make a project a favorite, you have to click on the little star icon which is on the left ofthe project name in the list of all projects:

To unselect a project as favorite, you do the same (this time, the star is marked as yellow):

Note that you also unselect a project as favorite from the list of favorite projects:

7

Branches of a project can also be selected as favorite - see Branch favorites.

2.1.2. Project labels

Projects can be associated with labels. This allows to classify them.

Labels are defined by:

• an optional category

• a name (unique within the category)

• an optional description

• a color (always given using the form #RRGGBB, for example black is #000000)

Using the labels

Project labels are displayed in the home page, in the list of projects:

They also appear in the project page, under the project’s name:

In the home page, projects can be filtered using labels. Several options are available.

You can type parts of the label in the Label filter box at the top of the project list. This displays a listof matching labels from which you can select an actual label:

Once the item is selected, the list of projects is filtered accordingly:

You can also select the label directly from the Label dropdown:

8

Finally, from the home page or from the project page, clicking on a label will select this label as afilter.

The selected filter is stored at browser level and is therefore preselected the nexttime you go to the home page.

You can clear the selected label by either:

• emptying the Label text box

• select Clear in the Label dropdown

Note that upon a label selection, this selection appears also in the URL of yourbrowser and can be used as a permalink to this filter.

Assigning labels to a project

Only some users are allowed to assign labels to projects.

See Security for list of available roles.

If the user is authorized to assign labels to a project, a pencil icon appears close to the list of labelsand the Labels command is available in the page menu. Both commands perform the sameoperation.

Those commands display a dialog which allows the selection (and unselection) of labels among alist. When exiting the dialog through the OK button, the selection of labels is applied to the projectand the project page is reloaded.

The list of available labels can be filtered using the text box at the top of the list.

9

Management of labels

Authorized users can manage the list of labels from their user menu.

The label management page allows the user to

• create

• update

• delete

labels. In the Projects column, the number of projects associated with the label on the line. Ifgreater than zero, it is a link to the home page, with the corresponding label being selected.

The edition dialog for a label looks like:

10

The color editor, as of now, relies on the browser default color editor, so therendering might be different from browser to browser.

If authorised, the creation of a label is also available from the project label assignment dialog. If thefilter being typed does not match any label, a button appears which allows the creation of the newlabel:

Once the label is created, it’s selected and filtered by default:

Automation of labels

Some labels can be created and assigned automatically using the concept of the "label providers".

The main thing to remember about automatically assigned labels is that theycannot be edited, not deleted, not unselected.

By default, automated labels are NOT enabled. In order to enable their collection, you can:

11

• set the ontrack.config.job-label-provider-enabled configuration property to true

• or go to the Settings and navigate to the Label provider job section:

• enabled - enable or disable the collection of automated labels. This overrides the settingsdefined by ontrack.config.job-label-provider-enabled

• interval - how often the collection of labels must be performed

• job per project - by default, only one job is created for the collection of all labels. Set this optionto split this job per project.

Those options are mostly used for tuning the performances on really big Ontrackinstances.

To create a label provider, you have to create an extension: see Label providers.

2.2. Managing branchesSeveral branches can be defined per project.

2.2.1. Managing the branches in the project page

If you click on the Show all branches button in the project page, you can display all the branches,including the ones being disabled and the templates.

According to your authorizations, the following commands will be displayed as icons just on theright of the branch name, following any other decoration:

• disabling the branch

• enabling the branch

• deleting the branch

12

This allows you to have a quick access to the management of the branches in a project. Only thedeletion of a branch will prompt you about your decision.

2.2.2. Branch favorites

Instead of selectioning a project as a favorite, one might find more convenient to select branchesonly.

This reduces the clutter on the home page when projects tend to have a lot of branches.

All favorite branches do appear on the home page, together with any favorite project:

The favorite branches of a given project do also appear on the project page:

In both cases, following information is displayed:

• latest build

• latest build per promotion

Branches can be unselected as favorite using the star left of their name.

In order to select a branch as favorite, use the little star left of its name in the branch list in theproject page:

13

You can use this star to unselect it as well. When selected, the star is marked asyellow.

2.2.3. Branch templating

In a context where branches are numerous, because the workflow you’re working with implies thecreation of many branches (feature branches, release branches, …), each of them associated with itsown pipeline, creating the branches by hand, even by cloning or copying them would be too muchan effort.

Ontrack gives the possibility to create branch templates and to automatically create branches usingthis template according to a list of branches. This list of branches can either be static or provided bythe SCM.

See Branch templates for details about using this feature.

2.2.4. Managing stale branches

By default, Ontrack will keep all the branches of a project forever. This can lead to a big number ofbranches to be displayed.

You can configure a project to disable branches after a given number of days has elapsed since thelast build, and then to delete them after an additional number of days has elapsed again.

To configure this:

• go to the project page

• select the Stale branches property and add it:

• set the number of days before disabling and the number of days before deleting

14

If the disabling days are set to 0, no branch will be ever disabled or deleted.

If the deleting days are set to 0, no branch will ever be deleted.

You can also set a list of promotion levels - a branch which is or has been promoted to such apromotion level will not be eligible for being disabled or deleted.

In the sample above, the stale branches will be disabled after 60 days (not shown any longer bydefault), and after again 300 days, they will be deleted (so after 360 days in total). Branches whichhave at least one build being promoted to PRODUCTION will not be deleted or disabled.s

Note that the Stale branches property can also be set programmatically using the DSL.

2.2.5. Validation stamp filters

When a branch defines many validation stamps, the view can become cluttered and not reallyuseful any longer, because displaying too much information.

Validation stamp filters can be defined to restrict the view to a set of known validation stamps.

Using filters

Validation stamp filters can be selected in the branch view, just on the left of the list of validationstamp headers:

When a filter is selected, it is marked as such and only associated validation stamp columns areshown in the view:

15

The validation stamp filter menu is also marked in orange to indicate that a filter has been applied.

When the filter is applied, its name appears also in the URL. This can be used as a permalink:

You can remove the filter by selecting Clear validation stamp filter in the filter menu:

Editing filters

Only authorized users are allowed to edit the validation stamp filters for a branch.See Authorisations for more details.

A validation stamp filter is defined by:

• a name

• a list of validation stamp names to include

While it is possible to edit a filter using a dialog (see later), it is far easier to use the in-place editor.

Start by creating a validation stamp filter by selecting the New Filter… entry in the filter menu:

16

This displays a dialog to create the new filter:

Only the name is required and all current validation stamps filters are included bydefault.

When created, the filter can be directly edited in-place:

The following actions are possible:

• by clicking on the Select none button, no validation stamps is associated with the filter.

• by clicking on the Select all button, all validation stamps are associated with the filter.

• by clicking on the Done with edition button, the in-place edition stops and the normal display isresumed

You can also click on a validation stamp to remove it or to add it to the filter.

In case the validation stamp is associated with the filter, a minus icon appears close to its name. It itis not associated, the icon is dimmed and a plus icon appears:

17

Note that you can also stop the edition by selecting the eye icon in the menu:

To start editing an existing filter, just click also on the eye icon close to its name:

Select any other filter, or removing the filter, will also stop the in-place edition.

To edit a filter directly, you can also select the pencil icon and edit the filter using a dialog:

This displays an edition dialog allowing to change the name and the list of validation stamps.

18

For a filter associated with a branch (see below, sharing), names can be selectedamong the validation stamps of the branch.

For a filter associated with a project, the list of validation stamps for all thebranches is available.

For a global filter, names are no longer selected but must be edited.

Finally, to delete a filter, click on the trash icon:

A confirmation will be asked before the deletion actually occurs.

Sharing

A filter is created by default at branch level and is only visible when the associated branch isdisplayed.

An authorized user can:

• share the filter at project level - in this case, the filter is available for all the branches of theproject

• share the filter at global level - in this case, the filter is available for all projects and all branches

19

A filter shared at project level is shown with a [P] close to its name and a global filter with a [G]:

In the screenshot above:

• DEPLOYMENT is associated with the current branch

• DOCUMENTATION is associated with the project

• the other filters are global

To share a filter at project level, click on the share icon:

To share a filter at global level, click on the share icon:

20

Authorisations

According to the role of the authenticated used, following actions are possible:

Scope Action Participant Validationstampmanager

Projectmanager/owner

Administrator

Branch Create Yes Yes Yes Yes

Branch Edit Yes Yes Yes Yes

Branch Delete Yes Yes Yes Yes

Branch Share toproject

No Yes Yes Yes

Project Edit No Yes Yes Yes

Project Delete No Yes Yes Yes

Project Share to global No No No Yes

Global Edit No No No Yes

Global Delete No No No Yes

2.3. Managing validation stamps

2.3.1. Validation stamp data configuration

Validation stamps are often created by tests, or scans, or any other kind of automated process. Thisis often associated with some metrics. For example:

• a security scan could bring a list of critical and high defects

• a test run has a list of passed and total tests

• a coverage test has a coverage %

• etc.

Ontrack is able to associate such data to a validation run for a given build and validation stamp.

The only precondition is that the validation stamp must be configured for a given type of data.

When creating or edition a validation stamp, you can select the type of data you want to associatewith any validation run for this validation stamp.

There is a list of predefined data types:

• plain text

• CHML (Critical / High / Medium / Low)

• Number (with or without threshold)

• Fraction (with or without threshold)

• Percentage (with or without threshold)

21

• Metrics (arbitrary map of names to floating point numbers)

You can create your own validation data types.

Every type is associated with a configuration. For some of them, nothing is needed.

For data types with threshold, you might want to select threshold for generating warnings, failures,according to a given direction.

For example, a validation stamp could be associated with a number of passed tests linked with atotal number of tests. This is a "fraction" type, where the numerator is the number of passed tests,and the denominator is the total number of tests.

The warning and failure thresholds are expressed as percentages, and we can choose a direction(higher is better by default).

If the failure threshold is 50, and the total number of tests is 200, and the number of passed tests is99, then, we’re below the threshold of 50 (%) and the validation run is marked as a failure.

22

For the creation of data associated with validation runs, see the associated documentation.

In order to use create a validation stamp with some validation data type, you can also use the DSL:

23

def branch = ...branch.validationStamp("Text data") { setTextDataType()}branch.validationStamp("CHML data") { setCHMLDataType("HIGH", 1, "CRITICAL", 1)}branch.validationStamp("Number data") { setNumberDataType(10, 100, true)}branch.validationStamp("Percentage data") { setPercentageDataType(0, 50, false)}branch.validationStamp("Fraction data") { setFractionDataType(100, 90, true)}branch.validationStamp("Metrics data") { setMetricsDataType()}

2.3.2. Auto creation of validation stamps

Creating the validation stamps for each branch, or making sure they are always up to date, can be anon trivial task. Having mechanisms like cloning or templates can help, but then one must stillmake sure the list of validation stamps in the template is up to date and than the template isregularly synchronized.

Another approach is to allow projects to create automatically the validation stamps on demand,whenever a build is validated. This must of course be authorised at project level and a list ofpredefined validation stamps must be maintained globally.

Predefined validation stamps

The management of predefined validation stamps is accessible to any Administrator, in his usermenu.

He can create, edit and delete predefined validation stamps, and associate images with them.

Deleting a predefined validation stamp has no impact on the ones which werecreated from it in the branches. No link is kept between the validation stamps inthe branches and the predefined ones.

Configuring projects

By default, a project does not authorise the automatic creation of a validation stamp. In case oneattempts to validate a build using a non existing validation stamp, an error would be thrown.

In order to enable this feature on a project, add the Auto validation stamps property to the projectand set Auto creation to Yes.

24

Disabling the auto creation can be done either by setting Auto creation to No or by removing theproperty altogether.

Auto creation of validation stamps

When the auto creation is enabled, build validations using a validation stamp name will follow thisprocedure:

• if the validation stamp is already defined in the branch, it is of course used

• if the validation stamp is predefined, it is used to create a new one on the branch and is thenused

• in any other case, an error is displayed

The auto creation of validation stamps is available only through the DSL orthrough the API. It is not accessible through the GUI, where only the validationstamps of the branch can be selected for a build validation.

Auto creation of validation stamps when not predefined

You can also configure the project so that validation stamps are created on demand, even when nopredefined validation stamp is created.

In this case:

• if the validation stamp is already defined in the branch, it is of course used

• if the validation stamp is predefined, it is used to create a new one on the branch and is thenused

• in any other case, a new validation stamp is created in the branch, with the requested name(and with an empty image and a default description)

Predefined validation stamps and validation data

As for validation stamps associated with branches, the predefined validation stamps can beassociated with some validation data.

2.3.3. Bulk update of validation stamps

Validation stamps are attached to a branch but in reality, they are often duplicated in a projectbranches and among all the projects. Updating the description and the image of a validation stampcan fast become cumbersome.

The predefined validation stamp can mitigate but this won’t solve the issue when validation stampsare created automatically even when not predefined.

In order to update all the validation stamps having the same name, across all branches and allprojects, you can use the Buld update command in the validation stamp page:

25

A confirmation will be asked and all the validation stamps having the same name, across allbranches and all projects, will be updated with the same image and the same description.

A predefined validation stamp will also be updated or created.

In order to perform a bulk update, you must be an administrator or been grantedthe global validation manager role.

Any validation data configuration is also part of the bulk update.

2.4. Managing promotion levels

2.4.1. Auto promotion

By default, a build is promoted explicitly, by associated a promotion with it.

By configuring an auto promotion, we allow a build to be automatically promoted whenever agiven list of validations or promotions have passed on this build.

For example, if a build had passed integration tests on platforms A, B and C, we can imaginepromoting automatically this build to a promotion level, without having to do it explicitly.

In order to configure the auto promotion, go to the promotion level and set the "Auto promotion"property. You then associate the list of validation stamps that must be PASSED or promotion levelswhich must be granted on a build in order to get this build automatically promoted.

The list of validation stamps can be defined by:

• selecting a fixed list of validation stamps

• selecting the validation stamps based on their name, using include and exclude regularexpressions

A validation stamp defined in the list is always taken into account in the autopromotion, whatever the values for the include and exclude regular promotions.

The list of promotion levels can be set independently of the list of validation stamps.

2.4.2. Promotion checks

By default, a build can be promoted to any promotion independently of any other constraint.

In particular, promotions are ordered and a build can be promoted to a given promotion withoutthe previous ones being granted.

If this "lax" behavior is not correct, you can configure this in several ways, using promotion checks.

This check on previous promotions is built-in in Ontrack but other could be addedby creating extensions.

26

Previous promotion check

One check is to make sure that a promotion is granted only if the previous one is granted. Forexample, if we have BRONZE → SILVER → GOLD as promotions for a branch:

• SILVER could not be promoted if IRON is not

• GOLD could not be promoted if SILVER is not

You can activate this behaviour:

• globally, by activating the settings for "Previous promotion condition"

• at project, branch or even promotion level level, by setting and activating the "Previouspromotion condition" property

The order of priority of this check is as follows:

• promotion level "Previous promotion condition" property (takes precedence on a branch setup)

• branch "Previous promotion condition" property (takes precedence on a project setup)

• project "Previous promotion condition" property (takes precedence on global settings)

• Global "Previous promotion condition" settings

Previous dependencies check

You can also define a set of dependencies to a promotion, like a list of promotions which must begranted before a promotion is itself granted.

For example, if we have IRON → BRONZE → SILVER → GOLD as promotions for a branch, we coulddecide that GOLD cannot be promoted if either BRONZE or SILVER is missing.

You can activate this behaviour by setting the "Promotion dependencies" property on a promotionlevel, and selecting the dependencies it depends on.

2.4.3. Auto creation

Creating the promotion levels for each branch, or making sure they are always up to date, can be anon trivial task. Having mechanisms like cloning or templating can help, but then one must stillmake sure the list of promotion levels in the template is up to date and than the template isregularly synchronized.

Another approach is to allow projects to create automatically the promotion levels on demand,whenever a build is promoted. This must of course be authorized at project level and a list ofpredefined promotion levels must be maintained globally.

Predefined promotion levels

The management of predefined promotion levels is accessible to any Administrator, in his usermenu.

He can create, edit and delete predefined promotion levels, and associate images with them.

27

Deleting a predefined promotion level has no impact on the ones which werecreated from it in the branches. No link is kept between the promotion levels in thebranches and the predefined ones.

Configuring projects

By default, a project does not authorize the automatic creation of a promotion level. In case oneattempts to validate a build using a non existing promotion level, an error would be thrown.

In order to enable this feature on a project, add the Auto promotion levels property to the projectand set Auto creation to Yes.

Disabling the auto creation can be done either by setting Auto creation to No or by removing theproperty altogether.

Auto creation of promotion levels

When the auto creation is enabled, build promotions using a promotion level name will follow thisprocedure:

• if the promotion level is already defined in the branch, it is of course used

• if the promotion level is predefined, it is used to create a new one on the branch and is thenused

• in any other case, an error is displayed

The auto creation of promotion levels is available only through the DSL or throughthe API. It is not accessible through the GUI, where only the promotion levels of thebranch can be selected for a build promotion.

2.5. Managing the buildsThe builds are displayed for a branch.

2.5.1. Filtering the builds

By default, only the 10 last builds of a branch are shown but you have the possibility to create buildfilters in order to change the list of displayed builds for a branch.

The management of filters is done using the Filter buttons at the top-left and bottom-left corners ofthe build list. Those buttons behave exactly the same way. They are not displayed if no build hasever been created for the branch.

Some filters, like Last build per promotion, are predefined, and you just have to select them to applythem.

You can create custom filters using the build filter types which are in the New filter section at theend of the Filter menu. You fill in the filter parameters and apply the filter by clicking on OK.

28

If you give your filter a name, this filter will be saved locally for the current branch and can bereused later on when using the same browser on the same machine account. If you are logged, youcan save this filter for your account at ontrack level so you can reuse it from any workstation.

If the filter is not named, it will be applied all the same but won’t be editable nor being able to besaved.

You can delete and edit any of your own filters.

You can disable any filtering by selection Erase filter. You would then return to the default: last 10builds. Note that the saved filters are not impacted by this operation.

Sharing filters

By selecting the Permalink option in the Filter menu, you update your browser’s URL to includeinformation about the current selected filter. By copying this URL and send to another user, thisother user will be able to apply the same filter than you, even if he did not create it in the firstplace.

Even anonymous (unnamed) filters can be shared this way.

2.5.2. Build links

A build can be linked to other builds. This is particularly useful to represent dependencies betweenbuilds and projects.

Definition of links

If authorized, you’ll see a Build links command at the top of the build page:

Clicking on this link will open a dialog which allows you to define the list of links:

Note that:

29

• usually, you’ll probably edit those links in an automated process using the DSL

• you cannot define or see links to builds for which the project is not accessible to you

Decorations

The build links are displayed as decorations in the build page header:

or in the list of builds:

In both cases, the decoration is clickable. If the target build has been promoted, the associatedpromotions will also be displayed.

If the target project (the project containing the build targeted by the link) has beenconfigured accordingly, the label associated to the build will be displayed insteadof its name.

When the list of dependencies becomes too big, the decoration can be morecumbersome than useful. See the Filtering the build links section below on tips forcustomizing the display of the decoration.

Information

The builds which are linked to a given build or which are used by this build are displayed on thebuild page:

30

Querying

The build links properties can be used for queries:

• in build filters

• in build searches

• in global searches

In all those cases, the syntax to find a match is:

• project, project: or project:* - all builds which contain a build link to the project project

• project:build - all builds which contain a link to the build build in the project project

• project:build* - all builds which contain a link to a build starting with build in the projectproject. The * wildcard can be used in any place.

Filtering the build links

Once a build has too many dependencies, the decoration is too cluttered and cannot be usedcorrectly:

In order to reduce this clutter, you can act at several levels:

• setting some global property to so that only "main" build links are displayed

Only the administrators can set those global settings. Navigate to the Settings in the user menu,navigate to Main build links and edit the Project labels.

Enter a list of project labels which will be considered as "main links" and must always bedisplayed in the build decoration.

• setting the project so that only "main" build links are displayed. Optionally, the global settingscan be overridden.

31

In the source project (the one having the builds with many links to other projects), add the"Main build links" property and edit the list of the labels designated the projects to be alwaysdisplayed.

By default, the global settings and the project settings are merged together. You can overridethis behaviour and take into account only the project settings by checking the "Override globalsettings" checkbox.

Given a project source whose one build depends on product(labeled with main), library (labeledmodule) and many other projects, if one sets the following settings:

• global settings: main

• project source settings: module and no override

Then, only the product dependency is displayed in the decoration:

The last link icon is a link allowing to navigate to the source build and list alldependencies. If the source build would have dependencies which are not flaggedas "main builds", only this icon would appear.

2.5.3. Run info

Builds can be associated with some run info which contains details about the source, the triggerand the duration of this build.

Information about the duration of the builds is shown just right of the build name in the branchpage:

32

or in the list of extensions in the build page:

More details about run information at Run info.

2.6. Managing validation runsValidation runs associate a validation stamp to a build, and a status describing the validation:passed, failed, etc.

Additionally, a run info can be associated with the validation run to show information like aduration, a source or a trigger.

Validation runs can be created manually, but more often, they will be created automatically by a CIengine like Jenkins.

Validation runs can be seen:

• in the branch overview - only their latest status is then visible

• in the branch overview, by clicking on a validation run (at the intersection of a validation stampand a build), you can either create a new validation run (when there is none) or see the list ofthem and their statuses.

33

• in the build page

• in the validation stamp page

For one validation run, one can add comments and update the status to reflect (for example, tomention that a failure in under investigation).

2.6.1. Validation run status

2.6.2. Validation run status comment edition

Authorized users can edit the description entered for a validation run status:

Administrators, project owners & managers, global & project validation managers can edit anycomment. The author of a validation run status change can edit her own comment.

2.6.3. Hyperlinks in descriptions

The free text which is entered as description for the validation run statuses can be automaticallyextended with hyperlinks.

Such link expansions are done for:

• raw hyperlinks in the text

• issue references, depending on the project configuration

For example, if one enters the following text as a validation run status:

For more information, see http://nemerosa.github.io/ontrack/

the link will be rendered as such:

If the project is configured with JIRA, any reference will be converted to a link to the issue. So a textlike

See CLOUD-6800

would be rendered as:

34

Same thing for GitHub or GitLab, a text like:

See #631

will be rendered as:

See Free text annotations for a way to extend this hyperlinking feature.

2.6.4. Validation run data

Some additional data can be associated with a validation run, according to a format defined bytheir validation stamp. For example, passed and total tests, or a coverage percentage.

When creating a validation run, either though the GUI or through any of the API, the data will bevalidated according to the rules defined by the validation stamp.

In particular, the validation run status (passed, warning, failed, etc.) will be computed in somecases, when a threshold of quality is associated with the validation stamp (like a % of passed tests).

In order to use create a validation run with some validation data, you can also use the DSL:

def build = ...build.validationWithText("Text data", "PASSED", "Some text")build.validateWithCHML("CHML data", 1, 10, 100, 1000)build.validateWithNumber("Number data", 80)build.validateWithPercentage("Percentage data", 57)build.validateWithFraction("Fraction data", 99, 100)build.validateWithMetrics("Metrics data", [ "js.bundle" to 1500.56, "js.error" to 111])

For a custom validation data type, you can use:

35

build.validateWithData( "Validation stamp name", [:] // Validation data)

The actual validation data type is taken from the validation stamp.

Run data metrics

While the validation run data is available from Ontrack, it can also be exported to other databases.

As of today, only InfluxDB is supported.

InfluxDB connector must be enabled - see InfluxDB metrics.

In order to export Ontrack validation as points into an InfluxDB database, following elements mustbe configured:

Property Environment variable Default Description

ontrack.influxdb.validation-data

ONTRACK_INFLUXDB_VALIDATION_DATA

true If true, the validationrun data is exported toInfluxDB (true bydefault)

Each point contains the following information:

• name: ontrack_value_validation_data

• tag project - name of the project

• tag branch - name of the branch

• tag build - name of the build

• tag validation - name of the validation

• tag status - status of the validation

• tag type - FQCN of the validation data type

• field values depend on the type of data

2.7. PropertiesAll entities can be associated with properties.

2.7.1. Build link display options property

By default, when a build link is displayed as a decoration in the source build, the target build nameis used.

The target project can be configured to display any label associated with the build instead of using

36

the build name.

In the target project page, select the "Build link display options" property and configure it to use thelabel as display option for the build link decoration:

2.7.2. Message property

The Message property can be associated with any entity in Ontrack.

A message is the association of some text with a type: information, warning or error:

The message is of course displayed in the list of properties:

i. and as a decoration:

37

2.7.3. Meta information property

Some arbitrary meta information properties can be associated with any entity in Ontrack, using aset of values for some names, and optionally some links and categories.

Input

Representation

The list of meta information properties is displayed in the list of properties:

Querying

The meta information properties can be used for queries:

• in build filters

• in build searches

• in global searches

In all those cases, the syntax to find a match is:

38

• name: or name:* - all entities which contain a name meta information property

• name:value - all entities which contain a name meta information property with the exact value

• name:val* - all entities which contain a name meta information property whose value starts withval

• the * wildcard can be used in any place

Neither the link nor the category can be used for the search, only the name and thevalue.

2.7.4. Release property

Also known as label property.

A release label can be associated to any build.

Select the "Release" property and define its label:

The release label is then displayed as a decoration:

• in the build page

• in the build list

39

Chapter 3. Topics

3.1. Branch templatesIn a context where branches are numerous, because the workflow you’re working with implies thecreation of many branches (feature branches, release branches, …), each of them associated with itsown pipeline, creating the branches by hand, even by cloning or copying them would be too muchan effort.

Ontrack gives the possibility to create branch templates and to automatically create branches usingthis template according to a list of branches. This list of branches can either be static or provided bythe SCM.

3.1.1. Template Definition

We distinguish between:

• the branch template definition - which defines a template for a group of branches

• the branch template instances - which are branches based on a template definition

There can be several template definitions per project, each with its own set of template instances.

A template definition is a branch:

• which is disabled (not visible by default)

• which has a special decoration for quick identification in the list of branches for a project

• which has a list of template parameters:

• names

• description

whose descriptions and property values use ${name} expressions where name is a templateparameter.

One can create a template definition from any branch following those rules:

• the user must be authorized to manage branch templates for a project

• the branch must not be already a template instance

• the branch must not have any existing build

3.1.2. Template Instances

A template instance is also a branch:

• which is linked to a template definition

• which has a set of name/values linked to the template parameters

40

• which has a special decoration for quick identification in the list of branches for a project

• it is a "normal branch" as far as the rest of Ontrack is concerned, but:

◦ it cannot be edited

◦ no property can be edited not deleted (they are linked to the template definition)

There are several ways to create template instances:

• from a definition, we can create one instance by providing:

◦ a name for the instance

◦ values for each template parameters

• we can define template synchronization settings linked to a template definition:

◦ source of instance names - this is an extension point. This can be:

▪ a list of names

▪ a list of actual branches from a SCM, optionally filtered. The SCM information is takenfrom the project definition.

◦ an interval of synchronization (manual or every x minutes)

▪ a list of template expressions for each template parameter which define how to map aninstance name into an actual parameter value (see below)

The actual creation of the instance is done using cloning and copy technics already in place inOntrack. The replacement is done using the template parameters and their values (computed ornot).

The manual creation of an instance follows the same rules than the creation of a branch. If thebranch already exists, an error is thrown.

For automatic synchronization from a list of names (static or from a SCM):

• if a previously linked branch does not exist any longer, it is disabled (or deleted directly,according to some additional settings for the synchronization)

• if a branch already exists with the same name, but is not a template instance, a warning isemitted

• if a branch exists already, its descriptions and property values are synched again

• if a branch does not exist, it is created as usual

Reporting about the synchronization (like syncs, errors and warnings) are visible in the Eventssection, in the template definition or in the template instances.

The same synchronization principle applies to branch components: promotion levels, validationstamps and properties.

Finally, at a higher level, cloning a project would also clone the template definitions (not theinstances).

41

3.1.3. Template expressions

Those expressions are defined for the synchronization between template definitions and templateinstances. They bind a parameter name and a branch name to an actual parameter value.

A template expression is a string that contains references to the branch name using the ${…}

construct where the content is a Groovy expression where the branchName variable is bound to thebranch name.

Note that those Groovy expression are executed in a sand box that prevent malicious codeexecution.

Examples

In a SVN context, we can bind the branch SVN configuration (branch locationtag pattern) this way, using simple replacements:

branchLocation: branchName -> /project/branches/${branchName}tagPattern: branchName -> /project/tags/{build:${branchName}*}

In a Jenkins context, we can bind the job name for a branch:

jobName: branchName -> PROJECT_${branchName.toUpperCase()}_BUILD

3.2. Working with SCMSource Control Management (SCM) is at the core of Continuous Integration and ContinuousDelivery chains. It’s therefore not a surprise that they play a major role in Ontrack.

Out of the box, several SCM are supported:

• Git based systems

◦ Generic Git repositories

◦ GitHub Cloud & Enterprise

◦ GitLab

◦ BitBucket Cloud & Server

• Subversion

As of version 3.41, Subversion is now deprecated and support for it will beremoved in version 4.x

3.2.1. SCM Catalog

Ontrack allows to collect information about all registered SCMs and to correlate this informationwith the Ontrack projects.

42

Model

A SCM Catalog entry represents a physical SCM reposotory which is accessible by Ontrack. An entrycontains the following information:

• SCM - type of SCM, like github or bitbucket.

• Configuration - associated configuration in Ontrack to access this repository (URL, credentials,etc.).

• Repository - identifier for this repository. It depends on the type of SCM. For example, forGitHub, it can be name of the repository, like nemerosa/ontrack.

A SCM catalog entry can be:

• linked if an Ontrack project exists which is associated to this repository

• unlinked otherwise

Some Ontrack projects are orphan if they are not associated with any repository accessible byOntrack or if their associated repository is not accessible.

SCM Catalog list

To access the SCM catalog, you must be logged in. You must select the SCM Catalog item in your usermenu.

The list looks like:

The Project column indicates if the entry is linked or unlinked. In case it is linked, a link to theOntrack project page is available.

Filtering is possible using text boxes at the top. You can also navigate back and forth in the list usingthe Previous and Next buttons.

The main filter, labelled Only SCM entries, allows to select the type of entry:

• Only SCM entries - selected by default, shows all repositories accessible by Ontrack

• All entries and orphan projects - additionally, shows the orphan projects

• Linked entries only - shows only the entries which are linked to projects

• Unlinked entries only - shows only the unlinked entries

• Orphan projects only - shows only the orphan projects, as shown below:

In this case, only the link to the project is available since no repository information is accessible.

Orphan project decoration

Since orphan projects are an anomaly (because every Ontrack project should be associated withsome kind of SCM), they get a special decoration, so that they can easily be identified (and fixed):

43

Project labels

If the collection of project labels is enabled, the following labels will be set for projects:

• scm-catalog:entry when the project is associated with a SCM Catalog entry

• scm-catalog:no-entry when the project is NOT associated with a SCM Catalog entry

Those labels can be used to filter orphan projects on the home page for example, or in GraphQLqueries.

GraphQL schema

The SCM Catalog is accessible through the Ontrack GraphQL schema.

At root level, the scmCatalog query allows to query the SCM Catalog itself and to filter the catalog.

For example, to get the list of orphan projects:

{ scmCatalog(link: "ORPHAN") { pageItems { project { name } } }}

or to get the entries which are unlinked:

{ scmCatalog(link: "UNLINKED") { pageItems { entry { scm config repository repositoryPage } } }}

See the GraphQL schema documentation for more fields and filters.

Additionally, the scmCatalogEntry field is available on the Project tpe to provide information aboutany associated SCM Catalog entry:

44

{ projects(name: "ontrack") { scmCatalogEntry { scm config repository repositoryPage } }}

Metrics

The following metrics are available:

• ontrack_extension_scm_catalog_total (gauge) - count of SCM catalog entries + orphan projects

• ontrack_extension_scm_catalog_entries (gauge) - count of SCM catalog entries

• ontrack_extension_scm_catalog_linked (gauge) - count of linked SCM catalog entries

• ontrack_extension_scm_catalog_unlinked (gauge) - count of unlinked SCM catalog entries

• ontrack_extension_scm_catalog_orphan (gauge) - count of orphan projects

Administration

This feature is enabled by default but can be controlled using some administrative jobs:

• Collection of SCM Catalog - gets the list of repositories accessible from Ontrack. Runs once a day.

• Catalog links collection - gets the links between the projects and associated SCM repositories.Runs once a day.

• Collection of SCM Catalog metrics - computes some metrics about the SCM catalog

Specific configuration for GitHub

The GitHub repositories are not collected unless their organization is specifically allowed. Bydefault, none are.

In order to enable the scanning of a GitHub organization, log as administrator, go to the Settings,scroll to the GitHub SCM Catalog section and enter the names of the organizations to authorise forcollection. For example, below, only the nemerosa organization is allowed:

45

3.3. Working with Git

3.3.1. Working with GitHub

GitHub is an enterprise Git repository manager on the cloud or hosted in the premises.

When working with Git in Ontrack, one can configure a project to connect to a GitHub repository.

General configuration

The access to a GitHub instance must be configured.

1. as administrator, go to the GitHub configurations menu

2. click on Create a configuration

3. in the configuration dialog, enter the following parameters:

◦ Name - unique name for the configuration

◦ URL - URL to the GitHub instance. If left blank, it defaults to the https://github.com location

◦ User & Password - credentials used to access GitHub - Ontrack only needs a read access tothe repositories

◦ OAuth2 token - authentication can also be performed using an API token instead of using auser/password pair

The existing configurations can be updated and deleted.

Although it is possible to work with an anonymous user when accessing GitHub,this is not recommended. The rate of the API call will be limited and can lead tosome errors.

Project configuration

The link between a project and a GitHub repository is defined by the GitHub configuration property:

• Configuration - selection of the GitHub configuration created before - this is used for theaccesses

• Repository - GitHub repository, like nemerosa/ontrack

• Indexation interval - interval (in minutes) between each synchronisation (Ontrack maintainsinternally a clone of the GitHub repositories)

• Issue configuration - issue service. If not set or set to "GitHub issues", the issues of the repositorywill be used

Branches can be configured for Git independently.

SCM Catalog configuration

The SCM Catalog feature requires some additional configuration for GitHub. See the specific sectionfor more information.

46

https://github.com

https://github.com

3.3.2. Working with GitLab

GitLab unifies issues, code review, CI and CD into a single UI.

When working with Git in Ontrack, one can configure a project to connect to a GitLab repository.


The access to a GitLab instance must be configured.

1. as administrator, go to the GitLab configurations menu




◦ URL - URL to the GitLab instance (not the repository, the GitLab server)

◦ User & Personal Access Token - credentials used to access GitLab

◦ Ignore SSL Certificate - select Yes if the SSL certificate for your GitLab instance cannot betrusted by default.

You cannot use the account’s password - only Personal Access Tokens aresupported.s



The link between a project and a GitLab repository is defined by the GitLab configuration property:

• Configuration - selection of the GitLab configuration created before - this is used for the access

• Issue configuration - select the source of issues for this project. This can be any ticketing system(like JIRA) or the built-in issue management for this GitLab project (displayed as "GitLab issues")

• Repository - repository name, like nemerosa/ontrack

• Indexation interval - how often, in minutes, must the content of this repository be synchronisedwith Ontrack. Use 0 to not automatically synchronize this repository (this can be donemanually).


3.3.3. Working with BitBucket

BitBucket is an enterprise Git repository manager by Atlassian.

When working with Git in Ontrack, one can configure a project to connect to a Git repositorydefined in BitBucket in order to access to the change logs.

47

https://about.gitlab.com

https://www.atlassian.com/software/bitbucket


The access to a BitBucket instance must be configured.

1. as administrator, go to the BitBucket configurations menu




◦ URL - URL to the Stash instance

◦ User & Password - credentials used to access Stash - Ontrack only needs a read access to therepositories



The link between a project and a Stash repository is defined by the Stash configuration property:

• Configuration - selection of the Stash configuration created before - this is used for the accessand the issues management

• Project - name of the Stash project

• Repository - name of the Stash repository

◦ Indexation interval - interval (in minutes) between each synchronization (Ontrackmaintains internally a clone of the BitBucket repositories)

◦ Issue configuration - configured issue service to use when looking for issues in commits.


3.3.4. Git searches

The Git Ontrack extension provides 3 search indexers:

• looking for Ontrack branches based on the name of the Git branch

• looking for commits (using hashes, authors, description, …)

• looking issues mentioned in commit messages (issue key)

The following configuration properties are available to run the Git search capabilities:

48

# How often the full-reindexation of commit must be performed# The schedule is either a number of minutes, or can use# a notation duration, like 1h, 60m, 1d, etc.# Even for big volumes, 1 hour is more than enough.ontrack.config.search.git.commits.schedule = 1h

# Set to false to disable the automated regular indexation# of Git commits. If disabled, the indexation job is still present# but must be run manually.ontrack.config.search.git.commits.scheduled = true

3.3.5. Working with Subversion

Ontrack allows you to configure projects and branches to work with Subversion in order to:

• get change logs

• search for issues linked to builds and promotions

• search for revisions

Subversion configurations

In order to be able to associate projects and branches with Subversion information, anadministrator must first define one or several Subversion configurations.

As an administrator, go to the user menu and select SVN configurations.

In this page, you can create, update and delete Subversion configurations. Parameters for aSubversion configuration are:

• a name - it will be used for the association with projects

• a URL - Ontrack supports svn, http and https protocols - if the SSL certificate is not recognized bydefault, some additional configuration must be done at system level.

The URL must be the URL of the repository.

• a user and a password if the access to the repository requires authentication

• a tag filter pattern - optional, a regular expression which defines which tags must be indexed

• several URL used for browsing

• indexation interval in minutes (see below)

• indexation start - the revision where to start the indexation from

• issue configuration - issue service associated with this repository

Indexation

Ontrack works with Subversion by indexing some repository information locally, in order to avoidgoing over the network for each Subversion query.

49

This indexation is controlled by the parameters of the Subversion configuration: starting revisionand interval. If this interval is set to 0, the indexation will have to be triggered manually.

Among the information being indexed, the copy of tags is performed and can be filtered if needed.

In order to access the indexation settings of a Subversion configuration, click on the Indexation link.

From the indexation dialog, you can:

• force the indexation from the latest indexed revision

• reindex a range of revisions

• erase all indexed information, and rerun it

The indexations run in background.


You can associate a project with a Subversion configuration by adding the SVN configurationproperty and selecting:

• a Subversion configuration using its name

• a reference path (typically to the trunk)

Like all paths in Subversion configurations of projects and branches, this is arelative path to the root of the repository. Not an absolute URL.

From then on, you can start configuring the branches of the project.

Branch configuration

You can associate a branch with Subversion by adding the SVN configuration property andselecting:

• a path to the branch

• a build revision link and its configuration if any

The path to the branch is relative to the URL of the SVN repository.

The build commit link defines how to associate a build and a location in Subversion (tag, revision,…). This link works in both directions since we need also to find builds based on Subversioninformations.

Build commit links are extension points - the following are available in Ontrack.

Tag name

The build name is considered a tag name in the tags folder for the branch. For example, if thebranch path is /projects/myproject/branches/1.1 then the tags folder is /projects/myproject/tagsand build names will be looked for in this folder.

50

No configuration is needed.

Tag pattern name

The build name is considered a tag name in the tags folder but must follow a given pattern.

Revision name

The build name is always numeric and represent a revision on the branch path.

No configuration is needed.

Revision pattern

The build name has the branch revision in its name, using the {revision} token, following a givenpattern. For example, if the pattern is 2.0.*-{revision}, then all build names must start with 2.0.,following by anything and suffixed by a revision number.

Build / tag synchronization

For branches whose builds are associated with tags, you have the option to enable asynchronization between the builds in Ontrack and the tags in the Subversion branch.

In the branch page, add the SVN synchronisation property and configure it:

Parameter Description

override If set to Yes, the existing builds in Ontrack willbe overridden by the tags in Subversion. If set toNo (the default), the existing builds in Ontrackare never overridden and only new tags aretaken into account.

interval The frequency, in minutes, of thesynchronization. If set to 0, the synchronizationis not automated and must be triggeredmanually.

In order to disable globally the tag/build synchronization, without having tochange manually all the configured branches, add the following entry in theOntrack configuration file and restart Ontrack:

application.yml

ontrack: extension: svn: build-sync-disabled: true

51

3.4. Change logsWhen working with Git or Subversion, you have the opportunity to get a change log between twobuilds of the same project.

3.4.1. Selection

In the branch view, you can select the two boundaries of the change log by:

• clicking on a build row

• clicking while holding the shift key on another build row

Two arrows indicate the current selection:

Note that by default the first and the last build of the current view are selected asboundaries.

The Change log button displays the change log page, which contains four sections:

• general information about the two build boundaries

• the commits (for Git) or revision (for Subversion) section

• the issues section

• the file changes selection

Only the first section (build information) is always displayed - the three other ones are displayedonly when you request them by clicking on one of the corresponding buttons or links.

Note that the issue section is available only if the corresponding SCM configuration (Git orSubversion) is associated with an issue server (like JIRA or GitHub).

3.4.2. Commits/revisions

This section displays the changes between the two build boundaries. For Git, the associated commitgraph is also displayed:

52

3.4.3. Issues

The list of issues associated with the commits between the two build boundaries is displayed here:

53

Chapter 4. File changesThe list of file changes between the two build boundaries is displayed here:

Each file change is associated with the corresponding changes. This includes the list of revisions forSubversion.

Additionally, you can define filters on the file changes, in order to have access to a list of filesimpacted by the change log.

By entering a ANT-like pattern, you can display the file paths which match:

For more complex selections, you can clock on the Edit button and you’ll have a dialog box whichallows you to define:

• a name for your filter

• a list of ANT-like patterns to match

If you are authorized, you can also save this filter for the project, allowing its selection by all users.

54

In the list of filters, you find the filters you have defined and the ones which have been shared forthe whole project. The latter ones are marked with an asterisk (*):

You can update and delete filters. Note that the shared filters won’t be actually updated or deleted,unless you are authorized.

Finally, you can get the unified diff for the selected filter by clicking on the Diff button:

This will display a dialog with:

• the unified diff you can copy

• a permalink which allows you download the diff from another source

You can obtain a quick diff on one file by clicking on the icon at the right of a file in the change log:

4.1. SearchingThe top search box allows to search objects stored in Ontrack like projects, branches or builds,based on their names or on their properties like their label, Git branch, etc. Other items like Gitcommits or issues mentioned in commit messages can also be looked for.

In the top search box, you can:

• select the type of object you look for

• enter search tokens

Upon hitting the Enter key, a search is performed using the token and the given type if selected.

55

The search page is displayed and repeats the type and token.

If no result is found, the search page display a warning.

If exactly 1 result is returned, Ontrack will automatically redirect to the page associated with thisresult.

If there are more than 1 result, their list is displayed, up to 20 results. If more results are available,a More link is displayed, which will load up to 20 more results.

4.1.1. Searching engine

By default, a built-in engine is used to provide results but this engine is quite slow and can bereplaced by a way-faster ElasticSearch based engine.

The ElasticSearch engine will become the default one starting from version 4.0.

See ElasticSearch search engine on how to enable the ElasticSearch based engine.

4.2. Project indicatorsProject indicators are set at project level to hold values about different types of information.

Those types of information are grouped into categories and can have a specific value type, like aboolean (yes/no), a percentage, a numeric value, etc. Types can be entered manually, imported orcomputed.

Every of those indicator values have a level of compliance which computed as a percentage (from0% - very bad - to 100% - very good) according to the configuration of the type. The compliance isalso associated with a rating, from F (very bad) to A (very good).

The indicator values can be entered manually at project level or be computed.

Projects can be grouped together in portfolios which are also associated with a subset of categories.And a global view of all portfolios is associated with a specific subset of categories.

Finally, the history of indicators is retained by Ontrack and can be used to compute trends at thedifferent levels (at project level, at portfolio level or globally).

4.2.1. Indicators authorization model

Having access to a project grants automatically access to viewing the associated indicators.

However, managing indicators, types & portfolios is granted according to the following matrix:

56

Function Administrator

Globalindicatormanager

Globalindicatorportfoliomanager

Projectmanager/owner

Projectindicatormanager

Globalindicators

Yes Yes No No No

Type andcategorymanagement(1)

Yes Yes No No No

Portfoliomanagement

Yes Yes Yes No No

Indicatoredition (2)

Yes Yes No Yes Yes

(1) Imported types & categories are not open to edition. (2) Computed indicators are not open tomanual edition.

4.2.2. Indicator types management

Categories & types can be managed manually by an authorized used using the following usermenus:

• Indicator categories

• Indicator types

A category must have the following attributes:

• id - unique ID for this category among all the categories

• name - display name for this category

A type must have the following attributes:

• id - unique ID for this type among all the type

• name - display name for this type

• link - optional URL for more information about this type

• value type - type of indicator value this type. For example, a percentage or a boolean

• value config - configuration for the value type, used to compute the indicator compliance andrating

Categories and types can also be imported or computed. In such a case, both the category and thetype are associated with a source and they cannot be edited.

Value types

The following value types are available in Ontrack:

57

Type Description Configuration Example

Yes/No Value which can beeither Yes (true) or No(false)

required - flag toindicate if the indicatormust be Yes in order forthe project to be fullycompliant. If required isfalse, the rating will beA is the value is set toYes and D if the value isNo. For a No value on arequired indicator, therating would be F.

"Project should be buildwith Gradle" - becauseof the "should", theindicator requiredvalue is set to false.

Percentage Integer value between0 and 100 inclusive

threshold - pivot value(see example)

higherIsBetter - ahigher percentage inthe value of theindicator indicates abetter quality (seeexample)

"Test coverage" isexpressed as apercentage andhigherIsBetter will beset to true. If thresholdis set to 80:

* any value >= 80% hasa rating of A * forvalues below 80%, therating is computedproportionally, with 0%having a rating of F

"Duplicated code" canalso be expressed as apercentage, but thistime withhigherIsBetter beingset to false. If thresholdis set to 10:

* any value ⇐ 10% hasa rating of A * forvalues above 10%, therating is computedproportionally, with100% having a rating ofF

58

Type Description Configuration Example

Number Integer value >= 0 min - pivot value (seeexample)

max - secondary pivotvalue (see example)

higherIsBetter - ahigher value of theindicator indicates abetter quality (seeexample)

"Number of blockingissues" is expressed asa number withhigherIsBetter beingset to false. If min is 0and max is 10:

* any value set to 0 hasa rating of A * any value>= 10 has a rating of F *for any value inbetween, the rating iscomputedproportionally

A "Number of tests"could be expressed as anumber withhigherIsBetter beingset to true. If min is 100and max is 1000:

* any value ⇐ 100 has arating of F * any value>= 1000 has a rating ofA * for any value inbetween, the rating iscomputedproportionally

Additional value types can be created by registering an extension implementingthe IndicatorValueType interface. See existing value types for examples.

4.2.3. Indicator edition

An authorized user can edit the indicator for a project by going to the Tools menu and select Projectindicators:

All available types are displayed, grouped by categories, and each indicator value is shown togetherwith its value, its rating:

59

If the indicator has a previous value, its previous rating is displayed.

If the indicator is open to edition, the user can click on the pencil icon to edit the value according tothe value type. Upon validation, a new indicator value is stored ; the old value is kept for historyand trend computation.

Comments can be associated with an indicator values. Links & issue references will be rendered aslinks.

An authorized user can also delete the indicator ; this actually register a new null value for theindicator. The historical values are kept.

The history of an indicator can be accessed by clicking on the History icon:

The list of portfolios the project belongs to is displayed at the top of the indicator list:

4.2.4. Indicator portfolios

Portfolios are available in the Indicator portfolios user menu and the associated page displays thelist of already created portfolios.

Each portfolio is associated with a list of selected global categories and each of those categories isassociated with the average rating for all the projects and all the types of this category.

60

Only indicators having an actual value are used to compute the average rating. Theindicators which are not set are not used for the computation and the ratio"number of indicators being set" to the "number of total indicators" is alsodisplayed. This gives an idea about the trust we can have in this average rating.

The minimum ratings are also mentioned if they diverge from the average.

The trend period allows to display the average value from the past, and to compare it with thecurrent value.

The trend computation is currently not correct - see the #793 issue.

Global indicators

Authorized users can edit the list of categories which are displayed on the portfolio overview byclicking on the Global indicators command:

On the associated page, the user can select / unselect the categories which must be displayed for allportfolios:

Closing this page goes back to the portfolio overview.

Management of portfolios

Authorized users can create, edit and delete portfolios.

Creating a portfolio is done using the Create portfolio command:

The portfolio creation dialog requires:

• an ID - must be unique amont all the portfolios and will be used as an identifier. It must

61

https://github.com/nemerosa/ontrack/issues/793

therefore comply with the following regular expression: [a-z0-9:-]+ (lowercase letters, digits, :colon or - dashes). The ID cannot be modified later on.

• a display name

Once created, the portfolio appears on the portfolio overview and can edited or deleted using theappropriate icons:

• the portfolio name is actually a link going to the detailed portfolio view

• the arrow icon goes to the home page and displays only the projects associated to this portfolio

• the edition icon goes to the portfolio edition page

• the deletion icon displays a warning and allows the user to delete the portfolio.

The deletion of a portfolio does not delete any indicator in any project.

Portfolio page

By clicking on the portfolio name in the portfolio overview, you get to a page displaying:

• the list of projects associated with this portfolio

• the list of categories associated with this portfolio

• the average indicator rating for project and for each category

62

As for the portfolio overview, the average rating is computed only using theindicators which are actually set, and the ratio filled vs. total is displayed.

The trend period selector allows you to check the past average values and the associated trends.

Clicking on a project name goes to the project indicators page.

Clicking on a category name goes to a page displaying a detailed view of indicators for all the typesin this category and for all the projects of this portfolio:

In this view, clicking on the icon right to the type name will bring up a page displaying the indicatorvalues for this type for all the projects of this portfolio:

According to your rights, you can edit and delete indicator values from this page.

Portfolio edition

The portfolio edition page allows you to:

63

• edit the portfolio display name (not the ID)

• set a label to select the associated projects

• select the categories associated with this portfolio

The label allows a portfolio to be associated to all projects which have this label. See Project labelsfor more information on how to manage labels.

"Global indicator portfolio managers" and "Global indicator managers" canassociate existing labels to projects but cannot create new labels.

4.2.5. Importing categories and types

While indicator categories and types can be entered manually, it is also possible to import lists ofcategories and their associated types.

In a company, a number of "principles" have been created for projects to comply with. Theyhave been written as Asciidoc and are published as a browsable web site. The associatedprinciples, grouped in pages, have been imported as types (and categories) in Ontrack, byparsing the Asciidoc.

To import categories & types in Ontrack, you need a user allowed to manage types and you can usethe POST /extension/indicators/imports end point, passing a JSON as payload.

For example, with Curl:

curl --user <user> \ -H "Content-Type: application/json" \ -X POST \ http://ontrack/extension/indicators/imports \ --data @payload.json

where:

64

payload.json

{ "source": "principles", "categories": [ { "id": "service-principles", "name": "Service Principles", "types": [ { "id": "java-spring-boot", "name": "SHOULD Use Java & spring boot stack", "required": false, "link": "https://example.com/architecture-principles/latest/service_principles.html#java-spring-boot" } ] } ]}

The source is an ID identifying the nature of this list.

Each category must have an id (unique in Ontrack) and a display name.

Each type must have:

• an id (unique in Ontrack)

• a display name

• a required flag - as of now, only "Yes/No" value types are supported

• an optional link to some external documentation

Upon import:

• new existing & types are created

• existing categories & types are updated and associated indicators are left untouched

• removed categories & types are deleted, and associated indicators are deleted

Imported categories & types cannot be edited.

4.2.6. Computing indicators

It is possible to define some types whose value is not entered manually but is computed by Ontrackitself.

You do so by registering an extension which implements the IndicatorComputer interface, or theAbstractBranchIndicatorComputer class when the value must be computed from the "main branch" ofa project.

65

See the documentation of those two types for more information.

The SonarQubeIndicatorComputer extension is an example of such an implementation.

Computed categories & types cannot be edited, and their values cannot be editedmanually.

66

Chapter 5. Administration

5.1. SecurityThe Ontrack security is based on accounts and account groups, and on authorizations granted tothem.

5.1.1. Concepts

Each action in Ontrack is associated with an authorisation function and those functions are groupedtogether in roles which are granted to accounts and account groups.

An account can belong to several account groups and his set of final authorisation functions will bethe aggregation of the rights given to the account and to the groups.

5.1.2. Roles

As of now, only roles can be assigned to groups and accounts, and the list of rolesand their associated functions is defined by Ontrack itself.

Ontrack distinguishes between global roles and project roles.

Extensions can contribute to built-in roles and functions - see Extending the security for details.

Global roles

An ADMINISTRATOR has access to all the functions of Ontrack, in all projects. At least such a roleshould be defined.

By default, right after installation, a default admin account is created with theADMINISTRATOR role, having admin as password. This password should be changedas soon as possible.

A CREATOR can create any project and can, on all projects, configure them, create branches,manage branch templates, create promotion levels and validation stamps. This role should beattributed to service users in charge of automating the definition of projects and branches.

An AUTOMATION user can do the same things than a CREATOR but can, on all projects,additionally edit promotion levels and validation stamps, create builds, promote and validate them,synchronize branches with their template, manage account groups and project permissions. Thisrole is suited for build and integration automation (CI).

A CONTROLLER can, on all projects, create builds, promote and validate them, synchronizebranches with their template. It is suited for a basic CI need when the Ontrack structure alreadyexists and does not need to be created.

A GLOBAL VALIDATION MANAGER can manage validation stamps across all projects.

67

A READ_ONLY can view all projects, but cannot perform any action on them.

The global roles can only be assigned by an administrator, in the Account management page, bygoing to the Global permissions command.

A global permission is created by associating:

• a permission target (an account or a group)

• a global role

Creation:

1. type the first letter of the account or the group you want to add a permission for

2. select the account or the group

3. select the role you want to give

4. click on Submit

Global permissions are created or deleted, not updated.

Project roles

A project OWNER can perform all operations on a project but to delete it.

A project PARTICIPANT has the right to see a project and to add comments in the validation runs(comment + status change).

A project VALIDATION_MANAGER can manage the validation stamps and create/edit thevalidation runs.

A project PROMOTER can create and delete promotion runs, can change the validation runsstatuses.

A project PROJECT_MANAGER cumulates the functions of a PROMOTER and of aVALIDATION_MANAGER. He can additionally manage branches (creation / edition / deletion) andthe common build filters. He can also assign labels to the project.

A project READ_ONLY user can view this project, but cannot perform any action on it.

Only project owners, automation users and administrators can grant rights in a project.

In the project page, select the Permissions command.

A project permission is created by associating:

• a permission target (an account or a group)

• a project role

Creation:

1. type the first letter of the account or the group you want to add a permission for

68

2. select the account or the group

3. select the role you want to give

4. click on Submit

Project permissions are created or deleted, not updated.

5.1.3. Accounts

Accounts are created with either:

• built-in authentication, with a password stored and encrypted in Ontrack itself

• LDAP setup

Built-in accounts

An administrator can create accounts. He must give them:

• a unique name

• a unique email

• a display name

• an initial password

Any user can change his own password by going to the Change password menu.

The administrator can give an account a list of global or project roles.

LDAP accounts

Accounts whose authentication is managed by the LDAP are not created directly but are insteadcreated at first successful login.

As for the other types of accounts, the administrator can give them a list of global or project roles.

5.1.4. Account groups

An administrator can create groups using a name and a description, and assign them a list of globalor project roles.

An account can be assigned to several groups.

If LDAP is enabled, some LDAP groups can be mapped to the account groups.

5.1.5. General settings

By default, all users (including anonymous ones) have access to all the projects, at least in read onlymode.

You can disable this anonymous access by goint go to the Settings and click the Edit button in the

69

General section. There you can set the Grants project view to all option to No.

5.1.6. Extending the security

Extensions can extend the security model beyond what if defined in the Ontrack core. SeeExtending the security for more details.

5.2. LDAP setupIt is possible to enable authentication using a LDAP instance and to use the LDAP-defined groups tomap them against Ontrack groups.

5.2.1. LDAP general setup

As an administrator, go to the Settings menu. In the LDAP settings section, click on Edit and fill thefollowing parameters:

• Enable LDAP authentication: Yes

• URL: URL to your LDAP

• User and Password: credentials needed to access the LDAP

• Search base: query to get the user

• Search filter: filter on the user query

• Full name attribute: attribute which contains the full name, cn by default

• Email attribute: attribute which contains the email, email by default

• Group attribute: attribute which contains the list of groups a user belongs to, memberOf by default

• Group filter: optional, name of the OU field used to filter groups a user belongs to

As of version 2.14, the list of groups (indicated by the memberOf attribute or anyother attribute defined by the Group attribute property) is not searched recursivelyand that only the direct groups are taken into account.

For example:

70

The settings shown above are suitable to use with an Activate Directory LDAPinstance.

5.2.2. LDAP group mapping

A LDAP group a user belongs to can be used to map onto an Ontrack group.

As an administrator, go to the Account management menu and click on the LDAP mappingcommand.

This command is only available if the LDAP authentication has been enabled in thegeneral settings.

To add a new mapping, click on Create mapping and enter:

• the name of the LDAP group you want to map

71

• the Ontrack group which must be mapped

For example, if you map the ontrack_admin LDAP group to an Administrators group in Ontrack, anyuser who belongs to ontrack_admin will automatically be assigned to the Administrators groupwhen connecting.

This assignment based on mapping is dynamic only, and no information is storedabout it in Ontrack.

Note that those LDAP mappings can be generated using the DSL.

Existing mappings can be updated and deleted.

5.3. Administration consoleThe Administration console is available to the Administrators only and is accessed through the usermenu.

It allows an administrator to:

• manage the running jobs

• see the state of the external connections

• see the list of extensions

5.3.1. Managing running jobs

The list of all registered jobs is visible to the administrator. From there, you can see:

• general informations about the jobs: name, description

• the run statistics

Filtering the jobs

The following filters are available:

• status

• idle jobs: jobs which are scheduled, but not running right now

• running jobs: jobs which are currently running

• paused jobs: jobs which are normally scheduled but which have been paused

• disabled jobs: jobs which are currently disabled

72

• invalid jobs: jobs which have been marked as invalid by the system (because their context is nolonger applicable for example)

• category and type of the job

• error status - jobs whose last run raised an error

• description - filtering using a search token on the job description

Controlling the jobs

For one job, you can:

• force it to run now, if not already running or disabled

• pause it if it is a scheduled job

• resume it if it was paused

• remove it if it is an invalid job

You can also pause or resume all the jobs using the Actions menu. All jobs currently selectedthrough the filter will be impacted.

The same Actions menu allows also to clear the current filter and to display all the jobs.

5.3.2. External connections

5.3.3. List of extensions

5.4. Application log messagesThe list of application log messages is available to the Administrators only and is accessed throughthe user menu.

It allows an administrator to manage the error messages.

The log items are displayed from the most recent to the oldest. By default, only 20 items aredisplayed on a page. You can navigate from page to page by using the Previous and Next buttons.

You can filter the log entries you want to see by using the filter fields:

73

• after - only log entries created after this time will be displayed

• before - only log entries created before this time will be displayed

• authentication - you can enter the name of a user, and only errors having occurred to this userwill be displayed.

• free text - this text will be searched in all other fields of the log message: details, information,type.

Click on the Filter button to activate the filter and on Reset filter to delete all fields.

You can refresh the log entries by clicking the Refresh log button.

Finally, you can remove all log entries (all of them, independently from the current filter) byclicking on the Delete all entries button. A confirmation will be asked.

Log entries are kept only for 7 days. This delay can be configured. See thedocumentation for more information.

You can click on the Details… button of a log entry to get more details about the error:

If available, the stack trace can be selected and copied (actually, like any other element of thisdialog). Dismiss the dialog by clicking on the OK button.

5.5. Status pageThe stage page is available to the Administrators only and is accessed through the user menu.

It displays two sections:

74

• the health of Ontrack itself, based on Spring Boot health information

• the statuses of all the connectors

For example:

This information is also available through several end points:

• /admin/status - health + connectors

• /manage/health - health only (regular Spring Boot health end point)

• /manage/connectors - connectors only - extra management end point providedby Ontrack

75

https://docs.spring.io/spring-boot/docs/2.1.9.RELEASE/reference/htmlsingle/#production-ready-health

Chapter 6. Integration

6.1. ElasticSearch search engineEnable the ElasticSearch engine by setting the ontrack.config.search.engine configuration propertyto elasticsearch.

Additionally, the spring.elasticsearch.rest.uris property must be set to specify whereElasticSearch is deployed, additionally to any credentials being needed (see the Spring Bootdocumentation).

6.1.1. ElasticSearch configuration properties

See Configuration properties for more search configuration properties.

6.1.2. ElasticSearch indexers

See Extending the search for extending search capabilities of Ontrack.

6.2. Integration with JenkinsThe best way to integration Ontrack with your Jenkins instance is to use the Ontrack plug-in.

Look at its documentation for details about its configuration and how to use it.

6.3. MonitoringOntrack is based on Spring Boot and exports metrics and health indicators that can be used tomonitor the status of the applications.

6.3.1. Health

The /manage/health end point provides a JSON tree which indicates the status of all connectedsystems: JIRA, Jenkins, Subversion repositories, Git repositories, etc.

Note than an administrator can have access to this information as a dashboard in the Adminconsole (accessible through the user menu).

6.3.2. Metrics

Since version 2.35 / 3.35, Ontrack uses the Micrometer framework to managemetrics, in order to allow a better integration with Spring Boot 2.

See Metrics migration for information about the migration.

By default, Ontrack supports two external registries for metrics:

76

https://docs.spring.io/spring-boot/docs/2.1.9.RELEASE/reference/htmlsingle/#boot-features-connecting-to-elasticsearch-rest

https://docs.spring.io/spring-boot/docs/2.1.9.RELEASE/reference/htmlsingle/#boot-features-connecting-to-elasticsearch-rest

https://wiki.jenkins-ci.org/display/JENKINS/Ontrack+plugin


http://projects.spring.io/spring-boot

http://micrometer.io/


• InfluxDB

• Prometheus

The export to those engine is disabled by default and must be enabled explicitely.

For example, for Prometheus, you can use the management.metrics.export.prometheus.enabled

property or the MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED environment variable.

For the rest of the configuration, you have to consult the Spring Boot or Micrometer documentation.

List of metrics

The list of Ontrack specific metrics and their tags and values is available using the/manage/ontrack_metrics endpoint. Note that this endpoint needs authenticationand some administrator privileges.

General metrics:

• ontrack_error (counter) - number of error (the type tag contains the type of error)

Statistics about the objects stored by Ontrack:

• ontrack_entity_project_total (gauge) - total number of projects

• ontrack_entity_branch_total (gauge) - total number of branches

• ontrack_entity_build_total (gauge) - total number of builds

• ontrack_entity_promotionLevel_total (gauge) - total number of promotion levels

• ontrack_entity_promotionRun_total (gauge) - total number of promotion runs

• ontrack_entity_validationStamp_total (gauge) - total number of validation stamps

• ontrack_entity_validationRun_total (gauge) - total number of validation runs

• ontrack_entity_validationRunStatus_total (gauge) - total number of validation run statuses

• ontrack_entity_property_total (gauge) - total number of properties

• ontrack_entity_event_total (gauge) - total number of events

General metrics about jobs:

• ontrack_job_count_total (gauge) - total number of jobs

• ontrack_job_running_total (gauge) - total number of running jobs

• ontrack_job_error_total (gauge) - total number of jobs in error

• ontrack_job_paused_total (gauge) - total number of paused jobs

• ontrack_job_disabled_total (gauge) - total number of disabled jobs

• ontrack_job_invalid_total (gauge) - total number of invalid jobs

• ontrack_job_error_count_total (gauge) - total number of errors among all the jobs

Information about individual jobs:

77

• ontrack_job_duration_ms (timer) - duration of the execution of the job

• ontrack_job_run_count (counter) - number of times a job has run

• ontrack_job_errors (counter) - number of errors for this job

Job metrics have the following tags:

• job-category - category of the job

• job-type - type of the job

• job-id - ID of the job

Run information:

• ontrack_run_build_time_seconds (timer) - duration of a run for a build. It is associated withproject and branch tags.

• ontrack_run_validation_run_time_seconds (timer) - duration of a run for a validation run. It isassociated with project, branch, validation_stamp and status tags.

More details at Run info.

Information about connectors (Jenkins, JIRA, Git, etc.):

• ontrack_connector_count (gauge) - number of connectors

• ontrack_connector_up (gauge) - number of UP connectors

• ontrack_connector_down (gauge) - number of DOWN connectors

Connector metrics have the following tags:

• type - type of connector (like jenkins, jira, …)

InfluxDB metrics

This is an experimental feature. In the future, especially when migrating to SpringBoot 2.0, the configuration might change. The feature is very likely to stay though.

The InfluxDB extension is shipped by default with Ontrack but is activated only if some propertiesare correctly set:


ontrack.influxdb.enabled

ONTRACK_INFLUXDB_ENABLED

false Enables the export ofrun info to InfluxDB

ontrack.influxdb.uri ONTRACK_INFLUXDB_URI "http://localhost:8086" URI of the InfluxDBdatabase

Optionally, the following properties can also be set:

78


ontrack.influxdb.username

ONTRACK_INFLUXDB_USERNAME

"root" User name to connectto the InfluxDBdatabase

ontrack.influxdb.password

ONTRACK_INFLUXDB_PASSWORD

"root" Password to connect tothe InfluxDB database

ontrack.influxdb.db ONTRACK_INFLUXDB_DB "ontrack" Name of the InfluxDBdatabase

ontrack.influxdb.create

ONTRACK_INFLUXDB_CREATE

true If true, the database iscreated at startup

ontrack.influxdb.ssl.host-check

ONTRACK_INFLUXDB_SSL_HOST_CHECK

true If false, disables hostchecking forcertificates. Thisshould not be used fora production system!

ontrack.influxdb.log ONTRACK_INFLUXDB_LOG NONE Level of log whencommunicating withInfluxDB. Possiblevalues are: NONE, BASIC,HEADERS and FULL

When an InfluxDB connector is correctly set, some Ontrack information is automatically sent tocreate timed values:

• run info

• validation run data

6.4. Management end pointOntrack exposes additional Spring Boot actuator end points.

6.4.1. Connectors

The connectors are used to connect to external systems like Jenkins, JIRA, Git repositories, etc. Themanage/connectors end point allows an administrator to get information about the state of thoseconnectors.

The connector statuses are also exposed as metrics.

6.5. GraphQL supportSince version 2.29, Ontrack provides some support for GraphQL.

While most of the Ontrack model is covered, only the query mode is supportedright now. Support for mutations might be integrated in later releases.

79

http://graphql.org/

The GraphQL end point is available at the /graphql context path. For example, if Ontrack isavailable at http://localhost:8080, then the GraphQL end point is available at http://localhost:8080/graphql.

Ontrack supports all capabilities of GraphQL schema introspection.

Example of a GraphQL query, to get the list of branches for a project:

{ projects (id: 10) { branches { id name } }}

6.6. Calling with CurlOne basic way to integration with the GraphQL interface of Ontrack is to use Curl.

Given the following file:

query.json

{ query: "{ projects (id: $projectId) { branches { id name }}}", variables: { projectId: 10 }}

You can POST this file to the Ontrack GraphQL end point, for example:

curl -X POST --user user http://localhost:8080/graphql --data @query.json -H "Content-Type: application/json"

6.7. Using the DSLThe simplest way is to use the Ontrack DSL to run a query:

80


http://localhost:8080/graphql

http://localhost:8080/graphql

https://curl.haxx.se/

def result = ontrack.graphQLQuery( '''{ projects (id: $projectId) { id branches { id name } } }''', [ projectId: 10, ])

assert result.errors != null && result.errors.emptyassert result.data.projects.size() == 1assert result.data.projects.get(0).id == 10

See the graphQLQuery documentation for more details.

6.8. GraphiQL supportOntrack supports GraphiQL and allows to experiment with Ontrack GraphQL queries directly inyour browser.

You can access the GraphiQL IDE page by clicking on the GraphiQL command in the top right cornerof the home page of Ontrack:

You can then type and experiment with your GraphQL queries:

The access rights used for your GraphQL queries are inherited from your Ontrackconnection. Connect with your user in Ontrack before switching to the GraphiQLIDE. Login in from within GraphiQL is not supported yet.

81

https://github.com/graphql/graphiql

6.9. Extending the GraphQL schemaThe core Ontrack GraphQL query schema can be extended by custom extensions.

See Extending GraphQL for more information.

6.10. Encryption serviceSecrets used by Ontrack are encrypted using keys managed by a ConfidentialStore.

Ontrack provides three types of storage:

• file based storage (default)

• Vault storage

• database storage

If needed, you can also create your own form of storage using extensions.

6.10.1. Selection of the confidential store

The selection of the confidential store is done at startup time using the ontrack.config.key-storeconfiguration property.

It defaults to file (see below).

Additional configuration properties might be needed according to the type of store.

6.10.2. File confidential store

This is the default store but its selection can be made explicit by setting the ontrack.config.key-store configuration property to file.

This store will store the keys in the working directory under the security/secrets subfolder.

A master.key file is used to encrypt the individual keys themselves, so two files will be typicallypresent:

• master.key

• net.nemerosa.ontrack.security.EncryptionServiceImpl.encryption

6.10.3. JDBC confidential store

This store manages the keys directly in the Ontrack database. It can be selected by setting theontrack.config.key-store configuration property to jdbc.

This store is intrinsically insecure since it stores the keys in the same locationwhere the secrets are themselves stored.

No further configuration is needed.

82

https://www.vaultproject.io/

6.10.4. Vault confidential store

By setting the ontrack.config.key-store configuration property to vault, Ontrack will use Vault tostore its encryption keys.

Following configuration properties are available to configure the connection to Vault:

Property Default Description

ontrack.config.vault.uri http://localhost:8200 URI to the Vault end point

ontrack.config.vault.token test Token authentication

ontrack.config.vault.prefix secret/ontrack/key Path prefix for the storage ofthe keys

WARNING: As of now, thesupport for Vault storage isexperimental and is subject tochange in later releases. Inparticular, the authenticationmechanism might change.

6.10.5. Migrating encryption keys

In the event you want to migrate the encryption keys from one type of storage to another, followthis procedure.

In the procedure below, ${ONTRACK_URL} designates the Ontrack URL and${ONTRACK_ADMIN_USER} the name of an Ontrack user which has the ADMINISTRATORrole.

Using the initial configuration for the store, start by exporting the key:

curl ${ONTRACK_URL}/admin/encryption \ --user ${ONTRACK_ADMIN_USER} \ --output ontrack.key

This command will export the encryption key into the local ontrack/key file.

Start Ontrack using the new configuration.

There might be errors are startup, when some jobs start to collect some data fromthe external applications. Those errors can be safely ignored for now.

Import the key file into Ontrack:

83

https://www.vaultproject.io/


curl ${ONTRACK_URL}/admin/encryption \ --user ${ONTRACK_ADMIN_USER} \ -X PUT \ -H "Content-Type: text/plain" \ --data @ontrack.key

Restart Ontrack.

6.10.6. Losing the encryption keys

In case you lose the encryption keys, the consequence will be that the secrets stored by Ontrackwon’t be able to be decrypted. This will typically make the external applications your Ontrackinstance connects to unreachable.

The only to fix this is to reenter the secrets.

Some pages might not display correctly if some applications are not reachable.

6.10.7. Adding custom confidential store

See Extending confidential stores.

6.11. Run infoBuilds and validation runs can be associated with some run information which contains:

• source of the information, like a Jenkins job

• trigger of the information, like a SCM change

• duration of the collection for the information (like the duration of a job)

6.11.1. Collection of run info

Run info can be attached to a build or a validation run using the REST API or the DSL of Ontrack.

This is typically done at CI engine level, where a solution like the Ontrack Jenkins plugin simplifiesthe operation.

When using the Jenkins pipeline as code, the ontrackBuild and ontrackValidate steps will do thisautomatically, so nothing to change. For example:

post { success { ontrackBuild project: "xxx", branch: "1.0", build: version }}

84

https://plugins.jenkins.io/ontrack

When using the DSL, the run info must be specified explicitly. The Jenkins plugin provides ajenkins.runInfo binding which contains some run into ready to be passed:

ontrackScript script: """ def b = ontrack.build(...) b.runInfo = jenkins.runInfo """

6.11.2. Displaying the run info

The run info is displayed in the branch overview and the build page for builds, and in thevalidation stamp and the validation run pages for the validation runs.

It is of course available through the REST API, GraphQL and the DSL.

6.11.3. Exporting the run info

While the run info is available from Ontrack, it can also be exported to other databases.

As of today, only InfluxDB is supported.

Exporting the run info to InfluxDB

InfluxDB connector must be enabled - see InfluxDB metrics.

In order to export Ontrack run info as points into an InfluxDB database, following elements mustbe configured:


ontrack.influxdb.run-info

ONTRACK_INFLUXDB_RUN_INFO

true If true, the run info isexported to InfluxDB(true by default)

Exporting the run info using extensions

It’s possible to manage your own export of run info by creating a RunInfoListener component.

See Run info listeners for more information.

Restoring the exported run info

It’s possible to run the "Run info restoration" manual system job in order to re-export all run infosto the registered exporters.

6.12. Integration with SonarQubeIt’s possible to configure projects so that any build which has been scanned by SonarQube getssome measures registered in Ontrack and those same measures can then be exported to some event

85

storage like InfluxDB.

6.12.1. General configuration

One configuration must be created per SonarQube server you want to integrate.

As an administrator, you need to select "SonarQube configurations" in your user menu and createSonarQube configurations by setting three parameters:

• Name - name for this configuration

• URL - the root URL of the SonarQube server

• Token - an authentication token to get information from SonarQube

6.12.2. Global settings

As an administrator, go to the Settings menu. In the SonarQube section, click on Edit and fill thefollowing parameters:

Name Default value Description

Measures critical_violations, coverage List of SonarQube metric namesto collect. They can becompleted or overridden atproject level.

Disabled No Global flag to disable thecollection of SonarQubemeasures

6.12.3. Project configuration

In order to enable the collection of SonarQube measures for a project, it must be associated withthe "SonarQube" property.

The property needs the following parameters:

86

https://docs.sonarqube.org/latest/user-guide/user-token/

Name Default value Description

Configuration Required SonarQube serverconfiguration

Key Required Key of the project in SonarQube(typically group:artifact)

Validation stamp sonarqube Name of the validation stamp,which, when granted to a build,triggers the collection ofSonarQube measures.

Measures Empty List of SonarQube metric namesto collect for this project,additionally to those definedglobally.

Override No If set to Yes, this causes the listof metric names defined by thevalue of Measures to takeprecedence on the globalsettings.

Branch model No If set to Yes, restricts thecollection of SonarQubemeasures to the builds whichare branch which comply withthe project branch model.

Branch pattern Empty If set, it defines a regularexpression to use against thebranch name (or Git path)

The Branch model and Branch pattern can be combined together.

6.12.4. Build measures

Once SonarQube measures have been collected for a build, they are available in the Informationsection of the build page.

6.12.5. Export of measures

Once SonarQube measures have been collected for a build, they are automatically exported asmetrics, like InfluxDB, if enabled.

See InfluxDB metrics for more information.

The list of metrics are the following.

Collection metrics

All metrics linked to the collection of the measures are associated with the following tags:

• project - name of the build’s project

87

• branch - name of the build’s branch

• uri - SonarQube URL

Following metrics are collected:

• ontrack_sonarqube_collection_started_count - counter - number of times a collection is started

• ontrack_sonarqube_collection_success_count - counter - number of times a collection is a success

• ontrack_sonarqube_collection_error_count - counter - number of times a collection is a failure

• ontrack_sonarqube_collection_time - timer - histogram of times for the collections

Missing measures

• ontrack_sonarqube_collection_none - counter - number of times a measure is collected but nonesuch measure was available in SonarQube

This metric is associated with following tags:

• project - name of the build’s project

• branch - name of the build’s branch

• uri - SonarQube URL

• measure - name of the measure

Measures

Measures associated to builds are exported to metrics using:

• metric name - ontrack_sonarqube_measure

• tags:

◦ project - name of the build’s project

◦ branch - name of the build’s branch

◦ build - name of the build for which measures are collected

◦ version - display name of the build

◦ status - the validation run status reported for the stamp

◦ measure - name of the measure

• value - value of the measure

• timestamp of the metric is the creation time of the build

88

Chapter 7. DSLOntrack provides several ways of interaction:

• the graphical user interface (GUI)

• the REST API (UI - also used internally by the GUI)

• the Domain Specific Language (DSL)

Using the DSL, you can write script files which interact remotely with your Ontrack instance.

7.1. DSL UsageIn some cases, like when using the Ontrack Jenkins plug-in, you can just write some Ontrack DSL touse it, because the configuration would have been done for you.

In some other cases, you have to set-up the Ontrack DSL environment yourself.

7.1.1. Embedded

You can embed the Ontrack DSL in your own code by importing it.

Using Maven:

<dependencies> <groupId>net.nemerosa.ontrack</groupId> <artifactId>ontrack-dsl</artifactId> <version>{{ontrack-version}}</version></dependencies>

Using Gradle:

compile 'net.nemerosa.ontrack:ontrack-dsl:{{ontrack-version}}'

7.1.2. Standalone shell

See DSL Tool.

7.1.3. Connection

Before calling any DSL script, you have to configure an Ontrack instance which will connect to yourremote Ontrack location:

89

https://github.com/nemerosa/ontrack-jenkins

import net.nemerosa.ontrack.dsl.*;

String url = "http://localhost:8080";String user = "admin";String password = "admin";

Ontrack ontrack = OntrackConnection.create(url) // Logging .logger(new OTHttpClientLogger() { public void trace(String message) { System.out.println(message); } }) // Authentication .authenticate(user, password) // OK .build();

7.1.4. Retry mechanism

By default, if the remote Ontrack API cannot be reached, the calls will fail. You can enable a retrymechanism by defining a maximum number of retries and a delay between the retries (defaults to10 seconds):

Ontrack ontrack = OntrackConnection.create(url) // ... // Max retries .maxTries(10) // Delay between retries (1 minute here) .retryDelaySeconds(60) // OK .build();

7.1.5. Calling the DSL

The Ontrack DSL is expressed through Groovy and can be called using the GroovyShell:

90

import groovy.lang.Binding;import groovy.lang.GroovyShell;

Ontrack ontrack = ...

Map<String, Object> values = new HashMap<>();values.put("ontrack", ontrack);Binding binding = new Binding(values);

GroovyShell shell = new GroovyShell(binding);

Object shellResult = shell.evaluate(script);

7.2. DSL Samples

7.2.1. DSL Security

The DSL allows to manage the accounts and the account groups.

Management of accounts

To add or update a built-in account:

ontrack.admin.account( "dcoraboeuf", // Name "Damien Coraboeuf", // Display name "[email protected]", // Email "my-secret-password", // Password [ // List of groups (optional) "Group1", "Group2" ])

To get the list of accounts:

def accounts = ontrack.admin.accountsdef account = accounts.find { it.name == 'dcoraboeuf' }assert account != nullassert account.fullName == "Damien Coraboeuf"assert account.email == "[email protected]"assert account.authenticationSource.allowingPasswordChangeassert account.authenticationSource.id == "password"assert account.authenticationSource.name == "Built-in"assert account.role == "USER"assert account.accountGroups.length == 2

91

LDAP accounts cannot be created directly. See the documentation for more details.

Account permissions

To give a role to an account:

ontrack.admin.setAccountGlobalPermission( 'dcoraboeuf', "ADMINISTRATOR)ontrack.project('PROJECT')ontrack.admin.setAccountProjectPermission( 'PROJECT', 'dcoraboeuf', "OWNER)

To get the list of permissions for an account:

def permissions = ontrack.admin.getAccountProjectPermissions('PROJECT', 'dcoraboeuf')assert permissions != nullassert permissions.size() == 1assert permissions[0].id == 'OWNER'assert permissions[0].name == 'Project owner'

Management of account groups

To add or update an account group:

ontrack.admin.accountGroup('Administrators', "Group of administrators")

To get the list of groups:

def groups = ontrack.admin.groupsdef group = groups.find { it.name == 'Administrators' }assert group.name == 'Administrators'assert group.description == "Group of administrators"

Account group permissions

To give a role to an account group:

92

ontrack.admin.setAccountGroupGlobalPermission( 'Administrators', "ADMINISTRATOR")ontrack.project('PROJECT')ontrack.admin.setAccountGroupProjectPermission( 'PROJECT', 'Administrators', "OWNER")

To get the list of permissions for an account group:

def permissions = ontrack.admin.getAccountGroupProjectPermissions('PROJECT','Administrators')assert permissions != nullassert permissions.size() == 1assert permissions[0].id == 'OWNER'assert permissions[0].name == 'Project owner'

DSL LDAP mapping

The LDAP mappings can be generated using the DSL.

To add or update a LDAP mapping:

ontrack.admin.ldapMapping 'ldapGroupName', 'groupName'

To get the list of LDAP mappings:

LDAPMapping mapping = ontrack.admin.ldapMappings[0]assert mapping.name == 'ldapGroupName'assert mapping.groupName == 'groupName'

7.2.2. DSL Images and documents

Some resources can be associated with images (like promotion levels and validation stamps) andsome documents can be downloaded.

When uploading a document or an image, the DSL will accept any object (see below), optionallyassociated with a MIME content type (the content type is either read from the source object ordefaults to image/png).

The object can be any of:

• a URL object - the MIME type and the binary content will be downloaded using the URL - the URLmust be accessible anonymously

• a File object - the binary content is read from the file and the MIME type must be provided

93

• a valid URL string - same as an URL - see above

• a file path - same as a File - see above

For example:

ontrack.project('project') { branch('branch') { promotionLevel('COPPER', 'Copper promotion') { image '/path/to/local/file.png', 'image/png' } }}

Document and image downloads return a Document object with has two properties:

• content - byte array

• type - MIME content type

For example, to store a promotion level’s image into a file:

File file = ...def promotionLevel = ontrack.promotionLevel('project', 'branch', 'COPPER')file.bytes = promotionLevel.image.content

7.2.3. DSL Change logs

When a branch is configured for a SCM (Git, Subversion), a change log can be computed betweentwo builds and following collections can be displayed:

• revisions or commits

• issues

• file changes

Change logs can also be computed between builds which belong to differentbranches, as long as they are in the same project. This is only supported for Git, notfor Subversion.

Getting the change log

Given two builds, one gets access to the change log using:

def build1 = ontrack.build('proj', 'master', '1')def build2 = ontrack.build('proj', 'master', '2')

def changelog = build1.getChangeLog(build2)

94

The returned change log might be null if the project and branches are notcorrectly configured.

On the returned ChangeLog object, one can access commits, issues and file changes.

Commits

The list of commits can be accessed using the commits property:

changeLog.commits.each { println "* ${it.shortId} ${it.message} (${it.author} at ${it.timestamp})"}

Each item in the commits collection has the following properties:

• id - identifier, revision or commit hash

• shortId - short identifier, revision or abbreviated commit hash

• author - name of the committer

• timestamp - ISO date for the commit time

• message - raw message for the commit

• formattedMessage - HTML message with links to the issues

• link - link to the commit

This covers only the common attributes provided by Ontrack - additionalproperties are also available for a specific SCM.

Issues

The list of issues can be accessed using the issues property:

changeLog.issues.each { println "* ${it.displayKey} ${it.status} ${it.summary}"}

Each item in the issues collection has the following properties:

• key - identifier, like 1

• displayKey - display key (like #1)

• summary - short title for the issue

• status - status of the issue

• url - link to the issue

95

This covers only the common attributes provided by Ontrack - additionalproperties are also available for a specific issue service.

Exporting the change log

The change log can also be exported as text (HTML and Markdown are also available):

String text = changeLog.exportIssues( format: 'text', groups: [ 'Bugs' : ['defect'], 'Features' : ['feature'], 'Enhancements': ['enhancement'], ], exclude: ['design', 'delivery'])

• format can be one of text (default), html or markdown

• groups allows to group issues per type. If not defined, no grouping is done

• exclude defines the types of issues to not include in the change log

• altGroup defaults to Other and is the name of the group where remaining issues do not fit.

File changes

The list of file changes can be accessed using the files property:

changeLog.files.each { println "* ${it.path} (${it.changeType})"}

Each item in the files collection has the following properties:

• path - path changed

• changeType - nature of the change

• changeTypes - list of changes on this path

This covers only the common attributes provided by Ontrack - additionalproperties are also available for a specific SCM.

7.2.4. DSL Branch template definitions

Using the template(Closure) method on a branch, one can define the template definition for abranch.

For example:

96

template { parameter 'gitBranch', 'Name of the Git branch', 'release/${sourceName}' fixedSource '1.0', '1.1'}

• def parameter(String name, String description = '', String expression = '') — defines aparameter for the template, with an optional expression based on a source name

• def fixedSource(String… names) — sets a synchronization source on the template, based on afixed list of names

You can then use this branch definition in order to generate or update branches from it:

// Create a templateontrack.branch('project', 'template') { template { parameter 'gitBranch', 'Name of the Git branch', 'release/${sourceName}' }}// Creates or updates the TEST instanceontrack.branch('project', 'template').instance 'TEST', [ gitBranch: 'my-branch']

7.2.5. DSL SCM extensions

If a SCM (Subversion or Git) is correctly configured on a branch, it is possible to download somefiles.

This is allowed only for the project owner.

For example, the following call:

def text = ontrack.branch('project', 'branch').download('folder/subfolder/path.txt')

will download the folder/subfolder/path.txt file from the corresponding SCM branch. AOTNotFoundException exception is thrown if the file cannot be found.

7.3. DSL ToolOntrack comes with an Ontrack DSL Shell tool that you can download from the releases page.

The ontrack-dsl-shell.jar is a fully executable JAR, published in GitHub release and in the MavenCentral, and can be used to setup a running instance of Ontrack:

97


ontrack-dsl-shell.jar --url ... --user ... --password ... --file ...

You can display the full list options using ontrack-dsl-shell.jar --help.

The --file argument is the path to a file containing the Ontrack DSL to execute. If not set, or set to -, the DSL is taken from the standard input. For example:

cat project-list.groovy | ontrack-dsl-shell.jar --url https://ontrack.nemerosa.net

where project-list.groovy contains:

ontrack.projects*.name

This would return a JSON like:

[ "iteach", "ontrack", "ontrack-jenkins", "versioning"]

The tool always returns its response as JSON and its output can be pipelined with tools like jq. Forexample:

cat project-list.groovy | ontrack-dsl-shell.jar --url https://ontrack.nemerosa.net |jq .

The JAR is a real executable, so there is no need to use java -jar on Unix likesystems or MacOS.

7.4. DSL ReferenceSee the appendixes.

7.5. DSL SamplesCreating a build:

ontrack.branch('project', 'branch').build('1', 'Build 1')

98

https://stedolan.github.io/jq/

http://docs.spring.io/spring-boot/docs/1.4.0.RELEASE/reference/htmlsingle/#build-tool-plugins-gradle-repackage-configuration

Promoting a build:

ontrack.build('project', '1', '134').promote('COPPER')

Validating a build:

ontrack.build('project', '1', '134').validate('SMOKETEST', 'PASSED')

Getting the last promoted build:

def buildName = ontrack.branch('project', 'branch').lastPromotedBuilds[0].name

Getting the last build of a given promotion:

def branch = ontrack.branch('project', 'branch')def builds = branch.standardFilter withPromotionLevel: 'BRONZE'def buildName = builds[0].name

Configuring a whole branch:

ontrack.project('project') { branch('1.0') { promotionLevel 'COPPER', 'Copper promotion' promotionLevel 'BRONZE', 'Bronze promotion' validationStamp 'SMOKE', 'Smoke tests' }}

Creating a branch template and an instance out of it:

99

// Branch template definitionontrack.project(project) { config { gitHub 'ontrack' } branch('template') { promotionLevel 'COPPER', 'Copper promotion' promotionLevel 'BRONZE', 'Bronze promotion' validationStamp 'SMOKE', 'Smoke tests' // Git branch config { gitBranch '${gitBranch}' } // Template definition template { parameter 'gitBranch', 'Name of the Git branch' } }}// Creates a template instanceontrack.branch(project, 'template').instance 'TEST', [ gitBranch: 'feature/test']

100

Chapter 8. ContributingContributions to Ontrack are welcome!

1. Fork the GitHub project

2. Code your fixes and features

3. Create a pull request

4. Your pull requests, once tested successfully, will be integrated into the master branch, waitingfor the next release

8.1. Branching strategyThe branching strategy used for Ontrack is based on the Git Flow.

• development of features always goes to feature/ branches created from the develop branch

• new releases are created by branching from the develop branch, using release/ as a prefix

• pull requests must be made from the develop branch

• the master branch contains an image of the latest release - no development is done on it

The versioning is automated using the Gradle Versioning plug-in. No file needs to be updated to setthe version.

8.2. Development

8.2.1. Environment set-up

Following tools must be installed before you can start coding with Ontrack:

• JDK8u181 or better

• Docker 17.12.0 or more recent

• Docker Compose 1.18.0 or more recent

Postgres set-up

Starting from release 3, Ontrack uses a Postgresql database for its backend.

By default, the application will try to access it at jdbc:postgresql://localhost:5432/ontrack usingontrack / ontrack as credentials.

You can of course set the database yourself, but the best way is to run the following Gradlecommand:

./gradlew devStart

101

https://github.com/nemerosa/ontrack

https://nvie.com/posts/a-successful-git-branching-model

https://github.com/nemerosa/versioning

https://www.oracle.com

https://www.docker.com/

https://docs.docker.com/compose/

This will use Docker in order to set up a Postgres database container, exposing the port 5432 on thehost and named postgresql.

To override the port being exposed, you can use the devPostgresPort property.

For example, to use the 5555 port:

./gradlew devStart -PdevPostgresPort=5555

You can also the name of the Postgres container, which defaults to postgresql byusing the devPostgresName property.

This container is used only for your local development, and is not used for running the integrationtests, where another container is automatically created and destroyed.

To stop the development environment, you can run:

./gradlew devStop

8.2.2. Building locally

./gradlew clean build

To launch the integration tests or acceptance tests, see Testing.

8.2.3. Launching the application from the command line

Just run:

./gradlew :ontrack-ui:bootRun

The application is then available at http://localhost:8080

The dev profile is activated by default and the working files and database file willbe available under ontrack-ui/work.

8.2.4. Launching the application in the IDE

Prepare the Web resources by launching:

./gradlew dev

In order to launch the application, run the net.nemerosa.ontrack.boot.Application class with

102


--spring.profiles.active=dev as argument.

The application is then available at http://localhost:8080

8.2.5. Developing for the web

If you develop on the web side, you can enable a LiveReload watch on the web resources:

./gradlew watch

Upon a change in the web resources, the browser page will be reloaded automatically.

8.2.6. Running the tests

See Testing.

8.2.7. Integration with IDE

With Intellij

• install the Lombok plugin

• in Build, Execution, Deployment > Compiler > Annotation Processors, check Enable annotationprocessing

8.2.8. Delivery

Official releases for Ontrack are available at:

• GitHub for the JAR, RPM and Debian packages

• Docker Hub for the Docker images

See the Installation documentation to know how to install them.

To create a package for delivery, just run:

./gradlew \ clean \ test \ integrationTest \ dockerLatest \ build

This will create:

• a ontrack-ui.jar

• a nemerosa/ontrack:latest Docker image in your local registry

103


http://livereload.com/


https://registry.hub.docker.com/nemerosa/ontrack

If you’re not interested in having a Docker image, just omit the dockerLatest task.

Versioning

The version of the Ontrack project is computed automatically from the current SCM state, using theGradle Versioning plug-in.

Deploying in production

See the Installation documentation.

8.2.9. Glossary

Form

Creation or update links can be accessed using the GET verb in order to get a form that allows theclient to carry out the creation or update.

Such a form will give information about:

• the fields to be created/updated

• their format

• their validation rules

• their description

• their default or current values

• etc.

The GUI can use those forms in order to automatically (and optionally) display dialogs to the user.Since the model is responsible for the creation of those forms, this makes the GUI layer moreresilient to the changes.

Link

In resources, links are attached to model objects, in order to implement a HATEOAS principle in theapplication interface.

HATEOAS does not rely exclusively on HTTP verbs since this would not allow a strongimplementation of the actual use cases and possible navigations (which HATEOAS is all about).

For example, the "Project creation" link on the list of projects is not carried by the sole POST verb,but by a _create link. This link can be accessed through verbs:

• OPTIONS - list of allowed verbs

• GET - access to a form that allows to create the object

• POST or PUT for an update - actual creation (or update) of the object

Model

104

https://github.com/nemerosa/versioning

Representation of a concept in the application. This reflects the ubiquitous language usedthroughout the application, and is used in all layers. As POJO on server side, and JSON objects atclient side.

Repository

Model objects are persisted, retrieved and deleted through repository objects. Repositories act as atransparent persistence layer and hides the actual technology being used.

Resource

A resource is a model object decorated with links that allow the client side to interact with the APIfollowing the HATEOAS principle. More than just providing access to the model structure, thoselinks reflect the actual use cases and the corresponding navigation. In particular, the links aredriven by the authorizations (a "create" link not being there if the user is not authorized). See Linkfor more information.

Service

Services are used to provide interactions with the model.

8.3. Architecture

8.3.1. Modules

105

Not all modules nor links are shown here in order to keep some clarity. The Gradlebuild files in the source remain the main source of authority.

Modules are used in ontrack for two purposes:

• isolation

• distribution

We distinguish also between:

• core modules

• extension modules

Extension modules rely on the extension-support module to be compiled and tested. The linkbetween the core modules and the extensions is done through the extension-api module, visible bythe two worlds.

106

Modules like common, json, tx or client are purely utilitarian (actually, they could be extracted fromontrack itself).

The main core module is the model one, which defines both the API of the Ontrack services and thedomain model.

8.3.2. UI

Resources

The UI is realized by REST controllers. They manipulate the model and get access to it throughservices.

In the end, the controllers return model objects that must be decorated by links in order to achieveHateoas.

The controllers are not directly responsible for the decoration of the model objects as resources(model + links). This is instead the responsibility of the resource decorators.

The model objects are not returned as such, often their content needs to be filtered out. Forexample, when getting a list of branches for a project, we do not want each project to bring along itsown copy of the project object. This is achieved using the model filtering technics.

Resource decorators

TODO

8.3.3. Forms

Simple input forms do not need a lot of effort to design in Ontrack. They can be used directly inpages or in modal dialogs.

Server components (controllers, services, …) are creating instances of the Form object and the clientlibraries (service.form.js) is responsible for their rendering:

107

Form object

The Form object is created by adding Field`s into it using its `with method:

import net.nemerosa.ontrack.model.form.Form;public Form getMyForm() { return Form.create() .with(field1) .with(field2) ;}

See the next section on how to create the field objects. The Form object contains utility methods forcommon fields:

Form.create() // `name` text field (40 chars max), with "Name" as a label // constrained by the `[A-Za-z0-9_\.\-]+` regular expression // Suitable for most name fields on the Ontrack model objects // (projects, branches, etc.) .name() // `password` password field (40 chars max) with "Password" as a label .password() // `description` memo field (500 chars max), optional, with "Description" // as a label .description() // `dateTime` date/time field (see below) with "Date/time" as a label .dateTime() // ... ;

In order to fill the fields with actual values, you can either use the value(…) method on the fieldobject (see next section) or use the fill(…) method on the Form object.

Map<String, ?> data = ...Form.create() // ... // Sets `value` as the value of the field with name "fieldName" .fill("fieldName", value) // Sets all values in the map using the key as the field name .fill(data)

Fields

Common field properties

Property Method Default value Description

108

name of(…) required Mapping

label label(…) none Display name

required optional() true Is the input required?

readOnly readOnly() false Is the input read-only?

validation validation(…) none Message to display isthe field content isdeemed invalid

help help(…) none Help message to displayfor the field (see belowfor special syntax)

visibleIf visibleIf(…) none Expression whichdefines if the field isdisplayed or not - seebelow for a detailedexplanation

value value(…) none Value to associatedwith the field

help property

TODO

visibleIf property

TODO

text field

The text field is a single line text entry field, mapped to the HTML <input type="test"/> form field.


length length(…) 300 Maximum length forthe text

regex regex(…) .* The text must complywith this regex in orderto be valid

Example:

109

Form.create() .with( Text.of("name") .label("Name") .length(40) .regex("[A-Za-z0-9_\\.\\-]+") .validation("Name is required and must contain only alpha-numeric characters,underscores, points or dashes.") )

password field

TODO

memo field

TODO

email field

TODO

url field

TODO

namedEntries field

Multiple list of name/value fields:

The user can:

• add / remove entries in the list

• set a name and a value for each item

• the name might be optional - the value is not


nameLabel nameLabel(…) "Name" Label for the "name"input part of an entry.

110


valueLabel valueLabel(…) "Value" Label for the "value"input part of an entry.

nameRequired nameOptional() true If the name part isrequired.

addText addText(…) "Add an entry" Label for the "add"button.

Example:

Form.create() .with( NamedEntries.of("links") .label("List of links") .nameLabel("Name") .valueLabel("Link") .nameOptional() .addText("Add a link") .help("List of links associated with a name.") .value(value != null ? value.getLinks() : Collections.emptyList()) )

date field

TODO

yesno field

TODO

dateTime field

TODO

int field

TODO

selection field

TODO

multi-strings field

TODO

multi-selection field

TODO

111

multi-form field

TODO

Creating your custom fields

TODO

Form usage on the client

TODO

Fields rendering

TODO

8.3.4. Model

The root entity in Ontrack is the project.

Several branches can be attached to a project. Builds can be created within a branch and linked toother builds (same or other branches).

Promotion levels and validation stamps are attached to a branch:

• a promotion level is used to define the promotion a given build has reached. A promotion rundefines this association.

• a validation stamp is used to qualify some tests or other validations on a build. A validation rundefines this association. There can be several runs per build and per validation stamp. A run

112

itself has a sequence of statuses attached to it: passed, failed, investigated, etc.

Builds and validation runs can be attached to some "run info" which gives additional informationlike the duration of the build or the validation.

Branches, promotion levels and validation stamps define the static structure of a project.

8.3.5. Model filtering

TODO

8.3.6. Jobs

Ontrack makes a heavy use of jobs in order to schedule regular activities, like:

• SCM indexation (for SVN for example)

• SCM/build synchronisations

• Branch templating synchronisation

• etc.

Services and extensions are responsible for providing Ontrack with the list of jobs they want to beexecuted. They do this by implementing the JobProvider interface that simply returns a collection of`JobRegistration`s to register at startup.

One component can also register a JobOrchestratorSupplier, which provides also a stream of`JobRegistration`s, but is more dynamic since the list of jobs to register will be determinedregularly.

The job scheduler is in charge to collect all registered jobs and to run them all.

Job architecture overview

This section explains the underlying concepts behind running the jobs in Ontrack.

When a job is registered, it is associated with a schedule. This schedule is dynamic and can bechanged with the time. For example, the indexation of a Git repository for a project is scheduledevery 30 minutes, but then, is changed to 60 minutes. The job registration schedule is then changedto every 60 minutes.

A job provides the following key elements:

• a unique identifier: the job key

• a task to run, provided as a JobRun interface:

@FunctionalInterfacepublic interface JobRun { void run(JobRunListener runListener);}

113

The task defined by the job can use the provided JobRunListener to providefeedback on the execution or to execution messages.

The job task is wrapped into a Runnable which is responsible to collect statistics about the jobexecution, like number of runs, durations, etc.

In the end, the JobScheduler can be associated with a JobDecorator to return another Runnable layerif needed.

The job scheduler is responsible to orchestrate the jobs. The list of jobs is maintained in memoryusing an index associating the job itself, its schedule and its current scheduled task (as aScheduledFuture).

Job registration

A JobRegistration is the associated of a Job and of Schedule (run frequency for the job).

A Schedule can be built in several ways:

// Registration only, no scheduleSchedule.NONE// Every 15 minutes, starting nowSchedule.everyMinutes(15)// Every minute, starting nowSchedule.EVERY_MINUTE// Every day, starting nowSchedule.EVERY_DAY// Every 15 minutes, starting after 5 minutesSchedule.everyMinutes(15).after(5)

see the Schedule class for more options.

By enabling the scattering options, one can control the schedule by adding a startup delay at thebeginning of the job.

The Job interface must define the unique for the job. A key in unique within a type within acategory.

Typically, the category and the type will be fixed (constants) while the key will depend on the jobparameters and context. For example:

JobCategory CATEGORY = JobCategory.of("category").withName("My category");JobType TYPE = CATEGORY.getType("type").withName("My type");public JobKey getKey() { return TYPE.getKey("my-id")}

The Job provides also a description, and the desired state of the job:

114

• disabled or not - might depend on the job parameters and context. For example, the job whichsynchronizes a branch instance with its template will be disable if the branch is disabled

• valid or not - when a job becomes invalid, it is not executed, and will be unregisteredautomatically. For example, a Subversion indexation job might become invalid if the associatedrepository configuration has been deleted.

Finally, of course, the job must provide the task to actually execute:

public JobRun getTask() { return (JobRunListener listener) -> ...}

The task takes as parameter a JobRunListener.

All job tasks run with administrator privileges. Job tasks can throw runtimeexceptions - they will be caught by the job scheduler and displayed in theadministration console.

8.3.7. Encryption

Ontrack will store secrets, typically passwords and tokens, together with the configurations neededto connect to external applications: Git, Subversion, JIRA, etc.

In order to protect the integrity of those external applications, those secrets must be protected.

Ontrack does so by encrypting those secrets in the database, using the AES128 algorithm. TheEncryptionService is used for encryption.

The key needed for the encryption is stored and retrieved using a ConfidentialStore service.

115

See Encryption service for more details about using a confidential store.

8.3.8. Build filters

The build filters are responsible for the filtering of builds when listing them for a branch.

Usage

By default, only the last 10 builds are shown for a branch, but a user can choose to create filters fora branch, and to select them.

The filters he creates are saved for later use: * locally, in its local browser storage * remotely, on theserver, if he is connected

For a given branch, a filter is identified by a name. The list of available filters for a branch iscomposed of those stored locally and of those returned by the server. The later ones have prioritywhen there is a name conflict.

116

Implementation

The BuildFilter interface defines how to use a filter. This filter takes as parameters:

• the current list of filtered builds

• the branch

• the build to filter

It returns two boolean results:

• is the build to be kept in the list?

• do we need to go on with looking for other builds?

The BuildFilterService is used to manage the build filters:

• by creating BuildFilter instances

• by managing BuildFilterResource instances

The service determines the type of BuildFilter by using its type, and uses injected`BuildFilterProvider`s to get an actual instance.

8.3.9. Reference services

This is a work in progress and this list is not exhaustive yet. In the meantime, thebest source of information remains the source code…

Service Description

StructureService Access to projects, branches and all entities

SecurityService Checks the current context for authorizations

PropertyService Access to the properties of the entities

EntityDataService This service allows to store and retrievearbitrary data with entities

EntityDataStore This service allows to store audited and indexeddata with entities. See EntityDataStore for moreinformation.

EntityDataStore

The EntityDataStore is a service which allows extensions to store some data associated with entitieswith the following properties:

• data stored as JSON

• data always associated with an entity

• indexation by category and name, not necessarily unique

• grouping of data using a group ID

• unique generated numeric ID

117

https://github.com/nemerosa/ontrack

• audit data - creation + updates

See the Javadoc for net.nemerosa.ontrack.repository.support.store.EntityDataStore for moredetails.

Example:

@AutowiredEntityDataStore store;@AutowiredSecurityService securityService;

Branch branch = ...

store.add(branch, "Category", "Name", securityService.getCurrentSignature(), null,json);

8.3.10. Technology

Client side

One page only, pure AJAX communication between the client and the server.

• AngularJS

• Angular UI Router

• Angular UI Bootstrap

• Bootstrap

• Less

Server side

• Spring Boot for the packaging & deployment

• Spring MVC for the REST API

• Spring for the IoC

• Spring Security & AOP for the security layer

• Plain JDBC for the data storage

• H2 in MySQL mode for the database engine

Layers

118

8.4. Testing• unit tests are always run and should not access resources not load the application context

(think: fast!)

• integration tests can access resources or load the application context, and run against adatabase

• acceptance tests are run against the deployed and running application.

8.4.1. Running the unit and integration tests

In order to run the unit tests only:

./gradlew test

In order to add the integration tests:

./gradlew integrationTest

From your IDE, you can launch both unit and integration tests using the default JUnit integration.

8.4.2. Acceptance tests

On the command line

This requires Docker & Docker Compose to be installed and correctly configured.

The application can be deployed on a local Docker container:

./gradlew localAcceptanceTest

If the Docker container used for the tests must be kept, add the -x localComposeDown to thearguments.

119

To only deploy the application in a container without launching any test, you canalso run ./gradlew localComposeUp.

From the IDE

In order to develop or test acceptance tests, you might want to run them from your IDE.

1. Make sure you have a running application somewhere, either by launching it from your IDE(see Integration with IDE) or by running ciStart (see previous section).

2. Launch all, some or one test in the ontrack-acceptance module after having set the followingsystem properties:

◦ ontrack.url - the URL of the running application to test - defaults to http://localhost:8080

◦ ontrack.disableSSL - true if the server is running with a self signed certificate, and if you’reusing https

Standalone mode

For testing ontrack in real mode, with the application to test deployed on a remote machine, it isneeded to be able to run acceptance tests in standalone mode, without having to check the code outand to build it.

Running the acceptance tests using the ciAcceptanceTest Gradle task remains theeasiest way.

The acceptance tests are packaged as a standalone JAR, that contains all the dependencies.

To run the acceptance tests, you need a JDK8 and you have to run the JAR using:

java -jar ontrack-acceptance.jar <options>

The options are:

• --option.acceptance.url=<url> to specify the <url> where ontrack is deployed. It defaults tohttp://localhost:8080

• --option.acceptance.admin=<password> to specify the administrator password. It defaults toadmin.

• --option.acceptance.context=<context> can be specified several time to define the context(s) theacceptance tests are running in (like --option.acceptance.context=production for example).According to the context, some tests can be excluded from the run.

The results of the tests is written as a JUnit XML file, in build/acceptance/ontrack-acceptance.xml.

The directory can be changed using the ontrack.acceptance.output-dir argument or systemproperty and defaults to build/acceptance.

The JUnit result file name can be changed using the ontrack.acceptance.result-file-name argument

120



or system property and defaults to ontrack-acceptance.xml.

8.4.3. Developing tests

Unit tests are JUnit tests whose class name ends with Test. Integration tests are JUnit tests whoseclass name ends with IT. Acceptance tests are JUnit tests whose class name starts with ACC and arelocated in the ontrack-acceptance module.

Unit test context

Unit tests do not need any application context or any database.

Integration test context

Integration tests will usually load an application context and connect to a Postgresql database.

For commodity, those tests will inherit from the AbstractITTestSupport class, and more specifically:

• from AbstractRepositoryTestSupport for JDBC repository integration tests

• from AbstractServiceTestSupport for service integration tests

Configuration for the integration tests is done in the ITConfig class.

8.5. Extending OntrackOntrack allows extensions to contribute to the application, and actually, most of the core features,like Git change logs, are indeed extensions.

This page explains how to create your own extensions and to deploy them along Ontrack. The samecoding principles apply also for coding core extensions and to package them in the mainapplication.

Having the possibility to have external extensions in Ontrack is very new and theway to provide them is likely to change (a bit) in the next versions. In particular,the extension mechanism does not provide classpath isolation between the"plugins".

8.5.1. Preparing an extension

In order to create an extension, you have to create a Java project.

The use of Kotlin is also possible.

Note that Ontrack needs at least a JDK8u65 to run.

Your extension needs to a Gradle project and have at least this minimal build.gradle file:

Maven might be supported in the future.

121

buildscript { repositories { mavenCentral() jcenter() } dependencies { classpath 'net.nemerosa.ontrack:ontrack-extension-plugin:{{ontrack-version}}' }}repositories { mavenCentral()}apply plugin: 'ontrack'

The buildscript section declares the version of Ontrack you’re building your extension for. Both themavenCentral and the jcenter repositories are needed to resolve the path for the ontrack-extension-plugin since the plugin is itself published in the Maven Central and some of its dependencies are inJCenter.

The repository declaration might be simplified in later versions.

The plug-in must declare the Maven Central as repository for the dependencies (Ontrack librariesare published in the Maven Central).

Finally, you can apply the ontrack plug-in. This one will:

• apply the java plug-in. If you want to use Groovy, you’ll have to apply this plug-in yourself.Kotlin is very well supported.

• add the ontrack-extension-support module to the compile configuration of your extension

• define some tasks used for running, testing and packaging your extension (see later)

8.5.2. Extension ID

Your extension must be associated with an identifier, which will be used throughout all theextension mechanism of Ontrack.

If the name of your extension project looks like ontrack-extension-<xxx>, the xxx will be ID of yourextension. For example, in the settings.gradle file:

rootProject.name = 'ontrack-extension-myextension'

then myextension is your extension ID.

If for any reason, you do not want to use ontrack-extension- as a prefix for your extension name,you must specify it using the ontrack Gradle extension in the build.gradle file:

122

ontrack { id 'myextension'}

8.5.3. Coding an extension

All your code must belong to a package starting with net.nemerosa.ontrack in order to be visible bythe Ontrack application.

Typically, this should be like: net.nemerosa.ontrack.extension.<id> where id is the ID of yourextension.

This limitation about the package name is likely to removed in future versions ofOntrack.

You now must declare your extension to Ontrack by creating an extension feature class:

package net.nemerosa.ontrack.extension.myextension;

import net.nemerosa.ontrack.extension.support.AbstractExtensionFeature;import net.nemerosa.ontrack.model.extension.ExtensionFeatureOptions;import org.springframework.stereotype.Component;

@Componentpublic class MyExtensionFeature extends AbstractExtensionFeature { public MyExtensionFeature() { super( "myextension", "My extension", "Sample extension for Ontrack", ExtensionFeatureOptions.DEFAULT ); }}

The @Component annotation makes this extension feature visible by Ontrack.

The arguments for the extension feature constructor are:

• the extension ID

• the display name

• a short description

• the extension options (see below)

123

8.5.4. Extension options

If your extension has some web components (templates, pages, etc.), it must declare this fact:

ExtensionFeatureOptions.DEFAULT.withGui(true)

If your extension depends on other extensions, it must declare them. For example, to depend onGitHub and Subversion extensions, first declare them as dependencies in the build.gradle:

ontrack { uses 'github' uses 'svn'}

then, in your code:

@Componentpublic class MyExtensionFeature extends AbstractExtensionFeature { @Autowired public MyExtensionFeature( GitHubExtensionFeature gitHubExtensionFeature, SVNExtensionFeature svnExtensionFeature ) { super( "myextension", "My extension", "Sample extension for Ontrack", ExtensionFeatureOptions.DEFAULT .withDependency(gitHubExtensionFeature) .withDependency(svnExtensionFeature) ); }}

8.5.5. Writing tests for your extension

Additionally to creating unit tests for your extension, you can also write integration tests, whichwill run with the Ontrack runtime enabled.

This feature is only available starting from version 2.23.1.

When the ontrack-extension-plugin is applied to your code, it makes the ontrack-it-utils moduleavailable for the compilation of your tests.

In particular, this allows you to create integration tests which inherit fromAbstractServiceTestSupport, to inject directly the Ontrack services you need and to use utilitymethods to create a test environment.

124

For example:

public MyTest extends AbstractServiceTestSupport { @Autowired private StructureService structureService @Test public void sample_test() { // Creates a project Project p = doCreateProject(); // Can retrieve it by name... asUser().withView(p).execute(() -> assertTrue(structureService.findProjectByName(p.getName()).isPresent()) ); }}

8.5.6. List of extension points

Ontrack provides the following extension points:

• Properties - allows to attach a property to an entity

• Decorators - allows to display a decoration for an entity

• User menu action - allows to add an entry in the connected user menu

• Settings - allows to add an entry in the global settings

• Metrics - allows to contribute to the metrics exported by Ontrack

• Event types - allows to define additional event types.

• GraphQL - allows contributions to the GraphQL Ontrack schema.

• Encryption key store - allows to define a custom store for the encryption keys.

• TODO Entity action - allows to add an action for the page of an entity

• TODO Entity information - allows to add some information into the page of an entity

• TODO Search extension - provides a search end point for global text based searches

• TODO Issue service - provides support for a ticketing system

• TODO SCM service - provides support for a SCM system

• TODO Account management action - allows to add an action into the account management

Other topics:

• Creating pages

• TODO Creating services

• TODO Creating jobs

See Reference services for a list of the core Ontrack services.

125

8.5.7. Running an extension

A Postgres database must be available to run an extension, since it is needed byOntrack.

See the development section to see how quickly set it up.

Using Gradle

To run your extension using Gradle:

./gradlew ontrackRun

This will make the application available at http://localhost:8080

The ontrackRun Gradle task can be run directly from Intellij IDEA and if necessary in debug mode.

When running with Gradle in your IDE, if you edit some web resources and wantyour changes available in the browser, just rebuild your project (Ctrl F9 in Intellij)and refresh your browser.

8.5.8. Packaging an extension

Just run:

./gradlew clean build

The extension is available as a JAR (together with its transitive dependencies, see below) inbuild/dist.

8.5.9. Extension dependencies

If your extension depends on dependencies which are not brought by Ontrack, you have to collectthem explicitly and put them in the same directory which contain your main JAR file.

The Ontrack plug-in provides an ontrackPrepare task which copies all dependencies (transitively)and the main JAR in the build/dist directory.

This task is called by the main build task.

8.5.10. Deploying an extension

Using the Docker image

The Ontrack Docker image uses the /var/ontrack/extensions volume to load extensions from. Bindthis volume to your host or to a data container to start putting extensions in it. For example:

126


docker run --volume /extension/on/host:/var/ontrack/extensions ...

You can also create your own image. Create the following Dockerfile:

Dockerfile

# Base Ontrack imageFROM nemerosa/ontrack:<yourversion># Overrides the extension directory, as to NOT use a volumeENV EXTENSIONS_DIR /var/ontrack/your-extension# Copies the extensions in the target volumeCOPY extensions/*.jar /var/ontrack/your-extension/

We assume here that your extensions are packaged in an extensions folder at the same level thanyour Dockerfile:

/-- Dockerfile|-- extensions/ |-- extension1.jar |-- extension2.jar

When using a child Dockerfile, the extension directory has to be customizedbecause we cannot use the VOLUME in this case.

Using the CentOS or Debian/Ubuntu package

The RPM and Debian packages both use the /usr/lib/ontrack/extensions directory for the locationof the extensions JAR files.

You can also create a RPM or Debian package which embeds both Ontrack and your extensions.

The means to achieve this depend on your build technology but the idea is the same in all cases:

Your package must:

• put the extension JAR files in /usr/lib/ontrack/extensions

• have a dependency on the ontrack package

In standalone mode

When running Ontrack directly, you have to set the loader.path to a directory containing theextensions JAR files:

java -Dloader.path=/path/to/extensions -jar ... <options>

127

8.5.11. Extending properties

Any entity in Ontrack can be associated with a set of properties. Extensions can contribute to createnew ones.

A property is the association some Java components and a HTML template to render it on thescreen.

Java components

First, a property must be associated with some data. Just create an invariant POJO like, for example:


import lombok.Data;

@Datapublic class MyProperty { private final String value;}

Note that Ontrack extensions can take benefit of using Lombok in order to reducethe typing. But this is not mandatory as all.

Then, you create the property type itself, by implementing the PropertyType interface or more easilyby extending the AbstractPropertyType class. The parameter for this class is the data created above:

@Componentpublic class MyPropertyType extends AbstractPropertyType<MyProperty> {}

The @Component notation registers the property type in Ontrack.

A property, or any extension is always associated with an extension feature and this one is typicallyinjected:

@Autowiredpublic MyPropertyType(MyExtensionFeature extensionFeature) { super(extensionFeature);}

Now, several methods need to be implemented:

• getName and getDescription return respectively a display name and a short description for theproperty

• getSupportedEntityTypes returns the set of entities the property can be applied to. For example,

128

https://projectlombok.org/

if your property can be applied only on projects, you can return:

@Overridepublic Set<ProjectEntityType> getSupportedEntityTypes() { return EnumSet.of(ProjectEntityType.PROJECT);}

• canEdit allows you to control who can create or edit the property for an entity. TheSecurityService allows you to test the authorizations for the current user. For example, in thissample, we authorize the edition of our property only for users being granted to the projectconfiguration:

@Overridepublic boolean canEdit(ProjectEntity entity, SecurityService securityService) { return securityService.isProjectFunctionGranted(entity, ProjectConfig.class);}

• canView allows you to control who can view the property for an entity. Like for canEdit, theSecurityService is passed along, but you will typically return true:

@Overridepublic boolean canView(ProjectEntity entity, SecurityService securityService) { return true;}

• getEditionForm returns the form being used to create or edit the property. Ontrack uses Formobjects to generate automatically user forms on the client. See its Javadoc for more details. Inour example, we only need a text box:

@Overridepublic Form getEditionForm(ProjectEntity entity, MyProperty value) { return Form.create() .with( Text.of("value") .label("My value") .length(20) .value(value != null ? value.getValue() : null) );}

• the fromClient and fromStorage methods are used to parse back and forth the JSON into aproperty value. Typically:

129

@Overridepublic MyProperty fromClient(JsonNode node) { return fromStorage(node);}

@Overridepublic MyProperty fromStorage(JsonNode node) { return parse(node, ProjectCategoryProperty.class);}

• the getSearchKey is used to provide an indexed search value for the property:

@Overridepublic String getSearchKey(My value) { return value.getValue();}

• finally, the replaceValue method is called when the property has to be cloned for another entity,using a replacement function for the text values:

@Overridepublic MyProperty replaceValue(MyProperty value, Function<String, String>replacementFunction) { return new MyProperty( replacementFunction.apply(value.getValue()) );}

Web components

A HTML fragment (or template) must be created at:

src/main/resources \-- static \-- extension \-- myextension \-- property \-- net.nemerosa.ontrack.extension.myextension.MyPropertyType.tpl.html

Replace myextension, the package name and the property type accordingly ofcourse.

The tpl.html will be used as a template on the client side and will have access to the Property object.Typically, only its value field, of the property data type, will be used.

130

The template is used the AngularJS template mechanism.

For example, to display the property as bold text in our sample:

<b>{{property.value.value}}</b>

The property must be associated with an icon, typically PNG, 24 x 24, located at:

src/main/resources \-- static \-- extension \-- myextension \-- property \-- net.nemerosa.ontrack.extension.myextension.MyPropertyType.png

Property search

By default, properties are not searchable - their value cannot be used to perform search.

If the property contains some text, it might be suitable to allow this property to be used in search.

To enable this, two main methods must be provided:

• containsValue

• getSearchArguments

The containsValue is used to check if a given string token is present of not in an instance of aproperty value. Let’s take a property data type which has a text field, we could implement thecontainsValue method by checking if this field contains the search token in a case insensitivemanner:

override fun containsValue(value: MessageProperty, propertyValue: String): Boolean { return StringUtils.containsIgnoreCase(value.text, propertyValue)}

The getSearchArguments method is more complex - it allows the Ontrack search engine to plug someSQL fragment into a more global search, for example like when searching for builds.

This method returns a PropertySearchArguments instance with three properties:

• jsonContext - expression to join with to the PROPERTIES table in order to contraint the JSON scope,for example jsonb_array_elements(pp.json→'items') as item. This expression is optional.

• jsonCriteria - Criteria to act on the jsonContext defined above, based on a search token, forexample: item→>'name' = :name and item→>'value' ilike :value. This expression is optional.Variables in this expression can be mapped to actual parameters using the criteriaParams mapparameter below.

• criteriaParams- Map of parameters for the criteria, for example: name → "name" and value →

131

https://docs.angularjs.org/guide/templates

"%value%". See the Spring Documentation for more information.

Most of the time, the jsonContext and jsonCriteria expressions will rely on the json column of thePROPERTIES table, which is a Postgres JSONB data type containing a JSON representation of theproperty data type.

Refer to the Postgres JSON documentation for more information about the syntax to use in thoseexpressions.

In the jsonContext and jsonCriteria expressions, the PROPERTIES table is designedusing the pp alias.

The getSearchArguments returns a null PropertySearchArguments instance by default- this means that any search on this property does not return anything.

Example, for a property data type having a links list of name/value strings, and we want to look inthe value field in a case insensitive way:

override fun getSearchArguments(token: String): PropertySearchArguments? { return PropertySearchArguments( jsonContext = "jsonb_array_elements(pp.json->'links') as link", jsonCriteria = "link->>'value' ilike :value", criteriaParams = mapOf( "value" to "%$token%" ) )}

8.5.12. Extending decorators

A decorator is responsible to display a decoration (icon, text, label, etc.) close to an entity name, inthe entity page itself or in a list of those entities. Extensions can contribute to create new ones.

A decorator is the association some Java components and a HTML template to render it on thescreen.

Java components

First, a decorator must be associated with some data. You can use any type, like a String, an enum orany other invariant POJO. In our sample, we’ll take a String, which is the value of the MyPropertyproperty described as example in Extending properties.

Then, you create the decorator itself, by implementing the DecorationExtension interface andextending the AbstractExtension. The parameter type is the decorator data defined above.

132

https://docs.spring.io/spring/docs/4.3.22.RELEASE/spring-framework-reference/htmlsingle/#jdbc-NamedParameterJdbcTemplate

https://www.postgresql.org/docs/9.4/datatype-json.html

https://www.postgresql.org/docs/9.4/functions-json.html

@Componentpublic class MyDecorator extends AbstractExtension implementsDecorationExtension<String> {}

The @Component notation registers the decorator in Ontrack.

A decorator, or any extension is always associated with an extension feature and this one istypically injected. Other services can be injected at the same time. For example, our sampledecorator needs to get a property on an entity so we inject the PropertyService:

private final PropertyService propertyService;@Autowiredpublic MyDecorator(MyExtensionFeature extensionFeature, PropertyServicepropertyService) { super(extensionFeature); this.propertyService = propertyService;}

Now, several methods need to be implemented:

• getScope returns the set of entities the decorator can be applied to. For example, if yourproperty can be applied only on projects, you can return:

@Overridepublic EnumSet<ProjectEntityType> getScope() { return EnumSet.of(ProjectEntityType.PROJECT);}

• getDecorations returns the list of decorations for an entity. In our case, we want to return adecoration only if the project is associated with the MyProperty property and return its value asdecoration data.

@Overridepublic List<Decoration<String>> getDecorations(ProjectEntity entity) { return propertyService.getProperty(entity, MyPropertyType.class).option() .map(p -> Collections.singletonList( Decoration.of( MyDecorator.this, p.getValue() ) )) .orElse(Collections.emptyList());}

133

Web components

A HTML fragment (or template) must be created at:

src/main/resources \-- static \-- extension \-- myextension \-- decoration \-- net.nemerosa.ontrack.extension.myextension.MyDecorator.tpl.html

Replace myextension, the package name and the decorator type accordingly ofcourse.

The tpl.html will be used as a template on the client side and will have access to the Decorationobject. Typically, only its data field, of the decoration data type, will be used.

The template is used the AngularJS template mechanism.

For example, to display the decoration data as bold text in our sample:

<b>{{decoration.data}}</b>

8.5.13. Extending the user menu

An extension can add a entry in the connected user menu, in order to point to an extension page.

Extension component

Define a component which extends AbstractExtension and implements UserMenuExtension:

134

https://docs.angularjs.org/guide/templates


@Componentpublic class MyUserMenuExtension extends AbstractExtension implementsUserMenuExtension {

@Autowired public MyUserMenuExtension(MyExtensionFeature extensionFeature) { super(extensionFeature); }

@Override public Action getAction() { return Action.of("my-user-menu", "My User Menu", "my-user-menu-page"); }

@Override public Class<? extends GlobalFunction> getGlobalFunction() { return ProjectList.class; }}

In this sample, my-user-menu-page is the relative routing path to the page the user action must pointto.

The getGlobalFunction method returns the function needed for authorizing the user menu toappear.

8.5.14. Extending pages

Extensions can also contribute to pages.

Extension menus

Extension pages must be accessible from a location:

• the global user menu

• an entity page

From the global user menu

TODO

From an entity page

In order for an extension to contribute to the menu of an entity page, you have to implement theProjectEntityActionExtension interface and extend the AbstractExtension.

135

@Componentpublic class MyProjectActionExtension extends AbstractExtension implementsProjectEntityActionExtension {}

The @Component notation registers the extension in Ontrack.

An action extension, or any extension is always associated with an extension feature and this one istypically injected. Other services can be injected at the same time. For example, our sampleextension needs to get a property on an entity so we inject the PropertyService:

private final PropertyService propertyService;@Autowiredpublic MyProjectActionExtension(MyExtensionFeature extensionFeature, PropertyServicepropertyService) { super(extensionFeature); this.propertyService ==== propertyService;}

The getAction method returns an optional Action for the entity. In our sample, we want to associatean action with entity if it is a project and if it has the MyProperty property being set:

@Overridepublic Optional<Action> getAction(ProjectEntity entity) { if (entity instanceof Project) { return propertyService.getProperty(entity, MyPropertyType.class).option() .map(p -> Action.of( "my-action", "My action", String.format("my-action/%d", entity.id()) ) ); } else { return Optional.empty(); }}

The returned Action object has the following properties:

• an id, uniquely identifying the target page in the extension

• a name, which will be used as display name for the menu entry

• a URI fragment, which will be used for getting to the extension end point (see later). Note thatthis URI fragment will be prepended by the extension path. So in our example, the final path forthe SAMPLE project with id 12 would be: extension/myextension/my-action/12.

136

Extension global settings

TODO

Extension page

Before an extension can serve some web components, it must be declared as beingGUI related. See the documentation to enable this(ExtensionFeatureOptions.DEFAULT.withGui(true)).

The extension must define an AngularJS module file at:

src/main/resources \-- static \-- extension \-- myextension \-- module.js

The module.js file name is fixed and is used by Ontrack to load the web components of yourextension at startup.

This is an AngularJS (1.2.x) module file and can declare its configuration, its services, its controllers,etc. Ontrack uses UI Router(), version 0.2.11 for the routing of the pages, allowing a routingdeclaration as module level.

For our example, we want to declare a page for displaying information forextension/myextension/my-action/{project} where {project} is the ID of one project:

137

http://angular-ui.github.io/ui-router/site

angular.module('ontrack.extension.myextension', [ 'ot.service.core', 'ot.service.structure' ]) // Routing .config(function ($stateProvider) { $stateProvider.state('my-action', { url: '/extension/myextension/my-action/{project}', templateUrl: 'extension/myextension/my-action.tpl.html', controller: 'MyExtensionMyActionCtrl' }); }) // Controller .controller('MyExtensionMyActionCtrl', function ($scope, $stateParams, ot,otStructureService) { var projectId ==== $stateParams.project;

// View definition var view ==== ot.view(); view.commands ==== [ // Closing to the project ot.viewCloseCommand('/project/' + projectId) ];

// Loads the project otStructureService.getProject(projectId).then(function (project) { // Breadcrumbs view.breadcrumbs ==== ot.projectBreadcrumbs(project); // Title view.title ==== "Project action for " + project.name; // Scope $scope.project ==== project; }); });

The routing configuration declares that the end point at /extension/myextension/my-

action/{project} will use the extension/myextension/my-action.tpl.html view and theMyExtensionMyActionCtrl controller defined below.

The ot and otStructureService are Ontrack Angular services, defined respectively by theot.service.core and ot.service.structure modules.

The MyExtensionMyActionCtrl controller:

• gets the project ID from the state (URI) definition

• it defines an Ontrack view, and defines a close command to go back to the project page

• it then loads the project using the otStructureService service and upon loading completes someinformation into the view

138

Finally, we define a template at:

src/main/resources \-- static \-- extension \-- myextension \-- extension/myextension/my-action.tpl.html

which contains:

<ot-view> Action page for {{project.name}}.</ot-view>

The ot-view is an Ontrack directive which does all the layout magic for you. You just have toprovide the content.

Ontrack is using Bootstrap 3.x for the layout and basic styling, so you can start structuring yourHTML with columns, rows, tables, etc. For example:

<ot-view> <div class="row"> <div class="col-md-12"> Action page for {{project.name}}. </div> </div></ot-view>

Extension API

TODO

Extension API resource decorators

TODO

8.5.15. Extending event types

Extensions can define additional event types which can then be used to add custom events toentities.

To register a custom event type:

139

http://getbootstrap.com/

@Autowiredpublic static final EventType CUSTOM_TYPE = SimpleEventType.of("custom-type", "Mycustom event");public MyExtension(..., EventFactory eventFactory) { super(extensionFeature); eventFactory.register(CUSTOM_TYPE);}

Then, you can use it this way when you want to attach an event to, let’s say, a build:

EventPostService eventPostService;Build build;...eventPostService.post( Event.of(MyExtension.CUSTOM_TYPE).withBuild(build).get());

8.5.16. Extending validation data

If built-in validation data types are not enough, additional ones can be created using the extensionmechanism.

To register a custom validation data type:

1. implement a component implementing the ValidationDataType interface or preferably theAbstractValidationDataType class (which provides some utility validation methods)

2. looks at the Javadoc of the ValidationDataType interface to get the list of methods to implementand some guides

The main choice to consider is about the configuration data type (C) and the data type (T).

The data type is the type of the data you actually associate with a validation run. For example, forsome code coverage, it would be a percentage, and therefore represented as an Int. It could be anyother type, either complex or simple.

The configuration data type is responsible for the configuration of the validation stamp, how theactual data will be interpreted when it comes to computing a status. It could be one or severalthresholds for example.

The best thing to get started would be to copy the code of existing built-in datatypes.

8.5.17. Extending GraphQL

Extensions can contribute to the Ontrack GraphQL core schema:

• custom types

140

• root queries

• additional fields in project entities

Preparing the extension

In your extension module, import the ontrack-ui-graphql module:

dependencies { compile "net.nemerosa.ontrack:ontrack-ui-graphql:${ontrackVersion}"}

If you want to write integration tests for your GraphQL extension, you have to include the GraphQLtesting utilities:

dependencies { testCompile "net.nemerosa.ontrack:ontrack-ui-graphql:${ontrackVersion}:tests"}

Custom types

To define an extra type, you create a component which implements the GQLType interface:

@Componentpublic class PersonType implements GQLType { @Override public GraphQLObjectType getType() { return GraphQLObjectType.newObject() .name("Person") .field(f -> f.name("name") .description("Name of the person") .type(GraphQLString) ) .build(); }}

See the graphql-java documentation for the description of the type construction.

You can use this component in other ones, like in queries, field definitions or other types, likeshown below:

141

https://github.com/graphql-java/graphql-java

@Componentpublic class AccountType implements GQLType {

private final PersonType personType;

@Autowired public AccountType (PersonType personType) { this.personType = personType; }

@Override public GraphQLObjectType getType() { return GraphQLObjectType.newObject() .name("Account") .field(f -> f.name("username") .description("Account name") .type(GraphQLString) ) .field(f -> f.name("identity") .description("Identity") .type(personType.getType()) ) .build(); }}

You can also create GraphQL types dynamically by using introspection of your model classes.

Given the following model:

@Datapublic class Person { private final String name;}@Datapublic class Account { private final String username; private final Person identity;}

You can generate the Account type by using:

@Overridepublic GraphQLObjectType getType() { return GraphQLBeanConverter.asObjectType(Account.class);}

142

The GraphQLBeanConverter.asObjectType is still very experimental and itsimplementation is likely to change in the next versions of Ontrack. For example,Map and Collection types are not supported.

Root queries

Your extension can contribute to the root query by creating a component implementing theGQLRootQuery interface:

@Componentpublic class AccountGraphQLRootQuery implements GQLRootQuery {

private final AccountType accountType;

@Autowired public AccountGraphQLRootQuery(AccountType accountType) { this.accountType = accountType; }

@Override public GraphQLFieldDefinition getFieldDefinition() { return GraphQLFieldDefinition.newFieldDefinition() .name("accounts") .argument(a -> a.name("username") .description("User name pattern") .type(GraphQLString) ) .type(accountType.getType()) .dataFetcher(...) .build(); }}

This root query can then be used into your GraphQL queries:

{ accounts(username: "admin*") { username identity { name } }}

Extra fields

The Ontrack GraphQL extension mechanism allows contributions to the project entities like theprojects, builds, etc.

143

For example, to contribute a owner field of type Account on the Branch project entity:

@Componentpublic class BranchOwnerGraphQLFieldContributor implements GQLProjectEntityFieldContributor {

private final AccountType accountType;

@Autowired public BranchOwnerGraphQLFieldContributor(AccountType accountType) { this.accountType = accountType; }

@Override public List<GraphQLFieldDefinition> getFields( Class<? extends ProjectEntity> projectEntityClass, ProjectEntityType projectEntityType) { return Collections.singletonList( GraphQLFieldDefinition.newFieldDefinition() .name("owner") .type(accountType.getType()) .dataFetcher(GraphqlUtils.fetcher( Branch.class, (environment, branch) -> return ... )) .build() );}

You can now use the owner field in your queries:

{ branches(id: 1) { name project { name } owner { username identity { name } } }}

144

Built-in scalar fields

The Ontrack GraphQL module adds the following scalar types, which you can use in your field ortype definitions:

• GQLScalarJSON.INSTANCE - maps to a JsonNode

• GQLScalarLocalDateTime.INSTANCE - maps to a LocalDateTime

You can use them directly in your definitions:

...

.field(f -> f.name("content").type(GQLScalarJSON.INSTANCE))

.field(f -> f.name("timestamp").type(GQLScalarLocalDateTime.INSTANCE))

...

Testing GraphQL

In your tests, create a test class which extends AbstractQLITSupport and use the run method toexecute a GraphQL query:

MyTestIT extends AbstractQLITSupport { @Test void my_test() { def p = doCreateProject() def data = run("""{ projects(id: ${p.id}) { name } }""") assert data.projects.first().name == p.name }}

While it is possible to run GraphQL tests in Java, it’s easier to do using Groovy.

8.5.18. Extending cache

Ontrack uses Caffeine to cache some data in memory to avoid reloading it from the database. Thecache behaviour can be configured using properties.

Extensions can also use the Ontrack cache and make it configurable.

In order to declare one or several caches, just a declare a Component which implementsCacheConfigExtension and set the Caffeine spec string for each cache.

145

https://github.com/ben-manes/caffeine

http://static.javadoc.io/com.github.ben-manes.caffeine/caffeine/2.6.0/com/github/benmanes/caffeine/cache/CaffeineSpec.html

@Componentclass MyCacheConfigExtension : CacheConfigExtension { override val caches: Map<String, String> get() = mapOf( "myCache" to "maximumSize=1000,expireAfterWrite=1h,recordStats" )}

The cache statistics are available as metrics if the recordStats flag is set.

The cache thus declared become configurable through external configuration. For example:

application.yml

ontrack: config: cache: specs: myCache: "maximumSize=2000,expireAfterWrite=1d,recordStats"

In order to use the cache in the code, you can just use the Spring cache annotations. For example:

@Serviceclass MyServiceImpl: MyService { @Cacheable(cacheNames = "myCache") fun getValue(id: Int): MyObject = ...}

8.5.19. Extending metrics

There are several ways to contribute to metrics in Ontrack:

• Meter registry direct usage

• Validation run metrics

• Run info listeners

• Metrics export service

Meter registry direct usage

Starting from version 2.35/3.35, the metrics framework used by Ontrack has beenmigrated to Micrometer. This is a breaking change - and the way metrics can becontributed to by extensions is totally different and some effort must be done inthe migration.

In order for extensions to add their own metrics, they can interact directly with an inject

146

https://docs.spring.io/spring-boot/docs/2.1.9.RELEASE/reference/htmlsingle/#production-ready-datasource-cache

https://docs.spring.io/spring-boot/docs/2.1.9.RELEASE/reference/htmlsingle/#boot-features-caching


MeterRegistry and then get gauges, timers, counters, etc.

Or they can create some MeterBinder beans to register some gauges at startup time.

Usually, migrating (monotonic) counters and timers will be straightforward:

val meterRegistry: MeterRegistrymeterRegistry.counter("...", tags).increment()meterRegistry.timer("...", tags).record { // Action to time}

For gauge, you have to register them so that they can be call at any time by the meter registry:

val meterRegistry: MeterRegistrymeterRegistry.gauge("...", tags, sourceObject, { obj -> /* Gets the gauge value from the object */ })

See the Micrometer documentation for more information on how to register metrics.

Validation run metrics

Every time a validation run is created, an event is sent to all instances ofValidationRunMetricsExtension.

You can register an extension to react to this creation:

class InfluxDBValidationRunMetricsExtension(myExtensionFeature: MyExtensionFeature) :AbstractExtension(myExtensionFeature), ValidationRunMetricsExtension { override fun onValidationRun(validationRun: ValidationRun) { // Does something with the created validation run }}

Run info listeners

Builds and validation runs can be associated with some run info, which contain information aboutthe execution time, source and author.

Every time a run info is created, an event is sent to all instances of RunInfoListener. To react tothose run info events, you can also declare a @Component implementing RunInfoListener. Forexample:

147


@Componentclass MyRunInfoListener : RunInfoListener { override fun onRunInfoCreated(runnableEntity: RunnableEntity, runInfo: RunInfo) { // Exports the run info to an external metrics system }}

Metrics export service

The MetricsExportService can be used to export any set of metrics, to any registered metrics system.

As of now, only InfluxDB is supported.

To export a metric, just call the exportMetrics method on the service:

metricsExportService.exportMetrics( "my-metric-name", tags = mapOf( "tag1" to "name1", "tag2" to "name2" ), fields = mapOf( "value1" to value1, "value2" to value2 ), timestamp = Time.now())

Metrics exporters must declared an extension of type MetricsExportExtension inorder to be accessible by the MetricsExportService service.

8.5.20. Using Kotlin in extensions

An extension can use Kotlin additionally to Java.

Just mention kotlin() in the Ontrack configuration in your build.gradle file:

build.gradle

ontrack { kotlin() ...}

The Kotlin Gradle plug-in will be automatically applied and the Kotlin JVM for JRE8, with the sameversion than for Ontrack, will be added in compileOnly mode to your dependencies. Enjoy!

148

http://kotlinlang.org/

8.5.21. Extending the settings

An extension can add a entry in the list of global settings.

Start by creating an invariant class which contains the data to manage in the new settings.

in the sample below, we use some PuppetDB connection settings, which need aURL, a user name and a password.

@Datapublic class PuppetDBSettings { private final String url; private final String username; private final String password;}

The settings are managed in Ontrack by two distinct services:

• a manager - responsible for the edition of the settings

• a provider - responsible for retrieving the settings

as-of today, the service cannot be the same class.

To define the manager, extend the AbstractSettingsManager class and use your settings class as aparameter:

@Componentpublic class PuppetDBSettingsManager extends AbstractSettingsManager<PuppetDBSettings>{

private final SettingsRepository settingsRepository; private final EncryptionService encryptionService;

@Autowired public PuppetDBSettingsManager(CachedSettingsService cachedSettingsService,SecurityService securityService, SettingsRepository settingsRepository,EncryptionService encryptionService) { super(PuppetDBSettings.class, cachedSettingsService, securityService); this.settingsRepository = settingsRepository; this.encryptionService = encryptionService; }

@Override protected void doSaveSettings(PuppetDBSettings settings) { settingsRepository.setString(PuppetDBSettings.class, "url",settings.getUrl()); settingsRepository.setString(PuppetDBSettings.class, "username",settings.getUsername());

149

settingsRepository.setPassword(PuppetDBSettings.class, "password",settings.getPassword(), false, encryptionService::encrypt); }

@Override protected Form getSettingsForm(PuppetDBSettings settings) { return Form.create() .with( Text.of("url") .label("URL") .help("URL to the PuppetDB server. For example:http://puppetdb") .value(settings.getUrl()) ) .with( Text.of("username") .label("User") .help("Name of the user used to connect to thePuppetDB server.") .optional() .value(settings.getUsername()) ) .with( Password.of("password") .label("Password") .help("Password of the user used to connect to thePuppetDB server.") .optional() .value("") // Password never sent to the client ); }

@Override public String getId() { return "puppetdb"; }

@Override public String getTitle() { return "PuppetDB settings"; }}

To define the provided, implement the AbstractSettingsManager and use your settings class as aparameter:

150

@Componentpublic class PuppetDBSettingsProvider implements SettingsProvider<PuppetDBSettings> {

private final SettingsRepository settingsRepository; private final EncryptionService encryptionService;

@Autowired public PuppetDBSettingsProvider(SettingsRepository settingsRepository,EncryptionService encryptionService) { this.settingsRepository = settingsRepository; this.encryptionService = encryptionService; }

@Override public PuppetDBSettings getSettings() { return new PuppetDBSettings( settingsRepository.getString(PuppetDBSettings.class, "url", ""), settingsRepository.getString(PuppetDBSettings.class, "username", ""), settingsRepository.getPassword(PuppetDBSettings.class, "password", "",encryptionService::decrypt) ); }

@Override public Class<PuppetDBSettings> getSettingsClass() { return PuppetDBSettings.class; }}

That’s all there is to do. Now, the new settings will automatically appear in the Settings page:

and can be edited using the form defined above:

151

8.5.22. Extending the security

The security model of Ontrack can be extended to fit for specific needs in extensions.

Adding functions

All authorizations in the code are granted through functions. We distinguish between:

• global functions about Ontrack in general

• project functions linked to a given project

Global roles are then linked to a number of global functions and project functions.

On the other hand, project roles can only be linked to project functions.

The association of core functions and core roles is fixed in the Ontrack core, but extensions can:

• define new global and project functions

• assign them to existing roles

For security reasons, extensions cannot associate existing core functions to roles.

In order to define a global function, just define an interface which extends GlobalFunction:

public interface MyGlobalFunction extends GlobalFunction {}

152

Almost the same thing for a project function:

public interface MyProjectFunction extends ProjectFunction {}

No method is to be implemented.

Now, you can link those functions to existing roles by providing a RoleContributor component. Inour example, we want to grant the global function and the project function to the AUTOMATION globalrole and the project function to the PROJECT_OWNER project role.

@Componentpublic MyRoleContributor implements RoleContributor { @Override public Map<String, List<Class<? extends GlobalFunction>>>getGlobalFunctionContributionsForGlobalRoles() { return Collections.singletonMap( Roles.GLOBAL_AUTOMATION, Collections.singletonList( MyGlobalFunction.class ) ); } @Override public Map<String, List<Class<? extends ProjectFunction>>>getProjectFunctionContributionsForGlobalRoles() { return Collections.singletonMap( Roles.GLOBAL_AUTOMATION, Collections.singletonList( MyProjectFunction.class ) ); } @Override public Map<String, List<Class<? extends ProjectFunction>>>getProjectFunctionContributionsForProjectRoles() { return Collections.singletonMap( Roles.PROJECT_OWNER, Collections.singletonList( MyProjectFunction.class ) ); }}

All available roles are listed in the Roles interface.

You can now check for those functions in your code by injecting the SecurityService:

153

private final SecurityService securityService;...if (securityService.isGlobalFunctionGranted(MyGlobalFunction.class)) { ...}if (securityService.isProjectFunctionGranted(project, MyProjectFunction.class)) { ...}

or:

private final SecurityService securityService;...securityService.checkGlobalFunction(MyGlobalFunction.class)) {securityService.checkProjectFunction(project, MyProjectFunction.class))

The project functions can be tested on a Project or any other entity which belongsto a project (branches, builds, etc.).

Adding roles

Both global and project roles can be added using the same RoleContributor extension class, byoverriding the following methods:

154

@Componentpublic MyRoleContributor implements RoleContributor { @Override public List<RoleDefinition> getGlobalRoles() { return Collections.singletonList( new RoleDefinition( "MY_GLOBAL_ROLE", "My Global Role", "This is a new global role" ) ); } @Override public List<RoleDefinition> getProjectRoles() { return Collections.singletonList( new RoleDefinition( "MY_PROJECT_ROLE", "My Project Role", "This is a new project role" ) ); }}

A new role can inherit from a built-in role:

@Override public List<RoleDefinition> getProjectRoles() { return Collections.singletonList( new RoleDefinition( "MY_PROJECT_ROLE", "My Project Role", "This is a new project role", Roles.PROJECT_PARTICIPANT ) ); }

In the previous example, the MY_PROJECT_ROLE will inherit from all functions of thebuilt-in PARTICIPANT role.

Same principle applies for global roles.

Those roles becomes eligible for selection when managing accounts and groups.

Note that functions (built-in or contributed) can be associated to those new roles - see Addingfunctions. By default, no function is associated to a contributed role.

155

8.5.23. Extending confidential stores

Extensions can define a custom confidential store used to store encryption keys.

Create a component which extends the AbstractConfidentialStore class:

@Component@ConditionalOnProperty(name = OntrackConfigProperties.KEY_STORE, havingValue ="custom")public class CustomConfidentialStore extends AbstractConfidentialStore {

public CustomConfidentialStore() { LoggerFactory.getLogger(CustomConfidentialStore.class).info( "[key-store] Using custom store" ); }

@Override public void store(String key, byte[] payload) throws IOException { // ... // Stores the key }

@Override public byte[] load(String key) throws IOException { // ... // Retrives the key or ... return null; }}

Note the use of the ConditionalOnProperty, which allows to select this store when theontrack.config.key-store property is set to custom.

8.5.24. Free text annotations

Some free text can be entered as description for some elements of the model and can beautomatically extended with hyperlinks.

See Hyperlinks in descriptions for this feature in the validation run statuses.

Using extensions, it is possible to extend this hyperlinked to other elements.

For example, let’s imagine that we have a system where all references like [1234] can be replaced toa link to http://reference/1234 with 1234 as a text.

For this, you have to create a @Component bean which implements the FreeTextAnnotatorContributorinterface.

The getMessageAnnotators returns a list of `MessageAnnotator`s used to transform the text into a

156

http://reference/1234



tree of nodes (typically some HTML).

In our example, this can give something like:

@Componentclass RefFreeTextAnnotatorContributor : FreeTextAnnotatorContributor { override fun getMessageAnnotators(entity: ProjectEntity): List<MessageAnnotator> { val regex = "\\[(d+)\\]".toRegex() return listOf( RegexMessageAnnotator( "\\[d+]\\" ) { match -> val result = regex.matchEntire(match) result ?.let { val id = it.groups[1].value.toInt(10) MessageAnnotation.of("a") .attr("href", "http://reference/$id") .text(id.toString()) } ?: match } ) }}

This component returns a single RegexMessageAnnotator (other implementations are of coursepossible, but this one is very convenient) which, given a regular expression, uses any match totransform into something else.

In our example, we extract the ID from the expression and return a link.

8.5.25. Label providers

Labels can be created and associated manually with projects.

Ontrack allows also some automation of this process using the concept of a label provider.

Labels created and associated to projects by label providers cannot be managedmanually: they cannot be edited, deleted or unselected.

Implementation

A label provider is a Service which extends the LabelProvider class and returns a list of labels for aproject.

For example, we could have a label provider which associates a "quality" label according to the"health" of the validation stamps in all "main" branches of the project. The label category would be"quality" and different names could be "high", "medium" and "low".

157

The code would look like:

@Serviceclass QualityLabelProvider : LabelProvider {

override val name: String = "Quality"

override val isEnabled: Boolean = true

override fun getLabelsForProject(project: Project): List<LabelForm> { // Computes quality of the project val quality: String = ... // Returns a label return listOf( LabelForm( category = "quality", name = quality, description = "", color = ... // Computes color according to quality ) ) }}

Activation

Even if you code such a label provider, nothing will happen until you activate the collection oflabels.

Ontrack disables this collection by default, because there is no default label provider and thatwould be a useless job.

To activate the label collection job, just set the ontrack.config.job-label-provider-enabled

configuration property to true.

Additionally, the label collection can be configured by administrators in the Settings:

• Enabled - Check to enable the automated collection of labels for all projects. This can generate ahigh level activity in the background.

158

• Interval - Interval (in minutes) between each label scan.

• Per project - Check to have one distinct label collection job per project.

8.5.26. Extending promotion checks

Promotion checks like "checking if the previous promotion is granted" are built-in in Ontrack butone can create its own by creating instances of the PromotionRunCheckExtension extension.

For example, to create a check on the name of the promotion level, that it should be uppercase only:

@Componentclass UppercasePromotionRunCheckExtension( extensionFeature: YourExtensionFeature): AbstractExtension(extensionFeature), PromotionRunCheckExtension { override fun checkPromotionRunCreation(promotionRun: PromotionRun) { if (promotionRun.promotionLevel.name !=promotionRun.promotionLevel.name.toUpperCase()) { throw UppercasePromotionRunCheckException(/* ... */) } }}

8.5.27. Extending the search

The Search capabilities of Ontrack can be extended through extensions and the core capabilities arealso coded through extensions.

A Search extension is a component which implements the SearchIndexer interface.

In versions 3.40 and before, search extensions were done using SearchProviderimplementations. Search was always done dynamically, without going through anindex, making it particularly slow on big volumes or when scanning externalsystems.

The SearchProvider is now deprecated and will be removed in version 4 of Ontrack,to be replaced exclusively by ElasticSearch.

Search indexer overview

A SearchIndexer is responsible for two things:

• feeding a search index

• transforming found index entries into displayable search results

The SearchIndexer must be parameterized by a SearchItem class - see

The indexerName is the display name for the indexer, used to log information or to name theindexation jobs.

159

Indexation jobs can be totally disabled by setting true as the isIndexationDisabled property. Theycannot even be triggered manually - set isIndexationDisabled to true when search indexes are notapplicable. For example, some SearchIndexer instances might be fed by other indexers.

The indexerSchedule is used to set a schedule to the indexation job. It defaults to Schedule.NONEmeaning that the job can be run only manually. Set another schedule for an automated job.

The indexName defines the name of the technical index used by this SearchIndexer - when usingElasticSearch, it corresponds to the name of ElasticSearch index to use. The index can be configuredby setting the indexMapping property - see Search indexation mapping for more information on thissubject.

At Ontrack startup time, all indexes are created (in ElasticSearch) and theirmapping updated.

The searchResultType defines the type of result returned by an index search capability. It’s used:

1. to provide a user a way to filter on the types of results

2. a way for the front-end to associate an icon to the type of result

For example:

@Componentclass MySearchIndexer: SearchIndexer<MySearchItem> { override val searchResultType = SearchResultType( feature = feature.featureDescription, id = "my-result", name = "My result", description = "Use a comma-separated list of tokens" )}

The feature is the ExtensionFeature associated with this SearchIndexer (see Coding an extension).

The description property is used to describe the type of search token one should use to find thistype of result (when applicable).

Search indexation

The indexAll method is called by the system when indexation job for this indexer is enabled (it is bydefault, unless isIndexationDisabled returns true).

It must:

• loop over all items to be indexed for a search (for example: all projects for the project indexer)

• transform all those items into instances of the SearchItem class associaed with this indexer (forexample: keeping only the project ID, its name and description)

• call the the provided processor function

160

The indexAll method is called by the system user.

For example:

override fun indexAll(processor: (ProjectSearchItem) -> Unit) { structureService.projectList.forEach { project -> processor(ProjectSearchItem(project)) }}

Behind the scene, the indexation job will send the items to index to an index service in batches(which makes the indexation quite performant).

The batch size is set by default to 1000 but can be:

1. configured using the ontrack.config.search.index.batch property

2. set explicitly using the indexBatch property of the SearchIndexer (this takes precedence)

Search results

When a search is performed, the SearchService will call the toSearchResult method of theSearchIndexer in order to transform an indexed item into a result which can be displayed to theuser.

See the documentation of the SearchIndexer.toSearchResult and of SearchResult fora complete information.

Usually, the indexer will:

• load the actual Ontrack object or extract information from the indexed item (this latter methodis preferred for performance reasons)

• in particular, it’ll check if the target object makes sense: does it still exist? Is it authorized to thecurrent user?

• setup a SearchResult instance to describe the result

For example, for the build indexer:

161

override fun toSearchResult(id: String, score: Double, source: JsonNode): SearchRe structureService.findBuildByID(ID.of(id.toInt()))?.run { SearchResult( title = entityDisplayName, description = description ?: "", uri = uriBuilder.getEntityURI(this), page = uriBuilder.getEntityPage(this), accuracy = score, type = searchResultType ) }

In this example:

• findBuildByID checks both the existence of the build and if it is accessible by the current user,returning null when not available

• the title of the result is set of the complete build name (including project and branch name)

• the uri and page can be computed using an injected URIBuilder

• the accuracy is the score returned by ElasticSearch

• for the type just use the searchResultType of the indexer

As of now, the accuracy is used for sorting results, but is not displayed

The toSearchResult runs with the authorizations of the user who is performing thesearch. Results should be filtered accordingly using an injected SecurityService. Ifnot, either the search will fail because of forbidden accesses or the final access willbe rejected.

Search index items

The SearchItem class used to parameterize the SearchIndexer must return two values:

• id - the unique ID of this item in the index

• fields - a map of values to store together with the index

Most of the times, you can define:

• a primary constructor listing the properties who want to store

• a secondary constructor using the domain model of Ontrack

Example for the Git commit indexer:

162

class GitCommitSearchItem( val projectId: Int, val gitType: String, val gitName: String, val commit: String, val commitShort: String, val commitAuthor: String, val commitMessage: String) : SearchItem {

constructor(project: Project, gitConfiguration: GitConfiguration, commit:GitCommit) : this( projectId = project.id(), gitType = gitConfiguration.type, gitName = gitConfiguration.name, commit = commit.id, commitShort = commit.shortId, commitAuthor = commit.author.name, commitMessage = commit.shortMessage )

override val id: String = "$gitName::$commit"

override val fields: Map<String, Any?> = asMap( this::projectId, this::gitType, this::gitName, this::commit, this::commitAuthor, this::commitShort, this::commitMessage )}

For the fields of the item, try to get only simple types or list of simple types.

The asMap utility method is optional and can be replaced by a direct map construction. However, itavoids to hard-code the field names and uses the property references instead.

Search indexation mapping

By default, indexes are mapped automatically to the provided fields (like in ElasticSearch) butexplicit mappings can be provided to:

• disable the indexation of some fields (like the projectId in the example above - while this field isneeded for creating a search result, it should not be used for searches)

• set a type, like keyword or text (the search won’t work the same way)

• boosting the search result score on some fields (a match on a key might be better than a matchon a free description text)

163

While the SearchIndexer mechanism has been made independent on ElasticSearch,the concept of mapping is very close to this application, in particular the mappingtypes (see below).

In order to specify a mapping, the indexMapping of the SearchIndexer must return an instance ofSearchIndexMapping.

While it’s possible to build such an instance manually, it’s more convenient to use the providedDSL. For example, for the Git commit indexer mentioned above:

override val indexMapping: SearchIndexMapping? = indexMappings<GitCommitSearchItem> { +GitCommitSearchItem::projectId to id { index = false } +GitCommitSearchItem::gitType to keyword { index = false } +GitCommitSearchItem::gitName to keyword { index = false } +GitCommitSearchItem::commit to keyword { scoreBoost = 3.0 } +GitCommitSearchItem::commitShort to keyword { scoreBoost = 2.0 } +GitCommitSearchItem::commitAuthor to keyword() +GitCommitSearchItem::commitMessage to text()}

The syntax is:

+<SearchItem::property>> [to <type>[ { <configuration> }]]*

The type for the property can be set using:

• id for a long

• keyword

• text

• any other type supported by ElasticSearch using `type("typeName")

The configuration is optional but accepts the following properties:

• index: Boolean - unset by default - to specify if this property must be indexed or not

• scoreBoost: Double - multiplicator for the significance of a match on this field (similar to theboost indicator in ElasticSearch)

A property can be associated with two types, for example when a field can be both considered as akeyword or as plain text.

+SearchItem::myProperty to keyword { scoreBoost = 2.0 } to text()

Search indexation jobs

Unless its isIndexationDisabled property returns true, every SearchIndexer is associated with a jobwhich runs the indexation of all items.

164

By default, those jobs must be launched manually but the indexSchedule can be used to define a runschedule.

Additionally, there is "All re-indexations" job which launches all re-indexations ; this is useful whenmigrating Ontrack to a deployment using ElasticSearch or to reset all indexes.

Search result icon

The searchResultType returned by a SearchIndexer contains a feature description and an ID. Both areused to identify the path to an icon which is used on client side:

• in the search box dropdown to select and restrict the type of result

• in the list of results

The icon (PNG, square, will be rescaled at client side) must be put in the resources at:

static/extension/<feature>/search-icon/<id>.png

where:

• <feature> is the feature ID

• <id> is the search result type id

Search indexing on events

Re-indexation of a complete index is costly. While some indexes don’t have any other choice but torecompute the index regularly, it’s more efficient to have the following steps:

• re-indexation once (when Ontrack is migrated to ElasticSearch)

• populating the index on events

Example: the project index is updated when a project is created, updated or deleted.

The type of event to listen to depends on the type of indexed item, but most of the cases are coveredby:

• implement EventListener - when you want to listen to events on project entities like projects,branches, validation runs, etc.

• PropertyType.onPropertyChanged/onPropertyDeleted to react on properties being created, updatedor deleted

• other types of listeners, more specialized, are also available in Ontrack

In all cases, you have to inject the SearchIndexService and call the appropriate methods, typicallycreateSearchIndex, updateSearchIndex and deleteSearchIndex, to update the index.

165

Don’t try to cover all the cases. For example, if your index is linked to a buildproperty, listen only to the property change, and not to the events occurring to thebuild, its branch or its project. It’s better to check in the toSearchResult method ifthe indexed object is still available or not.

166

Chapter 9. Appendixes

9.1. Configuration propertiesOntrack uses the Spring Boot mechanism for its configuration. See the documentation on how to setthose properties in your Ontrack installation.

All Spring Boot properties are available for configuration.

Additionally, Ontrack defines the following ones.

The names of the configuration properties are given for a .properties file formatbut you can configure them in YAML of course. They can also be provided assystem properties or environment variables. See the Spring Boot documentationfor more details.

This sample file is meant as a guide only. Do not copy/paste the entire content intoyour application; rather pick only the properties that you need.

When applicable, the default value is mentioned.

# ======================================================# Ontrack properties# ======================================================

# Maximum number of days to keep the log entriesontrack.config.application-log-retention-days = 7

# Maximum number of errors to display as notification in the GUIontrack.config.application-log-info-max = 10

# Directory which contains all the working files of Ontrack# It is usually set by the installationontrack.config.application-working-dir = work/files

# Maximum number of builds which can be returned by a build filter# Any number above is truncated down to this valueontrack.config.build-filter-count-max = 200

# Testing the configurations of external configurations# Used only for internal testing, to disable the checks# when creating external configurationsontrack.config.configuration-test = true

# Activation of the provided labels collection jobontrack.config.job-label-provider-enabled = false

167

http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#common-application-properties

http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#howto-properties-and-configuration

# Number of threads to use to run the background jobsontrack.config.jobs.pool-size = 10

# Interval (in minutes) between each refresh of the job listontrack.config.jobs.orchestration = 2

# Set to true to not start any job at application startup# The administrator can restore the scheduling jobs manuallyontrack.config.jobs.paused-at-startup = false

# Enabling the scattering of jobs# When several jobs have the same schedule, this can create a peak of activity,# potentially harmful for the performances of the application# Enabling scattering allows jobs to be scheduled with an additional delay, computed# as a fraction of the period.ontrack.config.jobs.scattering = false

# Scattering ratio. Maximum fraction of the period to take into account for the# scattering. For example, setting 0.5 would not add a dealy greater than half# the period of the job. Setting 0 would actually disable the scattering altogether.ontrack.config.jobs.scattering-ratio = 1.0

# Confidential store for the encryption keysontrack.config.key-store = file

# Cache configuration# Caffeine spec strings per cache type# See http://static.javadoc.io/com.github.ben-manes.caffeine/caffeine/2.6.0/com/github/benmanes/caffeine/cache/CaffeineSpec.html# For example, for the `properties` cache:ontrack.config.cache.specs.properties =maximumSize=1000,expireAfterWrite=1d,recordStats

################################## Search configuration properties#################################

# Search engine to use# Use `elasticsearch` to switch to ElasticSearch based searchontrack.config.search.engine = default

# By default, indexation is ElasticSearch is done after some# time after the index has been requested. The flag below# forces the index to be refreshed immediately.# This SHOULD NOT be used in production but is very useful# when testing Ontrack search capabilitiesontrack.config.search.index.immediate = false

# When performing full indexation, the indexation is performed# by batch. The parameter below allows to set the size# of this batch processing.

168

# Note: this is a default batch size. Custom indexers can# override it.ontrack.config.search.index.batch = 1000

# When performing full indexation, the indexation is performed# by batch. The parameter below allows to generate additional# logging when indexing actions are actually taken.ontrack.config.search.index.logging = false

# When performing full indexation, the indexation is performed# by batch. The parameter below allows to generate additional# logging for all actions on Git issues# Note: if set to `true` this generates an awful lot if information# at DEBUG level.ontrack.config.search.index.tracing = false

9.2. Deprecations and migration notes

9.2.1. Since 3.38

The PropertyType interface getSearchKey method is now deprecated and will be removed in a nextversion. Returning an empty string or calling the default super method is enough.

If the property is searchable, the getSearchArguments method must be implemented instead. SeeExtending properties for more information.

The searchkey column in the properties database table has been deleted.

9.2.2. Since 3.35

StructureService deprecated method:

• The getValidationRunsForBuildAndValidationStamp(net.nemerosa.ontrack.model.structure.ID,

net.nemerosa.ontrack.model.structure.ID) method is deprecated and should be replaced bygetValidationRunsForBuildAndValidationStamp(net.nemerosa.ontrack.model.structure.ID,

net.nemerosa.ontrack.model.structure.ID, int, int).

GraphQL schema deprecations:

• Build.linkedFrom is now deprecated and must be replaced by either uses or usedBy

9.2.3. Since 2.28

BitBucket global configurations are no longer associated with issue services, only project BitBucketconfigurations are. This is an alignment with the way the other SCM connections are working inOntrack.

Upgrading to 2.28 performs an automated migration of the global configuration settings to theproject ones.

169

9.2.4. Since 2.16

Support for custom branch and tags patterns in Subversion configurations hasbeen removed. Ontrack now supports only standard Subversion structure:project/trunk, project/branches and project/tags. This has allowed a betterflexibility in the association between builds and Subversion locations.

Association between builds and Subversion locations is now configured through a build revisionlink at branch level. The previous buildPath parameter is converted automatically to theappropriate type of link.

9.3. RoadmapHere are big ideas for the future of Ontrack. No plan yet, just rough ideas or wish lists.

9.3.1. Use JPA / Hibernate for SQL queries

• caching (no existent today)

• see impact on multi Ontrack cluster

9.3.2. Using Neo4J as backend

Ontrack basically stores its data as a graph, and Neo4J would be a perfect match for the storage.

Consider:

• migration

• search engine

9.3.3. Global DSL

The current Ontrack DSL can be used only remotely and cannot be run on the server.

We could design a DSL which can be run, either:

• remotely - interacting with the HTTP API

• in the server - interacting directly with the services

Additionally, the DSL should be extensible so that extensions can contribute to it, on the samemodel than the Jenkins Job DSL.

9.3.4. Web hooks

Have the possibility to register Webhooks in Ontrack in order to notify other applications aboutchanges and events.

170

https://github.com/jenkinsci/job-dsl-plugin/wiki/Extending-the-DSL

9.4. CertificatesSome resources (Jenkins servers, ticketing systems, SCM…) will be configured and accessed inOntrack using the https protocol, possibly with certificates that are not accepted by default.

Ontrack does not offer any mechanism to accept such invalid certificates.

The running JDK has to be configured in order to accept those certificates.

9.4.1. Registering a certificate in the JDK

To register the certificate in your JDK:

sudo keytool -importcert \ -keystore ${JAVA_HOME}/jre/lib/security/cacerts -storepass changeit \ -alias ${CER_ALIAS} \ -file ${CER_FILE}

To display its content:

sudo keytool -list \ -keystore ${JAVA_HOME}/jre/lib/security/cacerts \ -storepass changeit \ -alias ${CER_ALIAS} \ -v

See the complete documentation at http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html.

9.4.2. Saving the certificate on MacOS

1. Open the Keychain Access utility (Applications → Utilities)

2. Select your certificate or key from the Certificates or Keys category

3. Choose File → Export items …

4. In the Save As field, enter a ".cer" name for the exported item, and click Save.

You will be prompted to enter a new export password for the item.

9.5. Metrics migration

171

http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html

http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html

Since version 2.35 / 3.35, Ontrack uses the Micrometer framework to managemetrics, in order to allow a better integration with Spring Boot 2.

This means that old metrics are no longer supported and that any tool / dashboardusing the old keys must be adapted.

See also Metrics.

Old metric key New metric key Tags

gauge.entity.project ontrack_entity_project_total -

gauge.entity.branch ontrack_entity_branch_total -

gauge.entity.build ontrack_entity_build_total -

gauge.entity.promotionLevel ontrack_entity_promotionLevel_total

-

gauge.entity.promotionRun ontrack_entity_promotionRun_total

-

gauge.entity.validationStamp ontrack_entity_validationStamp_total

-

gauge.entity.validationRun ontrack_entity_validationRun_total

-

gauge.entity.validationRunStatus

ontrack_entity_validationRunStatus_total

-

gauge.entity.property ontrack_entity_property_total -

gauge.entity.event ontrack_entity_event_total -

gauge.jobs ontrack_job_count_total -

gauge.jobs.running ontrack_job_running_total -

gauge.jobs.disabled ontrack_job_disabled_total -

gauge.jobs.error ontrack_job_error_total -

gauge.jobs.invalid ontrack_job_invalid_total -

gauge.jobs.paused ontrack_job_paused_total -

gauge.jobs.<category> n/a -

gauge.jobs.<category>.running n/a -

gauge.jobs.<category>.disabled n/a -

gauge.jobs.<category>.error ontrack_job_error_count category tag

gauge.jobs.<category>.invalid n/a -

gauge.jobs.<category>.paused n/a -

ontrack.job.count n/a -

ontrack.job.running n/a -

ontrack.job.disabled n/a -

ontrack.job.error n/a -

ontrack.job.invalid n/a -

ontrack.job.paused n/a -

172



Old metric key New metric key Tags

counter.error ontrack_error -

counter.error.<type> ontrack_error <type> as `type`tag

If a metric marked as n/a (not available) is still needed, either create an extensionto add it or create an issue to have it added.

9.6. Migration from H2 to PostgresStarting from version 3, Ontrack uses Postgres instead of H2 for its back-end.

9.6.1. Prerequisites

Before you actually start the migration, please make sure you have the following elements:

• a copy of the H2 database file to migrate (typically a data.mv.db file) and the associatedcredentials

• an access to the Postgres database to migrate to and the associated credentials

• a copy of the secret files

For a Docker installation, the database is located at/var/ontrack/data/database/data.mv.db and the secret files in/var/ontrack/data/files/security/secrets.

For a RPM or Debian installation, the database is located at/usr/lib/ontrack/database/data.mv.db and the secret files in/usr/lib/ontrack/files/security/secrets.

9.6.2. Migration tool

The migration tool is part of the Ontrack release and can be downloaded as ontrack-postgresql-migration.jar in the GitHub release page.

9.6.3. Running the migration

Create a directory, called ${MIGRATION} in the rest of this section, and

• copy the data.mv.db database file in this directory

• copy the ontrack-postgresql-migration.jar migration tool in this directory

Run the following command:

java -jar ontrack-postgresql-migration.jar

By default, the tool will look for the H2 database file in the current directory, using ontrack / ontrack

173


as credentials.

By default, the tool will use a Postgres database located atjdbc:postgresql://localhost:5432/ontrack, using ontrack / ontrack as credentials.

You can change those default values using the configuration options below.

9.6.4. Migration tool options

Migration options can either be specified on the command line or by creating a localapplication.properties file.

Option Default value Description

ontrack.migration.cleanup false If set to true, all previous tableswill be deleted. This forces amigration from scratch.

ontrack.migration.skip-events false If set to true, the events will notbe migrated. This can speed upthe migration but can have sideeffects since some entities willnot be associated with theircreation event.

ontrack.migration.h2.url jdbc:h2:./data;MODE=MYSQL;DB_CLOSE_ON_EXIT=FALSE;DEFRAG_ALWAYS=TRUE

JDBC URL to the H2 database

ontrack.migration.h2.username ontrack User used to connect to the H2database

ontrack.migration.h2.password ontrack Password used to connect to theH2 database

ontrack.migration.postgresql.url

jdbc:postgresql://localhost:5432/ontrack

JDBC URL to the Postgresdatabase

ontrack.migration.postgresql.username

ontrack User used to connect to thePostgres database

ontrack.migration.postgresql.password

ontrack Password used to connect to thePostgres database

9.6.5. Secret files

The master.key and net.nemerosa.ontrack.security.EncryptionServiceImpl.encryption files must becopied and put in the correct place.

For a development environment, put those files in work/files/security/secrets,relatively to the workspace root.

9.7. Postgres and FlywayThe creation and updates of the Ontrack schema in Postgres is managed using Flyway.

174

https://flywaydb.org/

The configuration is initialized in the net.nemerosa.ontrack.repository.RepositoryConfig class andSQL files are stored in ontrack-database/src/main/resources/ontrack/sql.

As of now, extensions cannot contribute to the schema.

The actual migration is processed using the net.nemerosa.ontrack.service.support.StartupStrategycomponent. Once the database has been upgraded, all StartupService implementations are startedin heir specified order.

9.8. Using production dataSome times, when developing Ontrack or working with extensions, it might be useful to copy theproduction data locally.

Make sure to have pg_dump and psql tools available in your working environment.

They are part of the Postgres installation but can be downloaded individually fromthe download page.

To export the data from the source database in a local ontrack.sql file:

pg_dump --dbname ontrack --host <source-host> --port 5432 \ --username <source-user> > ontrack.sql

To import this data into the target database:

psql --dbname ontrack --host <target-host> --port 5432 \ --username <target-user> < ontrack.sql

the target database must be empty (no table, no sequences).

When the migration of data is done, do not forget to also copy the secret files and to put them in thecorrect location.

For a Docker installation, the secret files are in/var/ontrack/data/files/security/secrets.

For a RPM or Debian installation, the secret files are in/usr/lib/ontrack/files/security/secrets.

In the development environment, the secret files are inwork/files/security/secrets, relatively to the workspace root..

175

https://www.postgresql.org/download/

9.9. DSL Reference

Class summary

Class

Ontrack - Methods

AbstractProjectResource Methods

AbstractResource Methods

Account Methods

AccountGroup Methods

Admin Methods

AuthenticationSource Methods

Branch Properties Methods

Build Properties Methods

ChangeLog Methods

ChangeLogCommit Methods

ChangeLogFile Methods

ChangeLogIssue Methods

Config Methods

Document Methods

GroupMapping Methods

LDAPSettings

Label Methods

MainBuildLinks

PredefinedPromotionLevel Methods

PredefinedValidationStamp Methods

Project Properties Methods

ProjectEntityProperties Methods

PromotionLevel Properties Methods

PromotionRun Methods

SearchResult Methods

SonarQubeMeasuresSettings

ValidationRun Methods

ValidationRunStatus Methods

ValidationStamp Properties Methods

9.9.1. Ontrack

An Ontrack instance is usually bound to the ontrack identifier and is the root for all DSL calls.

176

Method summary

Method Description

branch Branch branch(String project, String branch)

Looks for a branch in a project. Fails if notfound.

build Build build(String project, String branch,String build)

Looks for a build by name. Fails if not found.

configure Object configure(Closure closure)

Configures the general settings of Ontrack. SeeConfig.

delete Object delete(String url)

Runs an arbitrary DELETE request for a relativepath and returns JSON

download Document download(String url)

Downloads an arbitrary document using arelative path.

findProject Project findProject(String name)

Finds a project using its name. Returns null ifnot found.

get Object get(String url)

Runs an arbitrary GET request for a relativepath and returns JSON

getAdmin Admin getAdmin()

Access to the administration of Ontrack

getConfig Config getConfig()

Access to the general configuration of Ontrack

getProjects List<Project> getProjects()

Gets the list of projects

getVersion String getVersion()

Gets the version of the remote Ontrack server

graphQLQuery Object graphQLQuery(String query, Mapvariables = [:])

177

post Object post(String url, Object data)

Runs an arbitrary POST request for a relativepath and some data, and returns JSON

project Project project(String name, Stringdescription = '')

Finds or creates a project.

project Project project(String name, Stringdescription = '', Closure closure)

Finds or creates a project, and configures it.

promotionLevel PromotionLevel promotionLevel(String project,String branch, String promotionLevel)

Looks for a promotion level by name. Fails if notfound.

put Object put(String url, Object data)

Runs an arbitrary PUT request for a relativepath and some data, and returns JSON

search List<SearchResult> search(String token, Stringtype = null, int offset = 0, int size = 20)

Launches a global search based on a token.

searchIndexReset void searchIndexReset(boolean reindex = false)

Resets all search indexes and re-index optionally

text Object text(String url)

Runs an arbitrary GET request for a relativepath and returns text

upload Object upload(String url, String name, Objecto)

Uploads some arbitrary binary data on a relativepath and returns some JSON. See upload.

upload Object upload(String url, String name, Objecto, String contentType)

Uploads some typed data on a relative path andreturns some JSON

validationStamp ValidationStamp validationStamp(Stringproject, String branch, StringvalidationStamp)

Looks for a validation stamp by name. Fails ifnot found.

178

branch

Branch branch(String project, String branch)

Looks for a branch in a project. Fails if not found.

See: Branch

build

Build build(String project, String branch, String build)

Looks for a build by name. Fails if not found.

See: Build

Sample:

def build = ontrack.build('prj', 'master', '1.0.0-12')assert build.name == '1.0.0-12'

configure

Object configure(Closure closure)

Configures the general settings of Ontrack. See Config.

delete

Object delete(String url)

Runs an arbitrary DELETE request for a relative path and returns JSON

download

Document download(String url)

Downloads an arbitrary document using a relative path.

See: Document

179

findProject

Project findProject(String name)

Finds a project using its name. Returns null if not found.

See: Project

Sample:

def project = ontrack.findProject('unexisting')assert project == null

get

Object get(String url)

Runs an arbitrary GET request for a relative path and returns JSON

getAdmin

Admin getAdmin()

Access to the administration of Ontrack

See: Admin

getConfig

Config getConfig()

Access to the general configuration of Ontrack

See: Config

getProjects

List<Project> getProjects()

Gets the list of projects

See: Project

Sample:

def projects = ontrack.projectsassert projects instanceof Collection

180

getVersion

String getVersion()

Gets the version of the remote Ontrack server

graphQLQuery

Object graphQLQuery(String query, Map variables = [:])

The graphQLQuery runs a GraphQL query against the Ontrack model.

It returns a JSON representation of an ExecutionResult object containing both the data and anyerror message.

def result = ontrack.graphQLQuery("""{ projects(name: "P") { name branches { name } }}""")

assert result.errors != null && result.errors.emptyassert result.data.projects.get(0).name == "P"

The graphQLQuery method accepts an additional variables map parameter to define any GraphQLvariable used in the query. For example:

def result = ontrack.graphQLQuery("""{ projects(id: $projectId) { name branches { name } }}""", [projectId: 10])

See GraphQL support for more information about the GraphQL Ontrack integration.

post

Object post(String url, Object data)

Runs an arbitrary POST request for a relative path and some data, and returns JSON

181

http://graphql.org/

https://github.com/graphql-java/graphql-java/blob/master/src/main/java/graphql/ExecutionResult.java

project

Project project(String name, String description = '')

Finds or creates a project.

See: Project

Sample:

def project = ontrack.project('my-project', 'My project')assert project.name == 'my-project'

project

Project project(String name, String description = '', Closure closure)

Finds or creates a project, and configures it.

See: Project

Sample:

def project = ontrack.project('my-project', 'My project') { // Configuring the project}assert project.name == 'my-project'

promotionLevel

PromotionLevel promotionLevel(String project, String branch, String promotionLevel)

Looks for a promotion level by name. Fails if not found.

See: PromotionLevel

put

Object put(String url, Object data)

Runs an arbitrary PUT request for a relative path and some data, and returns JSON

182

search

List<SearchResult> search(String token, String type = null, int offset = 0, int size = 20)

Launches a global search based on a token.

See: SearchResult

searchIndexReset

void searchIndexReset(boolean reindex = false)

Resets all search indexes and re-index optionally

text

Object text(String url)

Runs an arbitrary GET request for a relative path and returns text

upload

Object upload(String url, String name, Object o)

Uploads some arbitrary binary data on a relative path and returns some JSON. See upload.

upload

Object upload(String url, String name, Object o, String contentType)

Uploads some typed data on a relative path and returns some JSON

Creates a multi-part upload request where the name part contains the content of the given input oobject. The content depends on the type of object:

• for a net.nemerosa.ontrack.dsl.Document, uploads this document - the contentType parameter isthen ignored

• for a File or URL, the content of the file is uploaded, using the provided contentType

• for a byte array, the content of the array is uploaded, using the provided contentType

• for a String:

◦ if starting with classpath:, the remainder of the string is used as a resource path (see URLabove)

◦ if a valid URL, we use the string as a URL - see above

◦ if any other case, we consider the string to be the path to a file - see File above

183

validationStamp

ValidationStamp validationStamp(String project, String branch, String validationStamp)

Looks for a validation stamp by name. Fails if not found.

See: ValidationStamp

9.9.2. AbstractProjectResource

See also: AbstractResource

Method summary

Method Description

config Object config(Closure closure)

Configures this entity.

delete Object delete()

Deletes this entity.

getDecoration Object getDecoration(String type)

Gets the data for the first decoration of a giventype. If no decoration is available, returns null.

getDecorations List<> getDecorations(String type)

Returns the list of decoration data (JSON) for agiven decoration type.

getDecorations List<> getDecorations()

Returns the list of decorations for this entity.Each item has a decorationType type name anddata as JSON.

getDescription String getDescription()

Returns any description attached to this entity.

getId int getId()

Returns the numeric ID of this entity.

getJenkinsJobDecoration String getJenkinsJobDecoration()

Gets the Jenkins decoration for this entity.

getMessageDecoration Map<String> getMessageDecoration()

Gets any message for this entity

184

getName String getName()

Returns the name of this entity.

getProperty Object getProperty(String type, booleanrequired)

property Object property(String type)

property Object property(String type, Object data)

Sets the value for a property of this entity. Preferusing dedicated DSL methods.

config

Object config(Closure closure)

Configures this entity.

delete

Object delete()

Deletes this entity.

getDecoration

Object getDecoration(String type)

Gets the data for the first decoration of a given type. If no decoration is available, returns null.

getDecorations

List<> getDecorations(String type)

Returns the list of decoration data (JSON) for a given decoration type.

getDecorations

List<> getDecorations()

Returns the list of decorations for this entity. Each item has a decorationType type name and dataas JSON.

getDescription

String getDescription()

Returns any description attached to this entity.

185

getId

int getId()


getJenkinsJobDecoration

String getJenkinsJobDecoration()

Gets the Jenkins decoration for this entity.

getMessageDecoration

Map<String> getMessageDecoration()

Gets any message for this entity

The message is returned as a map containing:

• the type of message: ERROR, WARNING or INFO

• the actual text of the message

The returned map is null is no message is associated with this entity.

Sample:

def project = ontrack.project('prj')def branch = ontrack.branch('prj', 'test')def build = ontrack.build('prj', 'test', '1')assert project.messageDecoration == nullassert branch.messageDecoration == nullassert build.messageDecoration == nullproject.config.message('Information', 'INFO')assert project.messageDecoration == [type: 'INFO', text: 'Information']branch.config.message('Warning', 'WARNING')assert branch.messageDecoration == [type: 'WARNING', text: 'Warning']build.config.message('Error', 'ERROR')assert build.messageDecoration == [type: 'ERROR', text: 'Error']

getName

String getName()

Returns the name of this entity.

186

getProperty

Object getProperty(String type, boolean required)

Gets a property on the project entity.

If required is set to false and if the property does not exist or is not set, null will be returned.

If required is set to true and if the property does not exist or is not set, anet.nemerosa.ontrack.dsl.PropertyNotFoundException is thrown.

def project = ontrack.project('PRJ')def value = project.getProperty('com.my.UnsetPropertyType', false)assert value == null

property

Object property(String type)

Gets a required property on the project entity.

If the property does not exist or is not set, a net.nemerosa.ontrack.dsl.PropertyNotFoundException isthrown.

def project = ontrack.project('PRJ')def value = project.property('com.my.PropertyType')

property

Object property(String type, Object data)

Sets the value for a property of this entity. Prefer using dedicated DSL methods.

9.9.3. AbstractResource

Method summary

Method Description

getNode Object getNode()

Gets the internal JSON representation of thisresource.

getPage String getPage()

Gets the Web page address for this resource.

187

link String link(String name)

Gets a link address.

optionalLink String optionalLink(String name)

Gets a link address if it exists.

getNode

Object getNode()

Gets the internal JSON representation of this resource.

getPage

String getPage()

Gets the Web page address for this resource.

This method returns the URL of the Web page which displays this resource.

This is equivalent to calling link('page').

link

String link(String name)

Gets a link address.

The name of the link refers to a link which is embedded in the JSON representation of the resource.In the JSON, the link name is prefixed by _ but the name does not have too.

For example, link('create') and link('_create') are equivalent.

If the link does not exist, an ResourceMissingLinkException error is thrown.

The value of the link can be called using the Ontrack methods:

def project = ontrack.projects[0]def projectJson = ontrack.get(project.link('self'))

optionalLink

String optionalLink(String name)

Gets a link address if it exists.

This is the same than the link method, but returns null is the link does not exist instead of failing.

188

9.9.4. Account

Representation of a user account.


Method summary

Method Description

getAccountGroups List<AccountGroup> getAccountGroups()

List of groups this account belongs to.

getAuthenticationSource AuthenticationSource getAuthenticationSource()

Source of the account: LDAP, built-in, …

getEmail String getEmail()

Email for the account.

getFullName String getFullName()

Display name for the account.

getId int getId()

Unique ID for the account.


User name, used for signing in.

getRole String getRole()

Role for the user: admin or not.

getAccountGroups

List<AccountGroup> getAccountGroups()

List of groups this account belongs to.

See: AccountGroup

getAuthenticationSource

AuthenticationSource getAuthenticationSource()

Source of the account: LDAP, built-in, …

See: AuthenticationSource

189

getEmail

String getEmail()

Email for the account.

getFullName

String getFullName()

Display name for the account.

getId

int getId()

Unique ID for the account.

getName

String getName()

User name, used for signing in.

getRole

String getRole()

Role for the user: admin or not.

9.9.5. AccountGroup

Account group. Just a name and a description.


Method summary

Method Description


Description of the group.

getId int getId()

Unique ID for the group.


Name of the group. Unique.

190

getDescription


Description of the group.

getId

int getId()

Unique ID for the group.

getName

String getName()

Name of the group. Unique.

9.9.6. Admin

Administration management

Method summary

Method Description

account Account account(String name, String fullName,String email, String password = '', ListgroupNames = [])

Creates or updates an account.

accountGroup AccountGroup accountGroup(String name, Stringdescription)

Creates or updates an account group.

getAccountGlobalPermissions List<Role> getAccountGlobalPermissions(StringaccountName)

Gets the list of global roles an account has. SeeAccount permissions.

getAccountGroupGlobalPermissions List<Role>getAccountGroupGlobalPermissions(StringgroupName)

Gets the list of global roles an account group has.See Account group permissions.

getAccountGroupProjectPermissions List<Role>getAccountGroupProjectPermissions(StringprojectName, String groupName)

Gets the list of roles an account group has on aproject. See Account group permissions.

191

getAccountProjectPermissions List<Role> getAccountProjectPermissions(StringprojectName, String accountName)

Gets the list of roles an account has on a project.See Account permissions.

getAccounts List<Account> getAccounts()

Returns the list of all accounts.

getGroups List<AccountGroup> getGroups()

Returns the list of all groups.

getLdapMappings List<GroupMapping> getLdapMappings()

Gets the list of LDAP mappings.

getStatus Object getStatus()

Gets the health/status of the application

ldapMapping GroupMapping ldapMapping(String name, StringgroupName)

Creates or updates a LDAP mapping.

setAccountGlobalPermission void setAccountGlobalPermission(StringaccountName, String globalRole)

Sets a global role on an account. See Accountpermissions.

setAccountGroupGlobalPermission void setAccountGroupGlobalPermission(StringgroupName, String globalRole)

Sets a global role on an account group. SeeAccount group permissions.

setAccountGroupProjectPermission void setAccountGroupProjectPermission(StringprojectName, String groupName, StringprojectRole)

Sets a project role on an account group. SeeAccount group permissions.

setAccountProjectPermission void setAccountProjectPermission(StringprojectName, String accountName, StringprojectRole)

Sets a project role on an account. See Accountpermissions.

192

account

Account account(String name, String fullName, String email, String password = '', ListgroupNames = [])

Creates or updates an account.

See: Account This method is used only to create built-in accounts. There is no need to create LDAP-based accounts.

The name, fullName and email parameters are required and unique. The password is required onlywhen creating a new account, not when updating it.

The list of groups the account must belong to is provided using the names of the groups.

ontrack.admin { account 'test', 'Test user', 'xxx'}

accountGroup

AccountGroup accountGroup(String name, String description)

Creates or updates an account group.

See: AccountGroup

getAccountGlobalPermissions

List<Role> getAccountGlobalPermissions(String accountName)

Gets the list of global roles an account has. See Account permissions.

getAccountGroupGlobalPermissions

List<Role> getAccountGroupGlobalPermissions(String groupName)

Gets the list of global roles an account group has. See Account group permissions.

getAccountGroupProjectPermissions

List<Role> getAccountGroupProjectPermissions(String projectName, String groupName)

Gets the list of roles an account group has on a project. See Account group permissions.

193

getAccountProjectPermissions

List<Role> getAccountProjectPermissions(String projectName, String accountName)

Gets the list of roles an account has on a project. See Account permissions.

getAccounts

List<Account> getAccounts()

Returns the list of all accounts.

See: Account

getGroups

List<AccountGroup> getGroups()

Returns the list of all groups.

See: AccountGroup

getLdapMappings

List<GroupMapping> getLdapMappings()

Gets the list of LDAP mappings.

See: GroupMapping

getStatus

Object getStatus()

Gets the health/status of the application

194

ldapMapping

GroupMapping ldapMapping(String name, String groupName)

Creates or updates a LDAP mapping.

See: GroupMapping The name parameter is the name of the group in the LDAP.

The groupName parameter is the name of the group in Ontrack. It must exist.

ontrack.admin { accountGroup 'MyGroup', 'An Ontrack group' ldapMapping 'GroupInLDAP', 'MyGroup'}

setAccountGlobalPermission

void setAccountGlobalPermission(String accountName, String globalRole)

Sets a global role on an account. See Account permissions.

setAccountGroupGlobalPermission

void setAccountGroupGlobalPermission(String groupName, String globalRole)

Sets a global role on an account group. See Account group permissions.

setAccountGroupProjectPermission

void setAccountGroupProjectPermission(String projectName, String groupName, StringprojectRole)

Sets a project role on an account group. See Account group permissions.

setAccountProjectPermission

void setAccountProjectPermission(String projectName, String accountName, String projectRole)

Sets a project role on an account. See Account permissions.

9.9.7. AuthenticationSource

Authentication source for an account - indicates how the account is authenticated: LDAP, built-in,etc.


Method summary

Method Description

195

getId String getId()

Identifier for the source: ldap, password


Display name for the source

isAllowingPasswordChange boolean isAllowingPasswordChange()

Does this source allow to change the password?

getId

String getId()

Identifier for the source: ldap, password

getName

String getName()

Display name for the source

isAllowingPasswordChange

boolean isAllowingPasswordChange()

Does this source allow to change the password?

9.9.8. Branch

See also: AbstractProjectResource

Go to the methods

Configuration properties

See also: ProjectEntityProperties

Configuration property summary

Property Description

artifactorySync Object artifactorySync(String configuration,String buildName, String buildNameFilter ='*', int interval = 0)

getArtifactorySync Object getArtifactorySync()

getGitBranch Object getGitBranch()

getSvn Object getSvn()

getSvnSync Object getSvnSync()

getSvnValidatorClosedIssues Object getSvnValidatorClosedIssues()

196

gitBranch Object gitBranch(String branch, Map params =[:])

svn Object svn(Map params = [:])

svnSync Object svnSync(int interval = 0, booleanoverride = false)

svnValidatorClosedIssues Object svnValidatorClosedIssues(CollectionclosedStatuses)

197

198

Configuration: gitBranch

Object gitBranch(String branch, Map params = [:])

Defines the Git properties for an Ontrack branch. branch is the name of the Git branch. Possibleparameters are:

• buildCommitLink.id & buildCommitLink.data are the definition of the link between the Ontrackbuilds and the Git commits. See the samples below.

• override - true or false - defines if the synchronisation overrides or not the existing builds(defaults to false)

• buildTagInterval - interval in minutes between each synchronisation between the builds andGit branch. 0 (default) to disable. Note that not all build commit links allow for synchronisation

Examples:

• for a branch whose build names are long commits (the default):

ontrack.branch('project') { branch('1.0') { config { gitBranch 'release/1.0' } }}

• for a branch whose build names are short commits:

ontrack.branch('project') { branch('1.0') { config { gitBranch 'release/1.0', [ buildCommitLink: [ id: 'commit', data: [ abbreviated: true ] ] ] } }}

• for a branch whose build names are associated to Git tags following a given pattern

199

ontrack.branch('project') { branch('1.0') { config { gitBranch 'release/1.0', [ buildCommitLink: [ id: 'tagPattern', data: [ pattern: '1.0.*' ] ] ] } }}

• for a branch whose build are associated to Git commits using a Git property:

ontrack.branch('project') { branch('1.0') { config { gitBranch 'release/1.0', [ buildCommitLink: [ id: 'git-commit-property' ] ] } }}

The builds of this branch can be associated with a Git commit using thebuild.config.gitCommit method.

Configuration: svn

Object svn(Map params = [:])

To get the SVN branch configuration:

def getSvn()

To associate a branch with some Subversion properties:

def svn (Map<String, ?> params)

The project the branch belongs to must be configured for Subversion.

The parameters are:

• branchPath - required - the path to the branch, relative to the repository

• link - optional - type of build link:

◦ tag for build name as tag (default)

◦ tagPattern for build name as tag pattern

◦ revision for build name as revision

◦ revisionPattern for build name containing the revision

◦ see the Working with Subversion documentation for more details

• data - optional - configuration data for the link, typically [pattern: '…'] for tagPattern andrevisionPattern links

Example:

ontrack.project('project') { config { svn 'myconfig', '/project/trunk' } branch('mybranch') { config { svn branchPath: '/project/branches/mybranch', link: 'revisionPattern', data: [pattern: '2.0.*-{revision}'] } }}def cfg = ontrack.branch('project', 'mybranch').config.svnassert cfg.branchPath == '/project/branches/mybranch'assert cfg.buildRevisionLink.id == 'revisionPattern'assert cfg.buildRevisionLink.data.pattern == '11.8.4.*-{revision}'

200

Configuration: getSvn

Object getSvn()

See svn

Configuration: getGitBranch

Object getGitBranch()

See gitBranch

Configuration: svnValidatorClosedIssues

Object svnValidatorClosedIssues(Collection closedStatuses)

A SVN-enabled branch can be associated with a validator in order to validate if there are someanomalies for the issues in the change logs.

def svnValidatorClosedIssues(Collection<String> closedStatuses)

Sets the list of issues statuses which can raise warnings if one of the issues is present after thechange log.

def getSvnValidatorClosedIssues()

Gets the list of statuses to look for.

Example:

ontrack.configure { svn 'myconfig', url: 'svn://localhost'}ontrack.project('project') { config { svn 'myconfig', '/project/trunk' } branch('test') { config { svn '/project/branches/mybranch', '/project/tags/{build:mybranch-*}' svnValidatorClosedIssues(['Closed']) } }}assert ontrack.branch('project','test').config.svnValidatorClosedIssues.closedStatuses == ['Closed']

201

Configuration: getSvnValidatorClosedIssues

Object getSvnValidatorClosedIssues()

See svnValidatorClosedIssues

Configuration: svnSync

Object svnSync(int interval = 0, boolean override = false)

For a Subversion-enabled branch, an automated synchronisation can be set in order to regularlycreate builds from the list of tags in Subversion.

def svnSync(int interval = 0, boolean override = false)

Sets a synchronisation every interval minutes (0 meaning no sync at all). The override flag is usedto allow existing builds to be overridden.

Example:

ontrack.configure { svn 'myconfig', url: 'svn://localhost'}ontrack.project('project') { config { svn 'myconfig', '/project/trunk' } branch('test') { config { svn '/project/branches/mybranch', '/project/tags/{build:mybranch-*}' svnSync 30 } }}def sync = ontrack.branch('project', 'test').config.svnSyncassert sync.override == falseassert sync.interval == 30

Configuration: getSvnSync

Object getSvnSync()

See svnSync

202

Configuration: artifactorySync

Object artifactorySync(String configuration, String buildName, String buildNameFilter = '*',int interval = 0)

Branch builds can be synchronised with Artifactory:

def artifactorySync(String configuration, String buildName, String buildNameFilter = '*', intinterval = 0)

and the corresponding configuration can be accessed:

def getArtifactorySync()

Example:

ontrack.configure { artifactory 'Artifactory', 'http://artifactory'}ontrack.project('project') { branch('test') { config { artifactorySync 'Artifactory', 'test', 'test-*', 30 } }}def sync = ontrack.branch('project', 'test').config.artifactorySyncassert sync.configuration.name == 'Artifactory'assert sync.buildName == 'test'assert sync.buildNameFilter == 'test-*'assert sync.interval == 30

See also Artifactory configuration to have access to the list of available configurations.

Configuration: getArtifactorySync

Object getArtifactorySync()

See artifactorySync

Method summary

Method Description

build Build build(String name, String description ='', boolean getIfExists = false)

Creates a build for the branch

203

build Build build(String name, String description ='', boolean getIfExists = false, Closureclosure)

Creates a build for the branch and configures itusing a closure. See build.

call Object call(Closure closure)

Configures the branch using a closure.

disable Object disable()

Disables the branch

download String download(String path)

enable Object enable()

Enables the branch

filter List<Build> filter(String filterType, MapfilterConfig)

Runs any filter and returns the list ofcorresponding builds.

getConfig BranchProperties getConfig()

Access to the branch properties

getInstance TemplateInstance getInstance()

getLastPromotedBuilds List<Build> getLastPromotedBuilds()

Returns the last promoted builds.

getProject String getProject()

Returns the name of the project the branchbelongs to.

getPromotionLevels List<PromotionLevel> getPromotionLevels()

Gets the list of promotion levels for this branch.

getType String getType()

getValidationStamps List<ValidationStamp> getValidationStamps()

Gets the list of validation stamps for this branch.

instance Branch instance(String sourceName, Map params)

Creates or updates a new branch from thisbranch template. See DSL Branch templatedefinitions.

isDisabled boolean isDisabled()

Gets the disabled state of the branch

204

link Object link(String templateName, booleanmanual = true, Map parameters)

promotionLevel PromotionLevel promotionLevel(String name,String description = '', boolean getIfExists =false)

Creates a promotion level for this branch.

promotionLevel PromotionLevel promotionLevel(String name,String description = '', boolean getIfExists =false, Closure closure)

Creates a promotion level for this branch andconfigures it using a closure.

standardFilter List<Build> standardFilter(Map filterConfig)

Returns a list of builds for the branch, filteredaccording to given criteria.

sync Object sync()

Synchronizes the branch template with itsassociated instances. Will fail if this branch isnot a template.

syncInstance Object syncInstance()

Synchronises the branch instance with itsassociated template. Will fail if this branch is nota template instance.

template Object template(Closure closure)

Configure the branch as a template definition -see DSL Branch template definitions.

unlink Object unlink()

validationStamp ValidationStamp validationStamp(String name,String description = '', boolean getIfExists =false)

Creates a validation stamp for this branch.

validationStamp ValidationStamp validationStamp(String name,String description = '', boolean getIfExists =false, Closure closure)

Creates a validation stamp for this branch andconfigures it using a closure.

205

build

Build build(String name, String description = '', boolean getIfExists = false)

Creates a build for the branch

See: Build For example,

def build = ontrack.branch('project', 'branch').build('123', '', true)

Settings the getIfExists parameter to true will return the build if it already exists, and will fail ifset to false.

build

Build build(String name, String description = '', boolean getIfExists = false, Closureclosure)

Creates a build for the branch and configures it using a closure. See build.

See: Build

call

Object call(Closure closure)

Configures the branch using a closure.

disable

Object disable()

Disables the branch

download

String download(String path)

Download a file from the branch SCM.

The branch must be associated with a SCM branch, for Git or Subversion. If not, the call will fail.

The path is relative to the root of the branch in the SCM and is always returned as text.

For security, only users allowed to configure the project will be able to downloada file from the branch. See Security for the list of roles.

See also DSL SCM extensions.

206

enable

Object enable()

Enables the branch

filter

List<Build> filter(String filterType, Map filterConfig)

Runs any filter and returns the list of corresponding builds.

See: Build This is a low level method and more specialised methods should instead be used likestandardFilter and getLastPromotedBuilds.

getConfig

BranchProperties getConfig()

Access to the branch properties

getInstance

TemplateInstance getInstance()

If the branch is a template instance, returns a TemplateInstance object which contains the list ofthis instance parameters as a Map in the parameters property. Otherwise returns null.

ontrack.project('project') { branch('template') { template { parameter 'paramName', 'A parameter' } }}ontrack.branch(project, 'template').instance 'TEST', [ paramName: 'paramValue']def instance = ontrack.branch(project, 'TEST').instanceassert instance.parameters == [paramName: 'paramValue']

207

getLastPromotedBuilds

List<Build> getLastPromotedBuilds()

Returns the last promoted builds.

See: Build For example, to get the last promoted build:

def buildName = ontrack.branch('project', 'branch').lastPromotedBuilds[0].name

getProject

String getProject()

Returns the name of the project the branch belongs to.

Sample:

def branch = ontrack.branch('prj', 'master')assert branch.project == 'prj'

getPromotionLevels

List<PromotionLevel> getPromotionLevels()

Gets the list of promotion levels for this branch.

See: PromotionLevel

getType

String getType()

Returns the type of the branch when it comes to templating.

Possible values are:

• CLASSIC

• TEMPLATE_DEFINITION

• TEMPLATE_INSTANCE

208

getValidationStamps

List<ValidationStamp> getValidationStamps()

Gets the list of validation stamps for this branch.


instance

Branch instance(String sourceName, Map params)

Creates or updates a new branch from this branch template. See DSL Branch template definitions.

isDisabled

boolean isDisabled()

Gets the disabled state of the branch

link

Object link(String templateName, boolean manual = true, Map parameters)

Links a branch to an existing template. It will fail if the branch is already linked to a template or isa template definition itself. See unlink to unlink a branch to its template.

The templateName is the name of the branch template, and the parameters map contains the valuesneeded to instantiate the template.

You can put the manual flag to false if the template definition does not need any parameter tocreate the instance.

promotionLevel

PromotionLevel promotionLevel(String name, String description = '', boolean getIfExists =false)

Creates a promotion level for this branch.

See: PromotionLevel

promotionLevel

PromotionLevel promotionLevel(String name, String description = '', boolean getIfExists =false, Closure closure)

Creates a promotion level for this branch and configures it using a closure.

See: PromotionLevel

209

210

standardFilter

List<Build> standardFilter(Map filterConfig)

Returns a list of builds for the branch, filtered according to given criteria.

See: Build For example, to get the last build of a given promotion:

def branch = ontrack.branch('project', 'branch')def builds = branch.standardFilter count: 1, withPromotionLevel: 'BRONZE'def buildName = builds[0].name

Builds are always returned from the most recent one to the oldest.

The standardFilter method accepts the following parameters:


count Maximum number of builds to be returned.Defaults to 10.

sincePromotionLevel Name of a promotion level. After reaching thefirst build having this promotion, no furtherbuild is returned.

withPromotionLevel Name of a promotion level. Only builds havingthis promotion are returned.

afterDate ISO 8601 date. Only builds having been createdon or after this date are returned.

beforeDate ISO 8601 date. Only builds having been createdon or before this date are returned.

sinceValidationStamp Name of a validation stamp. After reaching thefirst build having this validation (whatever thestatus), no further build is returned.

sinceValidationStampStatus Refines the sinceValidationStamp criteria tocheck on the status of the validation.

withValidationStamp Name of a validation stamp. Only builds havingthis validation (whatever the status) arereturned.

withValidationStampStatus Refines the withValidationStamp criteria tocheck on the status of the validation.

withProperty Qualified name of a property (full class name ofthe PropertyType). Only builds having thisproperty being set are returned.

withPropertyValue Refines the withProperty criteria to check theproperty value. The way the value is matchedwith the actual value depends on the property.

sinceProperty Qualified name of a property (full class name ofthe PropertyType).After reaching the first buildhaving this property being set, no further buildis returned.

211

https://en.wikipedia.org/wiki/ISO_8601

https://en.wikipedia.org/wiki/ISO_8601


sincePropertyValue Refines the sinceProperty criteria to check theproperty value. The way the value is matchedwith the actual value depends on the property.

linkedFrom Selects builds which are linked from the buildselected by the criteria. See Build links for theexact syntax.

linkedFromPromotion The build must be linked FROM a build havingthis promotion (requires "Linked from")

linkedTo Selects builds which are linked to the buildselected by the criteria. See Build links for theexact syntax.

linkedToPromotion The build must be linked TO a build having thispromotion (requires "Linked to")

sync

Object sync()

Synchronizes the branch template with its associated instances. Will fail if this branch is not atemplate.

syncInstance

Object syncInstance()

Synchronises the branch instance with its associated template. Will fail if this branch is not atemplate instance.

template

Object template(Closure closure)

Configure the branch as a template definition - see DSL Branch template definitions.

unlink

Object unlink()

Disconnects the branch template instance from its template:

assert ontrack.branch('project', 'test').type == 'TEMPLATE_INSTANCE'ontrack.branch('project', 'test').unlink()assert ontrack.branch('project', 'test').type == 'CLASSIC'

validationStamp

ValidationStamp validationStamp(String name, String description = '', boolean getIfExists =false)

Creates a validation stamp for this branch.


validationStamp

ValidationStamp validationStamp(String name, String description = '', boolean getIfExists =false, Closure closure)

Creates a validation stamp for this branch and configures it using a closure.


212

9.9.9. Build

In order to get the change log between two builds, look at the documentation at DSL Change logs.


Go to the methods





getGitCommit Object getGitCommit()

Gets the Git commit associated to this build.

getJenkinsBuild Object getJenkinsBuild()

Gets the Jenkins build property.

getLabel Object getLabel()

Gets any label attached to the build. Returns nullif none is attached.

gitCommit Object gitCommit(String commit)

Sets a Git commmit associated to this build.

jenkinsBuild Object jenkinsBuild(String configuration,String job, int buildNumber)

Associates a Jenkins build with this build.

label Object label(String name)

213

Configuration: label

Object label(String name)

A label or release can be attached to a build using:

def label(String name)

For example:

ontrack.build('project', 'branch', 'build').config { label 'RC1'}

To get the label associated with a build:

def name = ontrack.build('project', 'branch', 'build').config.labelassert name == 'RC1'

Configuration: getLabel

Object getLabel()

Gets any label attached to the build. Returns null if none is attached.

See label

Configuration: jenkinsBuild

Object jenkinsBuild(String configuration, String job, int buildNumber)

Associates a Jenkins build with this build.

The configuration parameter is the name of an existing Jenkins configuration.

The job parameter is the path to the Jenkins job. For a job test as the Jenkins root, it would be onlytest but for a job test2 in a folder parent2 which is itself in a folder parent1 at the root, this wouldbe parent1/parent2/test2.

The buildNumber is the number of the Jenkins build.

this link is created automatically when using the Ontrack Jenkins plug-in.

214


Configuration: getJenkinsBuild

Object getJenkinsBuild()

Gets the Jenkins build property.

Returns an object describing the associated Jenkins build or null if none.

The returned object contains the following attributes:

• a configuration object, having itself a name and a url attribute

• a name - path to the job in Jenkins

• a url - absolute URL to the build page

• a pathComponents list of string - same than path but as list of separate components

• a build number

Even if a link to a Jenkins build is registered, this does not mean that the actualJenkins build still actually exists.

Configuration: gitCommit

Object gitCommit(String commit)

Sets a Git commmit associated to this build.

When working with Git, it is needed to associate a build with a commit. It can be done by using thebuild name itself as a commit indicator (full, short, or tag) or by putting the commit as a buildproperty:

def gitCommit(String commit)

To get the commit back:

def getGitCommit()

Example:

ontrack.project('project') { branch('test') { build('1') { config { gitCommit 'adef13' } } }}assert ontrack.build('project', 'test', '1').config.gitCommit == 'adef13'

215

Configuration: getGitCommit

Object getGitCommit()

Gets the Git commit associated to this build.

Method summary

Method Description

buildLink Object buildLink(String project, String build)


Configuration of the build in a closure.

getBranch String getBranch()

Gets the build branch name.

getBuildLinkDecorations List<> getBuildLinkDecorations()

Returns the build links associated with this build

getBuildLinks List<Build> getBuildLinks()

getChangeLog ChangeLog getChangeLog(Build otherBuild)

Computes the change log between this build andthe one given in parameter.

getConfig BuildProperties getConfig()

getNextBuild Build getNextBuild()

Returns the next build in the same branch, ornull if there is none.

getPreviousBuild Build getPreviousBuild()

Returns the previous build in the same branch,or null if there is none.


Gets the build project name.

getPromotionRuns List<PromotionRun> getPromotionRuns()

Gets the list of promotion runs for this build

getReleaseDecoration String getReleaseDecoration()

Returns any label associated with this build.

getRunInfo RunInfo getRunInfo()

Gets the associated run info with this build, ornull if none

getSvnRevisionDecoration Long getSvnRevisionDecoration()

216

getValidationRuns List<ValidationRun> getValidationRuns()

Gets the list of validation runs for this build

promote PromotionRun promote(String promotion, Closureclosure)

Promotes this build to the given promotion leveland configures the created promotion run.

promote PromotionRun promote(String promotion)

Promotes this build to the given promotion level.

setRunInfo void setRunInfo(Map info)

Sets the run info for this build.

signature Object signature(String user = null, Date date= null)

validate ValidationRun validate(String validationStamp,String validationStampStatus = 'PASSED',String description = "")

validate ValidationRun validate(String validationStamp,String validationStampStatus = 'PASSED',Closure closure)

validateWithCHML ValidationRun validateWithCHML(StringvalidationStamp, int critical = 0, int high =0, int medium = 0, int low = 0, String status= null)

Associates some critical / high / medium / lowissue counts with the validation. The validationstamp must be configured to accept CHML asvalidation data.

validateWithData ValidationRun validateWithData(StringvalidationStamp, Object data, String dataType= null, String status = null)

Associates some data with the validation.

validateWithFraction ValidationRun validateWithFraction(StringvalidationStamp, int numerator, intdenominator, String status = null)

Associates some fraction with the validation.The validation stamp must be configured toaccept fraction as validation data.

validateWithMetrics ValidationRun validateWithMetrics(StringvalidationStamp, Map metrics, String status =null)

Associates some arbitrary metrics with thevalidation.

217

validateWithNumber ValidationRun validateWithNumber(StringvalidationStamp, int value, String status =null)

Associates some number with the validation.The validation stamp must be configured toaccept number as validation data.

validateWithPercentage ValidationRun validateWithPercentage(StringvalidationStamp, int value, String status =null)

Associates some percentage with the validation.The validation stamp must be configured toaccept percentage as validation data.

validateWithText ValidationRun validateWithText(StringvalidationStamp, String status, String text)

Associates some text with the validation. Thevalidation stamp must be configured to accepttext as validation data.

218

buildLink

Object buildLink(String project, String build)

A build can be linked to other builds.

To create links:

def build = ...build.buildLink 'project1', '11.0'build.buildLink 'project2', '2.3.1'

Several links can be attached to a build, by calling the buildLink method severaltimes.

The target project and build must exist.

To get the list of linked builds:

def links = build.buildLinksassert links.size == 2def link = links[0]assert link.project = 'project1'assert link.branch = '...'assert link.name = '11.0'assert link.page = '...' // URL to the build page

The page property of the link is a URL to the page of the link.

call


Configuration of the build in a closure.

getBranch

String getBranch()

Gets the build branch name.

getBuildLinkDecorations

List<> getBuildLinkDecorations()

Returns the build links associated with this build

219

getBuildLinks

List<Build> getBuildLinks()

See buildLink

getChangeLog

ChangeLog getChangeLog(Build otherBuild)

Computes the change log between this build and the one given in parameter.

See: ChangeLog

getConfig

BuildProperties getConfig()

getNextBuild

Build getNextBuild()

Returns the next build in the same branch, or null if there is none.

getPreviousBuild

Build getPreviousBuild()

Returns the previous build in the same branch, or null if there is none.

getProject

String getProject()

Gets the build project name.

getPromotionRuns

List<PromotionRun> getPromotionRuns()

Gets the list of promotion runs for this build

See: PromotionRun

getReleaseDecoration

String getReleaseDecoration()

Returns any label associated with this build.

220

getRunInfo

RunInfo getRunInfo()

Gets the associated run info with this build, or null if none

The returned object has the following properties:

• sourceType - Type of source (like "jenkins")

• sourceUri - URI to the source of the run (like the URL to a Jenkins job)

• triggerType - Type of trigger (like "scm" or "user")

• triggerData - Data associated with the trigger (like a user ID or a commit)

• runTime - Time of the run (in seconds)

Example:

def build = ontrack.build('project', 'branch', '1')def info = build.runInfoassert info != nullassert info.runTime == 30

getSvnRevisionDecoration

Long getSvnRevisionDecoration()

Returns any Subversion revision attached to this build.

def build = ontrack.build('project', 'branch', '1')Long revision = build.svnRevisionDecorationassert revision != null

getValidationRuns

List<ValidationRun> getValidationRuns()

Gets the list of validation runs for this build

See: ValidationRun

promote

PromotionRun promote(String promotion, Closure closure)

Promotes this build to the given promotion level and configures the created promotion run.

See: PromotionRun

221

promote

PromotionRun promote(String promotion)

Promotes this build to the given promotion level.

See: PromotionRun

setRunInfo

void setRunInfo(Map info)

Sets the run info for this build.

Accepted parameters are:






Example:

def build = ontrack.build('project', 'branch', '1')build.runInfo triggerType: "user", triggerData: "damien", runTime: 45

signature

Object signature(String user = null, Date date = null)

Sets the signature of the build. This method is granted only for users having the ProjectEditfunction: administrators, project owners, project managers.

Date is expected to be UTC.

validate

ValidationRun validate(String validationStamp, String validationStampStatus = 'PASSED',String description = "")

See: ValidationRun Validates the build using the given validation stamp and status - and configuresthe resulting validation run.

222

validate

ValidationRun validate(String validationStamp, String validationStampStatus = 'PASSED',Closure closure)

See: ValidationRun Validates the build using the given validation stamp and status - possiblevalues for the status are: PASSED, FAILED, DEFECTIVE, EXPLAINED, FIXED, INTERRUPTED, INVESTIGATING,WARNING

validateWithCHML

ValidationRun validateWithCHML(String validationStamp, int critical = 0, int high = 0, intmedium = 0, int low = 0, String status = null)

Associates some critical / high / medium / low issue counts with the validation. Thevalidation stamp must be configured to accept CHML as validation data.

See: ValidationRun

validateWithData

ValidationRun validateWithData(String validationStamp, Object data, String dataType = null,String status = null)

Associates some data with the validation.

See: ValidationRun

validateWithFraction

ValidationRun validateWithFraction(String validationStamp, int numerator, int denominator,String status = null)

Associates some fraction with the validation. Thevalidation stamp must be configured to accept fraction as validation data.

See: ValidationRun

validateWithMetrics

ValidationRun validateWithMetrics(String validationStamp, Map metrics, String status = null)

Associates some arbitrary metrics with the validation.

See: ValidationRun

223

validateWithNumber

ValidationRun validateWithNumber(String validationStamp, int value, String status = null)

Associates some number with the validation. Thevalidation stamp must be configured to accept number as validation data.

See: ValidationRun

validateWithPercentage

ValidationRun validateWithPercentage(String validationStamp, int value, String status = null)

Associates some percentage with the validation. Thevalidation stamp must be configured to accept percentage as validation data.

See: ValidationRun

validateWithText

ValidationRun validateWithText(String validationStamp, String status, String text)

Associates some text with the validation. The validation stamp must be configured to accept textas validation data.

See: ValidationRun

9.9.10. ChangeLog

Change log between two builds. See getChangeLog method.


Method summary

Method Description

exportIssues String exportIssues(Map map)

Export the issue change log. See this section foran example.

getCommits List<ChangeLogCommit> getCommits()

List of commits in the change log.

getFiles List<ChangeLogFile> getFiles()

List of file changes in the change log.

224

getFrom Build getFrom()

Lower boundary of the change log.

getIssues List<ChangeLogIssue> getIssues()

List of issues in the change log.

getIssuesIds List<String> getIssuesIds()

List of issues IDs in the change log.

getTo Build getTo()

Upper boundary of the change log.

getUuid String getUuid()

UUID of the change log.

exportIssues

String exportIssues(Map map)

Export the issue change log. See this section for an example.

getCommits

List<ChangeLogCommit> getCommits()

List of commits in the change log.

See: ChangeLogCommit

getFiles

List<ChangeLogFile> getFiles()

List of file changes in the change log.

See: ChangeLogFile

getFrom

Build getFrom()

Lower boundary of the change log.

See: Build

225

getIssues

List<ChangeLogIssue> getIssues()

List of issues in the change log.

See: ChangeLogIssue

getIssuesIds

List<String> getIssuesIds()

List of issues IDs in the change log.

getTo

Build getTo()

Upper boundary of the change log.

See: Build

getUuid

String getUuid()

UUID of the change log.

9.9.11. ChangeLogCommit


Method summary

Method Description

getAuthor String getAuthor()

Gets the author name of the commit

getAuthorEmail String getAuthorEmail()

Gets the author email of the commit. Can be nullif not available.

getFormattedMessage String getFormattedMessage()

Gets the formatted message of the commit,where issues might have been replaced by links.

getId String getId()

Gets the full hash of the commit

226

getLink String getLink()

Gets a link to SCM for this commit.

getMessage String getMessage()

Gets the trimmed message of the commit.

getShortId String getShortId()

Gets the abbreviated hash of the commit

getTimestamp String getTimestamp()

Gets the timestamp of the commit as a ISO datestring.

getAuthor

String getAuthor()

Gets the author name of the commit

getAuthorEmail

String getAuthorEmail()

Gets the author email of the commit. Can be null if not available.

getFormattedMessage

String getFormattedMessage()

Gets the formatted message of the commit, where issues might have been replaced by links.

getId

String getId()

Gets the full hash of the commit

getLink

String getLink()

Gets a link to SCM for this commit.

getMessage

String getMessage()

Gets the trimmed message of the commit.

227

getShortId

String getShortId()

Gets the abbreviated hash of the commit

getTimestamp

String getTimestamp()

Gets the timestamp of the commit as a ISO date string.

9.9.12. ChangeLogFile


Method summary

Method Description

getChangeType String getChangeType()

Change type for this file. Can be one of: ADDED,MODIFIED, DELETED, RENAMED, COPIED,UNDEFINED

getChangeTypes List<String> getChangeTypes()

List of possible change types. Can be one of:ADDED, MODIFIED, DELETED, RENAMED,COPIED, UNDEFINED

getPath String getPath()

Relative path to the file being changed.

getChangeType

String getChangeType()

Change type for this file. Can be one of: ADDED, MODIFIED, DELETED, RENAMED, COPIED,UNDEFINED

getChangeTypes

List<String> getChangeTypes()

List of possible change types. Can be one of: ADDED, MODIFIED, DELETED, RENAMED, COPIED,UNDEFINED

228

getPath

String getPath()

Relative path to the file being changed.

9.9.13. ChangeLogIssue


Method summary

Method Description

getDisplayKey String getDisplayKey()

Gets the display key for this issue. For example,#22 for a GitHub issue.

getKey String getKey()

Gets the technical key for this issue. Forexample, 22 for a GitHub issue.

getStatus String getStatus()

Gets the status of this issue.

getSummary String getSummary()

Gets the summary for this issue.

getUpdateTime String getUpdateTime()

Gets the last update time for this issue, as ISOdate string.

getUrl String getUrl()

Gets the URL to this issue.

getDisplayKey

String getDisplayKey()

Gets the display key for this issue. For example, #22 for a GitHub issue.

getKey

String getKey()

Gets the technical key for this issue. For example, 22 for a GitHub issue.

229

getStatus

String getStatus()

Gets the status of this issue.

getSummary

String getSummary()

Gets the summary for this issue.

getUpdateTime

String getUpdateTime()

Gets the last update time for this issue, as ISO date string.

getUrl

String getUrl()

Gets the URL to this issue.

9.9.14. Config

General configuration of Ontrack.

Method summary

Method Description

artifactory Object artifactory(String name, String url,String user = '', String password = '')

Creates or updates a Artifactory configuration.

getArtifactory List<String> getArtifactory()

getGit List<String> getGit()

getGitHub List<String> getGitHub()

getGitLab List<String> getGitLab()

getGrantProjectViewToAll boolean getGrantProjectViewToAll()

Checks if the projects are accessible inanonymous mode.

getJenkins List<String> getJenkins()

getJira List<String> getJira()

getLabel Label getLabel(String category, String name)

Gets an existing label or returns null

230

getLabels List<Label> getLabels()

Gets the list of labels

getLdapSettings LDAPSettings getLdapSettings()

Gets the global LDAP settings

getMainBuildLinks List<String> getMainBuildLinks()

Gets the main build links settings

getPredefinedPromotionLevels List<PredefinedPromotionLevel>getPredefinedPromotionLevels()

Gets the list of promotion levels. SeeautoPromotionLevel.

getPredefinedValidationStamps List<PredefinedValidationStamp>getPredefinedValidationStamps()

Gets the list of validation stamps. SeeautoValidationStamp.

getPreviousPromotionRequired boolean getPreviousPromotionRequired()

Gets the previous promotion condition settings

getSonarQube List<String> getSonarQube()

Gets the list of SonarQube configuration ids

getSonarQubeSettings SonarQubeMeasuresSettingsgetSonarQubeSettings()

Gets the global SonarQube settings

getStash List<String> getStash()


git Object git(Map parameters, String name)

Creates or update a Git configuration

gitHub Object gitHub(Map parameters, String name)

gitHub Object gitHub(String name)

gitLab Object gitLab(Map parameters, String name)

jenkins Object jenkins(String name, String url, Stringuser = '', String password = '')

Creates or updates a Jenkins configuration.

jira Object jira(String name, String url, Stringuser = '', String password = '')

Creates or updates a JIRA configuration.

231

label Label label(String category, String name,String description = "", String color ="#000000")

Creates or updates a label

predefinedPromotionLevel PredefinedPromotionLevelpredefinedPromotionLevel(String name, Stringdescription = '', boolean getIfExists = false)

See autoPromotionLevel.

predefinedPromotionLevel PredefinedPromotionLevelpredefinedPromotionLevel(String name, Stringdescription = '', boolean getIfExists = false,Closure closure)


predefinedValidationStamp PredefinedValidationStamppredefinedValidationStamp(String name, Stringdescription = '', boolean getIfExists = false,Closure closure)

See autoValidationStamp.

predefinedValidationStamp PredefinedValidationStamppredefinedValidationStamp(String name, Stringdescription = '', boolean getIfExists = false)


setGrantProjectViewToAll Object setGrantProjectViewToAll(booleangrantProjectViewToAll)

Sets if the projects are accessible in anonymousmode.

setLdapSettings Object setLdapSettings(LDAPSettings settings)

Sets the global LDAP settings

setMainBuildLinks void setMainBuildLinks(List labels)

Sets the main build links settings

setPreviousPromotionRequired void setPreviousPromotionRequired(booleanpreviousPromotionRequired)

Sets the previous promotion condition settings

setSonarQubeSettings ObjectsetSonarQubeSettings(SonarQubeMeasuresSettingssettings)

Sets the global SonarQube settings

sonarQube Object sonarQube(String name, String url,String user = '', String password = '')

Creates or updates a SonarQube configuration.

232

stash Object stash(Map parameters, String name)

Creates or updates a BitBucket configuration.

svn Object svn(Map parameters, String name)

Creates a or updates a Subversion configuration.

artifactory

Object artifactory(String name, String url, String user = '', String password = '')

Creates or updates a Artifactory configuration.

Access to Artifactory is done through the configurations:

def artifactory(String name, String url, String user = '', String password = '')

The list of Artifactory configurations is accessible:

List<String> getArtifactory()

Example:

ontrack.configure { artifactory 'Artifactory', 'http://artifactory'}assert ontrack.config.artifactory.find { it == 'Artifactory' } != null

getArtifactory

List<String> getArtifactory()

See artifactory

getGit

List<String> getGit()

See git

getGitHub

List<String> getGitHub()

See gitHub

233

getGitLab

List<String> getGitLab()

See gitLab

getGrantProjectViewToAll

boolean getGrantProjectViewToAll()

Checks if the projects are accessible in anonymous mode.

Sample:

ontrack.config.grantProjectViewToAll = falseassert !ontrack.config.grantProjectViewToAll

getJenkins

List<String> getJenkins()

See jenkins

getJira

List<String> getJira()

See jira

getLabel

Label getLabel(String category, String name)

Gets an existing label or returns null

See: Label

getLabels

List<Label> getLabels()

Gets the list of labels

See: Label

234

getLdapSettings

LDAPSettings getLdapSettings()

Gets the global LDAP settings

See: LDAPSettings

getMainBuildLinks

List<String> getMainBuildLinks()

Gets the main build links settings

getPredefinedPromotionLevels

List<PredefinedPromotionLevel> getPredefinedPromotionLevels()

Gets the list of promotion levels. See autoPromotionLevel.

See: PredefinedPromotionLevel

getPredefinedValidationStamps

List<PredefinedValidationStamp> getPredefinedValidationStamps()

Gets the list of validation stamps. See autoValidationStamp.

See: PredefinedValidationStamp

getPreviousPromotionRequired

boolean getPreviousPromotionRequired()

Gets the previous promotion condition settings

getSonarQube

List<String> getSonarQube()

Gets the list of SonarQube configuration ids

getSonarQubeSettings

SonarQubeMeasuresSettings getSonarQubeSettings()

Gets the global SonarQube settings

See: SonarQubeMeasuresSettings

235

getStash

List<String> getStash()

See stash

getSvn

Object getSvn()

See svn

236

git

Object git(Map parameters, String name)

Creates or update a Git configuration

When working with Git, the access to the Git repositories must be configured.

def git(Map<String, ?> parameters, String name)

The name is the identifier of the configuration - if it already exists, it will be updated.

The parameters are the following:


remote the remote location

user user used to connect to GitHub (optional)

password password used to connect to GitHub (optional)

commitLink Link to a commit, using {commit} as placeholder

fileAtCommitLink Link to a file at a given commit, using {commit}and {path} as placeholders

indexationInterval interval (in minutes) between eachsynchronisation (Ontrack maintains internally aclone of the GitHub repository)

issueServiceConfigurationIdentifier identifier for the linked issues (see examplehere)

See the documentation to know the meaning of those parameters.

Example:

ontrack.configure { git 'ontrack', remote: 'https://github.com/nemerosa/ontrack.git', user: 'test',password: 'secret'}assert ontrack.config.git.find { it == 'ontrack' } != null

gitHub

Object gitHub(Map parameters, String name)

See gitHub

237

gitHub

Object gitHub(String name)

When working with GitHub, the access to the GitHub API must be configured.

def gitHub(Map<String, ?> parameters, String name)




url the GitHub URL - is set by default tohttps://github.com if not filled in, allowing forusing GitHub enterprise as well

user user used to connect to GitHub (optional)

password password used to connect to GitHub (optional)

oauth2Token OAuth token to use instead of a user/password(optional)

See Working with GitHub to know the meaning of those parameters.

Example:

ontrack.configure { gitHub 'github.com', oauth2Token: 'ABCDEF'}assert ontrack.config.gitHub.find { it == 'github.com' } != null

You can also configure an anonymous access to https://github.com (not recommended) by doing:

ontrack.configure { gitHub 'github.com'}

238

https://github.com

https://github.com

gitLab

Object gitLab(Map parameters, String name)

When working with GitLab, the access to the GitLab API must be configured.

def gitLab(Map<String, ?> parameters, String name)




url the URL to the GitLab application, without anyrepository nor project reference

user user used to connect to GitHub

password Personal Access Token associated with theuser

ignoreSslCertificate Set to true if SSL checks must be disabled(optional, default to false)

The password field must be a Personal Access Token - using the actual passwordis not supported.

Example:

ontrack.configure { gitLab 'AcmeGitLab', url: 'https://gitlab.acme.com', user: 'user', password:'abcdef'}assert ontrack.config.gitLab.find { it == 'AcmeGitLab' } != null

239

jenkins

Object jenkins(String name, String url, String user = '', String password = '')

Creates or updates a Jenkins configuration.

Access to Jenkins is done through the configurations:

def jenkins(String name, String url, String user = '', String password = '')

The list of Jenkins configurations is accessible:

List<String> getJenkins()

Example:

ontrack.configure { jenkins 'Jenkins', 'http://jenkins'}assert ontrack.config.jenkins.find { it == 'Jenkins' } != null

jira

Object jira(String name, String url, String user = '', String password = '')

Creates or updates a JIRA configuration.

Access to JIRA is done through the configurations:

def jira(String name, String url, String user = '', String password = '')

The list of JIRA configurations is accessible:

List<String> getJira()

Example:

ontrack.configure { jira 'JIRA', 'http://jira'}assert ontrack.config.jira.find { it == 'JIRA' } != null

label

Label label(String category, String name, String description = "", String color = "#000000")

Creates or updates a label

See: Label

240

predefinedPromotionLevel

PredefinedPromotionLevel predefinedPromotionLevel(String name, String description = '',boolean getIfExists = false)



predefinedPromotionLevel

PredefinedPromotionLevel predefinedPromotionLevel(String name, String description = '',boolean getIfExists = false, Closure closure)



predefinedValidationStamp

PredefinedValidationStamp predefinedValidationStamp(String name, String description = '',boolean getIfExists = false, Closure closure)



predefinedValidationStamp

PredefinedValidationStamp predefinedValidationStamp(String name, String description = '',boolean getIfExists = false)



setGrantProjectViewToAll

Object setGrantProjectViewToAll(boolean grantProjectViewToAll)

Sets if the projects are accessible in anonymous mode.

Sample:

ontrack.config.grantProjectViewToAll = trueassert ontrack.config.grantProjectViewToAll

241

setLdapSettings

Object setLdapSettings(LDAPSettings settings)

Sets the global LDAP settings

setMainBuildLinks

void setMainBuildLinks(List labels)

Sets the main build links settings

setPreviousPromotionRequired

void setPreviousPromotionRequired(boolean previousPromotionRequired)

Sets the previous promotion condition settings

setSonarQubeSettings

Object setSonarQubeSettings(SonarQubeMeasuresSettings settings)

Sets the global SonarQube settings

sonarQube

Object sonarQube(String name, String url, String user = '', String password = '')

Creates or updates a SonarQube configuration.

242

stash

Object stash(Map parameters, String name)

Creates or updates a BitBucket configuration.

When working with BitBucket, the access to the BitBucket application must be configured.

def stash(Map<String, ?> parameters, String name)




url the URL of the Stash instance

user L user used to connect to Stash (optional) password

Example:

ontrack.configure { stash 'MyStash', url: 'https://stask.example.com'}assert ontrack.config.stash.find { it == 'MyStash' } != null

243

svn

Object svn(Map parameters, String name)

Creates a or updates a Subversion configuration.

In order to create, update and access a Subversion configuration, use:

ontrack.configure { svn 'myconfig', url: 'https://myhost/repo'}def names = ontrack.config.svn*.name

The configuration password is always returned blank.

Some parameters, like url are required. List of parameters is:


url URL of the Subversion repository (required)

user

password

tagFilterPattern none by default

browserForPath none by default

browserForRevision none by default

browserForChange none by default

indexationInterval 0 by default

indexationStart revision to start the indexation from (1 bydefault)

issueServiceConfigurationIdentifier identifier for the issue service (optional) - seehere

Example of issue link (with JIRA):

ontrack.configure { jira 'MyJIRAConfig', 'http://jira' svn 'myconfig', url: 'https://myhost/repo', issueServiceConfigurationIdentifier:'jira//MyJIRAConfig'}

9.9.15. Document

Definition for a document, for upload and download methods. See also DSL Images and documents.

Method summary

244

Method Description

getContent byte[] getContent()

Returns the content of the document as an arrayof bytes.

getType String getType()

Returns the MIME type of the document.

isEmpty boolean isEmpty()

Returns true is the document is empty and hasno content.

getContent

byte[] getContent()

Returns the content of the document as an array of bytes.

getType

String getType()

Returns the MIME type of the document.

isEmpty

boolean isEmpty()

Returns true is the document is empty and has no content.

9.9.16. GroupMapping

Mapping between a LDAP group and an account group.


Method summary

Method Description

getGroupName String getGroupName()

Name of the Ontrack account group.


Name of the LDAP group.

245

getGroupName

String getGroupName()

Name of the Ontrack account group.

getName

String getName()

Name of the LDAP group.

9.9.17. LDAPSettings

LDAP settings parameters.

The LDAP settings are defined using the following values:


enabled Set to true to actually enable the LDAPAuthentication

url URL to the LDAP end point. For example,ldaps://ldap.company.com:636

searchBase DN for the search root, for example,dc=company,dc=com

searchFilter Query to look for an account. {0} is replaced bythe account name. For example,(sAMAccountName={0})

user Service account user to connect to the LDAP

password Password of the service account user to connectto the LDAP.

fullNameAttribute Attribute which contains the display name of theaccount. Defaults to cn

emailAttribute Attribute which contains the email of theaccount. Default to email.

groupAttribute Multiple attribute name which contains thegroups the account belong to. Defaults tomemberOf.

groupFilter When getting the list of groups for an account,filter this list using the OU attribute of the group.Defaults to blank (no filtering)

When getting the LDAP settings, the password field is always returned as an emptystring.

For example, to set the LDAP settings:

246

ontrack.config.ldapSettings = [ enabled : true, url : 'ldaps://ldap.company.com:636', searchBase : 'dc=company,dc=com', searchFilter: '(sAMAccountName={0})', user : 'service', password : 'secret',]

9.9.18. Label

Label


Method summary

Method Description

getCategory String getCategory()

Category of the label.

getColor String getColor()

Color of the label.


Description of the label.

getId int getId()

ID of the label.


Name of the label.

getCategory

String getCategory()

Category of the label.

getColor

String getColor()

Color of the label.

247

getDescription


Description of the label.

getId

int getId()

ID of the label.

getName

String getName()

Name of the label.

9.9.19. MainBuildLinks

Configuration which describes the list of build links to display, based on some project labels.

9.9.20. PredefinedPromotionLevel


Method summary

Method Description

getImage Document getImage()

Downloads the image for the promotion level.See DSL Images and documents.

image Object image(Object o)

Sets the image for this validation stamp (must bea PNG file). See DSL Images and documents.

getImage

Document getImage()

Downloads the image for the promotion level. See DSL Images and documents.

See: Document

248

image

Object image(Object o)

Sets the image for this validation stamp (must be a PNG file). See DSL Images and documents.

9.9.21. PredefinedValidationStamp


Method summary

Method Description

getDataType Object getDataType()

Gets the data type for the validation stamp, mapwith id and config, or null if not defined.


Downloads the image for the validation stamp.See DSL Images and documents.


Sets the image for this validation stamp (must bea PNG file). See DSL Images and documents.

setDataType Object setDataType(String id, Object config)

Sets a data type for the validation stamp

getDataType

Object getDataType()

Gets the data type for the validation stamp, map with id and config, or null if not defined.

getImage

Document getImage()

Downloads the image for the validation stamp. See DSL Images and documents.

See: Document

image


Sets the image for this validation stamp (must be a PNG file). See DSL Images and documents.

249

setDataType

Object setDataType(String id, Object config)


9.9.22. Project

The project is the main entity of Ontrack.

// Getting a projectdef project = ontrack.project('project')project { // Creates a branch for the project branch('1.0')}


Go to the methods





autoPromotionLevel Object autoPromotionLevel(boolean autoCreate =true)

autoValidationStamp Object autoValidationStamp(boolean autoCreate= true, boolean autoCreateIfNotPredefined =false)

buildLinkDisplayOptions Object buildLinkDisplayOptions(booleanuseLabel)

Sets the display options for the build linkstargeting this project.

getAutoPromotionLevel boolean getAutoPromotionLevel()

getAutoValidationStamp boolean getAutoValidationStamp()

getBuildLinkDisplayOptions boolean getBuildLinkDisplayOptions()

getGit Object getGit()

getGitLab Object getGitLab()

getJiraFollowLinks List<String> getJiraFollowLinks()

getMainBuildLinks MainBuildLinks getMainBuildLinks()

Gets the options for displaying the builds beingused by the builds of this project.

getSonarQube Map<String> getSonarQube()

250

getStale Object getStale()

getStash Object getStash()


git Object git(String name)

Configures the project for Git.

gitHub Object gitHub(Map parameters, String name)

Configures the project for GitHub.

gitLab Object gitLab(Map parameters, String name)

jiraFollowLinks Object jiraFollowLinks(String[] linkNames)

jiraFollowLinks Object jiraFollowLinks(Collection linkNames)

setMainBuildLinks void setMainBuildLinks(MainBuildLinksmainBuildLinks)

Sets the options for displaying the builds beingused by the builds of this project.

sonarQube void sonarQube(Map values)

Sets the SonarQube settings for this project.

stale Object stale(int disablingDuration = 0, intdeletingDuration = 0, List promotionsToKeep =[])

Setup of stale branches management.

stash Object stash(String name, String project,String repository, int indexationInterval = 0,String issueServiceConfigurationIdentifier ='')

svn Object svn(String name, String projectPath)

Configures the project for Subversion.

251

Configuration: stale

Object stale(int disablingDuration = 0, int deletingDuration = 0, List promotionsToKeep = [])

Setup of stale branches management.

Stale branches can be automatically disabled or even deleted.

To enable this property on a project:

ontrack.project('project').config { stale 15, 30}

def property = ontrack.project('project').config.staleassert property.disablingDuration == 15assert property.deletingDuration == 30assert property.promotionsToKeep == []

It is possible to make sure to keep branches which have been promoted to some levels. Forexample, if you want to keep branches which have been promoted to PRODUCTION:

ontrack.project('project').config { stale 15, 30, ['PRODUCTION']}

def property = ontrack.project('project').config.staleassert property.disablingDuration == 15assert property.deletingDuration == 30assert property.promotionsToKeep == ['PRODUCTION']

Configuration: gitHub

Object gitHub(Map parameters, String name)

Configures the project for GitHub.

252

Configuration: stash

Object stash(String name, String project, String repository, int indexationInterval = 0,String issueServiceConfigurationIdentifier = '')

Associates the project with the BitBucket configuration with the given name and specifies theproject in BitBucket and the repository.

Example:

ontrack.configure { jira 'MyJIRA', 'https://jira.example.com', 'user', 'password' stash 'MyStash', repository: 'https://stash.example.com', 'user', 'password'}ontrack.project('project') { config { stash 'MyStash', 'PROJECT', 'my-repo', 30, "jira//MyJIRA" }}assert ontrack.project('project').config.stash.configuration.name == 'MyStash'assert ontrack.project('project').config.stash.project == 'PROJECT'assert ontrack.project('project').config.stash.repository == 'my-repo'assert ontrack.project('project').config.stash.indexationInterval == 30assert ontrack.project('project').config.stash.issueServiceConfigurationIdentifier =="jira//MyJIRA"assert ontrack.project('project').config.stash.repositoryUrl =='https://stash.example.com/projects/PROJECT/repos/my-repo'

Configuration: getStash

Object getStash()

See stash

253

Configuration: git

Object git(String name)

Configures the project for Git.

Associates a project with a Git configuration.

def git(String name)

Gets the associated Git configuration:

def getGit()

Example:

ontrack.configure { git 'ontrack', remote: 'https://github.com/nemerosa/ontrack.git', user: 'test',password: 'secret'}ontrack.project('project') { config { git 'ontrack' }}def cfg = ontrack.project('project').config.gitassert cfg.configuration.name == 'ontrack'

Configuration: getGit

Object getGit()

See git

254

Configuration: svn

Object svn(String name, String projectPath)

Configures the project for Subversion.

To associate a project with an existing Subversion configuration:

def svn (String name, String projectPath)

To get the SVN project configuration:

def getSvn()

Example:

ontrack.project('project') { config { svn 'myconfig', '/project/trunk' }}def cfg = ontrack.project('project').config.svnassert cfg.configuration.name == 'myconfig'assert cfg.projectPath == '/project/trunk'

Configuration: getSvn

Object getSvn()

See svn

Configuration: getMainBuildLinks

MainBuildLinks getMainBuildLinks()

Gets the options for displaying the builds being used by the builds of this project.

See: MainBuildLinks

Configuration: setMainBuildLinks

void setMainBuildLinks(MainBuildLinks mainBuildLinks)

Sets the options for displaying the builds being used by the builds of this project.

255

256

Configuration: sonarQube

void sonarQube(Map values)

Sets the SonarQube settings for this project.

To enable SonarQube collection of measures for a project:

ontrack.project('project').config { sonarQube( configuration: "...", key: "project:key", )}

def property = ontrack.project('project').config.sonarQubeassert property.configuration.name == "..."assert property.key == "project:key"

Only the configuration and key parameters are required.

Full list of parameters is described below:

Parameter Type Default Description

configuration String Required Name of theSonarQubeconfiguration

key String Required Key of the project inSonarQube

validationStamp String sonarqube Name of the validationstamp to listen to whencollecting SonarQubemeasures on validationrun

measures List<String> [] List of additionalmeasures to collect forthis project

override boolean false Set to true if themeasures set abovemust override thegeneral settings.

branchModel boolean false If true, restricts thebranches where theSonarQube measuresare collected to theones matching anybranch modelassociated with theproject.

257

Parameter Type Default Description

branchPattern Regular expression None If set, restricts thebranches where theSonarQube measuresare collected to theones matching theregular expression.

Configuration: getSonarQube

Map<String> getSonarQube()

See sonarQube

Configuration: getGitLab

Object getGitLab()

See gitLab

Configuration: gitLab

Object gitLab(Map parameters, String name)

Configuration: getStale

Object getStale()

See stale

Configuration: jiraFollowLinks

Object jiraFollowLinks(String[] linkNames)

Links between JIRA issues can be followed when getting information about issues.

The links to follow can be configured at the project’s level:

• def jiraFollowLinks(String… linkNames)

• def jiraFollowLinks(Collection<String> linkNames)

The list of links to follow is accessible through:

• List<String> getJiraFollowLinks()

Example:

ontrack.project('project') { config { jiraFollowLinks 'Clones', 'Depends' }}assert ontrack.project('project').config.jiraFollowLinks == ['Clones', 'Depends']

258

Configuration: jiraFollowLinks

Object jiraFollowLinks(Collection linkNames)

See jiraFollowLinks

Configuration: getJiraFollowLinks

List<String> getJiraFollowLinks()

See jiraFollowLinks

259

260

Configuration: autoValidationStamp

Object autoValidationStamp(boolean autoCreate = true, boolean autoCreateIfNotPredefined =false)

Validation stamps can be automatically created for a branch, from a list of predefined validationstamps, if the "Auto validation stamps" property is enabled on a project.


ontrack.project('project') { config { autoValidationStamp() }}

or:

ontrack.project('project') { config { autoValidationStamp(true) }}

You can also edit the property so that a validation stamp is created even when no predefinedvalidation stamp does exit. In this case, the validation stamp will be created with the requiredname and without any image. To enable this feature:

ontrack.project('project') { config { autoValidationStamp(true, true) }}

To get the value of this property:

boolean auto = ontrack.project('project').autoValidationStamp

The list of predefined validation stamps is accessible using:

def stamps = ontrack.config.predefinedValidationStamps

Each item contains the following properties:

• id

• name

description

261

•

Its image is accessible through the image property.

In order to create/update predefined validation stamps, use the following method:

ontrack.config.predefinedValidationStamp('VS') { image new File('my/image.png')}

You need Administrator rights to be able to update the predefined validationstamps.

Configuration: getAutoValidationStamp

boolean getAutoValidationStamp()

See autoValidationStamp

262

263

Configuration: autoPromotionLevel

Object autoPromotionLevel(boolean autoCreate = true)

Promotion levels can be automatically created for a branch, from a list of predefined promotionlevels, if the "Auto promotion levels" property is enabled on a project.


ontrack.project('project') { config { autoPromotionLevel() }}

or:

ontrack.project('project') { config { autoPromotionLevel(true) }}

To get the value of this property:

boolean auto = ontrack.project('project').autoPromotionLevel

The list of predefined promotion levels is accessible using:

def stamps = ontrack.config.predefinedPromotionLevels

Each item contains the following properties:

• id

• name

• description

Its image is accessible through the image property.

In order to create/update predefined promotion levels, use the following method:

ontrack.config.predefinedPromotionLevel('VS') { image new File('my/image.png')}

You need Administrator rights to be able to update the predefined promotionlevels.

264

Configuration: getAutoPromotionLevel

boolean getAutoPromotionLevel()

See autoPromotionLevel

Configuration: buildLinkDisplayOptions

Object buildLinkDisplayOptions(boolean useLabel)

Sets the display options for the build links targeting this project.

Configuration: getBuildLinkDisplayOptions

boolean getBuildLinkDisplayOptions()

See buildLinkDisplayOptions

Method summary

Method Description

assignLabel void assignLabel(String category, String name,boolean createIfMissing = false)

Assign a label to the project, optionally creatingit if requested (and authorized)

branch Branch branch(String name, String description= '', boolean getIfExists = false, Closureclosure)

Retrieves or creates a branch for the project, andthen configures it.

branch Branch branch(String name, String description= '', boolean getIfExists = false)

Retrieves or creates a branch for the project

getBranches List<Branch> getBranches()

Gets the list of branches for the project.

getConfig ProjectProperties getConfig()

Access to the project properties

getLabels List<Label> getLabels()

Gets the labels for this project

search List<Build> search(Map form)

Searches for builds in the project.

265

unassignLabel void unassignLabel(String category, Stringname)

Unassign a label from a project

assignLabel

void assignLabel(String category, String name, boolean createIfMissing = false)

Assign a label to the project, optionally creating it if requested (and authorized)

branch

Branch branch(String name, String description = '', boolean getIfExists = false, Closureclosure)

Retrieves or creates a branch for the project, and then configures it.

See: Branch

branch

Branch branch(String name, String description = '', boolean getIfExists = false)

Retrieves or creates a branch for the project

See: Branch If the branch already exists, the getIfExists parameter is used:

• if false (default), an error is thrown

• if true, the existing branch is returned

If the branch does not exist, it is created.

Sample:

def project = ontrack.project('test')def branch = project.branch('new-branch')

getBranches

List<Branch> getBranches()

Gets the list of branches for the project.

See: Branch

266

getConfig

ProjectProperties getConfig()

Access to the project properties

getLabels

List<Label> getLabels()

Gets the labels for this project

See: Label

267

268

search

List<Build> search(Map form)

Searches for builds in the project.

See: Build Possible options are:

Parameter Description Default

maximumCount Maximum number of results toreturn

10

branchName Regular expression for thebranch a build belong to

none

buildName Regular expression for thebuild name

none

buildExactMatch Considers the buildName asbeing an exact match, and not aregular expression

false

promotionName Name of a promotion level abuild is promoted to

none

validationStampName Name of a validation stamp abuild has been validated towith status PASSED

none

property Qualified name of a propertythat the build must have

none

propertyValue Together with property, refinesthe filter by checking the valueof the build property. The waythe value is matched with theactual value depends on theproperty

none

linkedFrom Selects builds which are linkedfrom the build selected by thecriteria. See Build links for theexact syntax.

none

linkedTo Selects builds which are linkedto the build selected by thecriteria. See Build links for theexact syntax.

none

Example of build searches:

269

def project = ontrack.project('project')def builds = project.search()def build = project.search(maximumCount: 1)[0]def build = project.search(promotionName: 'BRONZE', maximumCount: 1)[0]ontrack.project('project') { branch 'MyBranch'}assert ontrack.project('project').branches.find { it.name == 'MyBranch' }

unassignLabel

void unassignLabel(String category, String name)

Unassign a label from a project

9.9.23. ProjectEntityProperties

Method summary

Method Description

getJenkinsBuild Object getJenkinsBuild()

getJenkinsJob Object getJenkinsJob()

getLinks Map<String,String> getLinks()

getMessage Object getMessage()

getMetaInfo List<MetaInfo> getMetaInfo()

getPreviousPromotionRequired Boolean getPreviousPromotionRequired()

jenkinsBuild Object jenkinsBuild(String configuration,String job, int build)

jenkinsJob Object jenkinsJob(String configuration, Stringjob)

links Object links(Map links)

message Object message(String text, String type ='INFO')

metaInfo Object metaInfo(String name, String value,String link = null, String category = null)

metaInfo Object metaInfo(Map map)

property Object property(String type, boolean required= true)

property Object property(String type, Map data)

Sets a property.

setPreviousPromotionRequired void setPreviousPromotionRequired(booleanpreviousPromotionRequired)

getJenkinsBuild

Object getJenkinsBuild()

See jenkinsBuild

getJenkinsJob

Object getJenkinsJob()

See jenkinsJob

270

getLinks

Map<String,String> getLinks()

See links

getMessage

Object getMessage()

See message

getMetaInfo

List<MetaInfo> getMetaInfo()

See metaInfo

getPreviousPromotionRequired

Boolean getPreviousPromotionRequired()

271

272

jenkinsBuild

Object jenkinsBuild(String configuration, String job, int build)

For builds, promotion runs and validation runs, it is possible to attach a reference to a Jenkinsbuild:

def jenkinsBuild(String configuration, String job, int buildNumber)

or to get the build reference:

def getJenkinsBuild()

Example:

273

ontrack.configure { jenkins 'Jenkins', 'http://jenkins'}def name = uid('P')def project = ontrack.project(name)def branch = project.branch('test') { promotionLevel('COPPER') validationStamp('TEST')}def build = branch.build('1') { config { jenkinsBuild 'Jenkins', 'MyBuild', 1 } promote('COPPER') { config { jenkinsBuild 'Jenkins', 'MyPromotion', 1 } } validate('TEST') { config { jenkinsBuild 'Jenkins', 'MyValidation', 1 } }}

def j = ontrack.build(name, 'test', '1').config.jenkinsBuildassert j.configuration.name == 'Jenkins'assert j.job == 'MyBuild'assert j.build == 1assert j.url == 'http://jenkins/job/MyBuild/1'

j = ontrack.build(name, 'test', '1').promotionRuns[0].config.jenkinsBuildassert j.configuration.name == 'Jenkins'assert j.job == 'MyPromotion'assert j.build == 1assert j.url == 'http://jenkins/job/MyPromotion/1'

j = ontrack.build(name, 'test', '1').validationRuns[0].config.jenkinsBuildassert j.configuration.name == 'Jenkins'assert j.job == 'MyValidation'assert j.build == 1assert j.url == 'http://jenkins/job/MyValidation/1'

Note that Jenkins folders are supported by giving the full job name. For example, the job name togive to the job in A > B > C would be A/job/B/job/C or even A/B/C.

See also the Jenkins job property.

274

https://wiki.jenkins-ci.org/display/JENKINS/CloudBees+Folders+Plugin

jenkinsJob

Object jenkinsJob(String configuration, String job)

Projects, branches, promotion levels and validation stamps can have a reference to a Jenkins job:

def jenkinsJob(String configuration, String job)

or to get the job reference:

def getJenkinsJob()

Example:

275

ontrack.configure { jenkins 'Jenkins', 'http://jenkins'}ontrack.project('project') { config { jenkinsJob 'Jenkins', 'MyProject' } branch('test') { config { jenkinsJob 'Jenkins', 'MyBranch' } promotionLevel('COPPER') { config { jenkinsJob 'Jenkins', 'MyPromotion' } } validationStamp('TEST') { config { jenkinsJob 'Jenkins', 'MyValidation' } } }}

def j = ontrack.project('project').config.jenkinsJobassert j.configuration.name == 'Jenkins'assert j.job == 'MyProject'assert j.url == 'http://jenkins/job/MyProject'

j = ontrack.branch('project', 'test').config.jenkinsJobassert j.configuration.name == 'Jenkins'assert j.job == 'MyBranch'assert j.url == 'http://jenkins/job/MyBranch'

j = ontrack.promotionLevel('project', 'test', 'COPPER').config.jenkinsJobassert j.configuration.name == 'Jenkins'assert j.job == 'MyPromotion'assert j.url == 'http://jenkins/job/MyPromotion'

j = ontrack.validationStamp('project', 'test', 'TEST').config.jenkinsJobassert j.configuration.name == 'Jenkins'assert j.job == 'MyValidation'assert j.url == 'http://jenkins/job/MyValidation'

Note that Jenkins folders are supported by giving the full job name. For example, the job name togive to the job in A > B > C would be A/job/B/job/C or even A/B/C.

See also the Jenkins build property.

links

Object links(Map links)

Arbitrary named links can be associated with projects, branches, etc.

ontrack.project('project') { config { links 'project': 'http://project' } branch('test') { config { links 'branch': 'http://branch' } build('1') { config { links 'build': 'http://build' } } }}assert ontrack.project('project').config.links.project == 'http://project'assert ontrack.branch('project', 'test').config.links.branch == 'http://branch'assert ontrack.build('project', 'test', '1').config.links.build == 'http://build'

276

https://wiki.jenkins-ci.org/display/JENKINS/CloudBees+Folders+Plugin

message

Object message(String text, String type = 'INFO')

An arbitrary message, together with a message type, can be associated with any entity.

To set the message on any entity:

entity.message(String text, String type = 'INFO')

Following types of messages are supported:

• INFO

• WARNING

• ERROR

For example, on a build:

ontrack.build('project', 'branch', '1').config { message 'My message', 'WARNING'}

To get a message:

def msg = ontrack.build('project', 'branch', '1').config.messageassert msg.type == 'WARNING'assert msg.text == 'My message'

See Message property for more details about this property.

metaInfo

Object metaInfo(String name, String value, String link = null, String category = null)

See metaInfo

277

metaInfo

Object metaInfo(Map map)

Arbitrary meta information properties can be associated with any entity.

To set a list of meta information properties:

entity.config { metaInfo A: '1', B: '2'}

This method does not allow to set links and will erase any previous metainformation.

The following method is the preferred one:

ontrack.build('project', 'branch', '1').config { metaInfo 'name1', 'value1' metaInfo 'name2', 'value2', 'http://link2' metaInfo 'name3', 'value3', 'http://link3', 'Category'}

This allows to keep any previous meta information property and to specify links if needed.

To get the meta information, for example on the previous build:

def list = ontrack.build('project', 'branch', '1').config.metaInfoassert list.size() == 3assert list[0].name = 'name1'assert list[0].value = 'value1'assert list[0].link = nullassert list[0].category = nullassert list[1].name = 'name2'assert list[1].value = 'value2'assert list[1].link = 'http://link2'assert list[1].category = nullassert list[2].name = 'name3'assert list[2].value = 'value3'assert list[2].link = 'http://link3'assert list[2].category = 'Category'

See Meta information property for more details about this property.

278

property

Object property(String type, boolean required = true)

Gets a property on the project entity.

If required is set to false and if the property does not exist or is not set, null will be returned.

If required is set to true and if the property does not exist or is not set, anet.nemerosa.ontrack.dsl.PropertyNotFoundException is thrown.

def project = ontrack.project('PRJ')def value = project.getProperty('com.my.UnsetPropertyType', false)assert value == null

property

Object property(String type, Map data)

Sets a property.

setPreviousPromotionRequired

void setPreviousPromotionRequired(boolean previousPromotionRequired)

9.9.24. PromotionLevel


Go to the methods


279

Builds can be auto promoted to a promotion level when this latter is configured to do so.

A promotion level is configured for auto promotion using:

ontrack.promotionLevel('project', 'branch', 'promotionLevel').config { autoPromotion 'VS1', 'VS2'}

where VS1, VS2 are the validation stamps which must be PASSED in order to promote a buildautomatically.

To get the list of validation stamps for the auto promotion of a promotion level:

def validationStamps = ontrack.promotionLevel('project', 'branch', 'promotionLevel') .config .autoPromotion .validationStamps

The validation stamps used to define an auto promotion can also be defined using regularexpressions:

ontrack.promotionLevel('project', 'branch', 'promotionLevel').config { autoPromotion [], 'VS.*'}

In this sample, all validation stamps whose name starts with VS will participate in the promotion.

You can also exclude validation stamps using their name:

ontrack.promotionLevel('project', 'branch', 'promotionLevel').config { autoPromotion [], 'VS.*', 'VS/.1'}

In this sample, all validation stamps whose name starts with VS will participate in the promotion,but for the VS.1 one.




autoPromotion Object autoPromotion(String[]validationStamps)

Sets the validation stamps participating into theauto promotion.

280

autoPromotion Object autoPromotion(CollectionvalidationStamps = [], String include = '',String exclude = '', CollectionpromotionLevels = [])

Sets the validation stamps or promotion levelsparticipating into the auto promotion, and setsthe include/exclude settings.

getAutoPromotion boolean getAutoPromotion()

Checks if the promotion level is set in autopromotion.

getPromotionDependencies List<String> getPromotionDependencies()

Gets the validation stamps participating into theauto promotion. The returned list can be null ifthe property is not defined.

setPromotionDependencies void setPromotionDependencies(List promotions)

Sets the validation stamps participating into theauto promotion.

Configuration: setPromotionDependencies

void setPromotionDependencies(List promotions)

Sets the validation stamps participating into the auto promotion.

Configuration: getPromotionDependencies

List<String> getPromotionDependencies()

Gets the validation stamps participating into the auto promotion. The returned list can be null ifthe property is not defined.

Configuration: autoPromotion

Object autoPromotion(String[] validationStamps)

Sets the validation stamps participating into the auto promotion.

Configuration: autoPromotion

Object autoPromotion(Collection validationStamps = [], String include = '', String exclude ='', Collection promotionLevels = [])

Sets the validation stamps or promotion levels participating into the auto promotion, and sets theinclude/exclude settings.

281

Configuration: getAutoPromotion

boolean getAutoPromotion()

Checks if the promotion level is set in auto promotion.

Method summary

Method Description


Configuration of the promotion level with aclosure.

getAutoPromotionPropertyDecoration Boolean getAutoPromotionPropertyDecoration()

Checks if this promotion level is set in autodecoration mode.


Name of the associated branch.

getConfig PromotionLevelProperties getConfig()

Access to the promotion level properties


Gets the promotion level image (see DSL Imagesand documents)


Name of the associated project.

image Object image(Object o, String contentType)

Sets the promotion level image (see DSL Imagesand documents)


Sets the promotion level image (see DSL Imagesand documents)

call


Configuration of the promotion level with a closure.

282

getAutoPromotionPropertyDecoration

Boolean getAutoPromotionPropertyDecoration()

Checks if this promotion level is set in auto decoration mode.

getBranch

String getBranch()


getConfig

PromotionLevelProperties getConfig()

Access to the promotion level properties

getImage

Document getImage()

Gets the promotion level image (see DSL Images and documents)

See: Document

getProject

String getProject()


image

Object image(Object o, String contentType)

Sets the promotion level image (see DSL Images and documents)

image


Sets the promotion level image (see DSL Images and documents)

9.9.25. PromotionRun

You can get a promotion run by promoting a build:

283

def run = ontrack.build('project', 'branch', '1').promote('BRONZE')assert run.promotionLevel.name == 'BRONZE'

or by getting the list of promotion runs for a build:

def runs = ontrack.build('project', 'branch', '1').promotionRunsassert runs.size() == 1assert runs[0].promotionLevel.name == 'BRONZE'


Method summary

Method Description

getPromotionLevel Object getPromotionLevel()

Gets the associated promotion level (JSON)

getPromotionLevel

Object getPromotionLevel()

Gets the associated promotion level (JSON)

9.9.26. SearchResult

The SearchResult class is used for listing the results of a search.


Sample:

ontrack.project('prj')def results = ontrack.search('prj')assert results.size() == 1assert results[0].title == 'Project prj'assert results[0].page == 'https://host/#/project/1'assert results[0].page == 'https://host/#/project/1'

Method summary

Method Description

getAccuracy int getAccuracy()

Gets a percentage of accuracy about the result.

284


Gets a description for the search result.

getPage String getPage()

Gets the URI to display the search result details(Web).

getTitle String getTitle()

Gets the display name for the search result.

getUri String getUri()

Gets the URI to access the search result details(API).

getAccuracy

int getAccuracy()

Gets a percentage of accuracy about the result.

getDescription


Gets a description for the search result.

getPage

String getPage()

Gets the URI to display the search result details (Web).

getTitle

String getTitle()

Gets the display name for the search result.

getUri

String getUri()

Gets the URI to access the search result details (API).

9.9.27. SonarQubeMeasuresSettings

SonarQube measures settings parameters.

285

9.9.28. ValidationRun

You can get a validation run by validating a build:

def run = ontrack.build(branch.project, branch.name, '2').validate('SMOKE', 'FAILED')assert run.validationStamp.name == 'SMOKE'assert run.validationRunStatuses[0].statusID.id == 'FAILED'assert run.validationRunStatuses[0].statusID.name == 'Failed'assert run.status == 'FAILED'

or by getting the list of validation runs for a build:

def runs = ontrack.build(branch.project, branch.name, '2').validationRunsassert runs.size() == 1assert runs[0].validationStamp.name == 'SMOKE'assert runs[0].validationRunStatuses[0].statusID.id == 'FAILED'assert runs[0].status == 'FAILED'


Method summary

Method Description

getData Object getData()

Gets the data for the validation run, map with idand data, or null if not defined.

getLastValidationRunStatus ValidationRunStatusgetLastValidationRunStatus()

Gets the last of statuses

getRunInfo RunInfo getRunInfo()

Gets the associated run info with this validationrun or null if none


Gets the status for this validation run.

getValidationRunStatuses List<ValidationRunStatus>getValidationRunStatuses()

Gets the list of statuses

getValidationStamp Object getValidationStamp()

Gets the associated validation stamp (JSON)

286

setRunInfo void setRunInfo(Map info)

Sets the run info for this validation run.

getData

Object getData()

Gets the data for the validation run, map with id and data, or null if not defined.

getLastValidationRunStatus

ValidationRunStatus getLastValidationRunStatus()

Gets the last of statuses

See: ValidationRunStatus

getRunInfo

RunInfo getRunInfo()

Gets the associated run info with this validation run or null if none

The returned object has the following properties:






287

getStatus

String getStatus()

Gets the status for this validation run.

Possible values are:

• DEFECTIVE

• EXPLAINED

• FAILED

• FIXED

• INTERRUPTED

• INVESTIGATING

• PASSED

• WARNING

getValidationRunStatuses

List<ValidationRunStatus> getValidationRunStatuses()

Gets the list of statuses

See: ValidationRunStatus

getValidationStamp

Object getValidationStamp()

Gets the associated validation stamp (JSON)

setRunInfo

void setRunInfo(Map info)

Sets the run info for this validation run.

Accepted parameters are:






288

9.9.29. ValidationRunStatus


Method summary

Method Description


Returns the status description

getId int getId()



Returns the status ID in text form

getStatusID Object getStatusID()

Returns the status ID in JSON form

getStatusName String getStatusName()

Returns the status display name

isPassed boolean isPassed()

Returns if the status is passed or not

setDescription void setDescription(String value)

Sets the description on this status

getDescription


Returns the status description

getId

int getId()


getStatus

String getStatus()

Returns the status ID in text form

289

getStatusID

Object getStatusID()

Returns the status ID in JSON form

getStatusName

String getStatusName()

Returns the status display name

isPassed

boolean isPassed()

Returns if the status is passed or not

setDescription

void setDescription(String value)

Sets the description on this status

9.9.30. ValidationStamp


Go to the methods



Method summary

Method Description


Configuration of the promotion level with aclosure.



getConfig ValidationStampProperties getConfig()

Access to the validation stamp properties

290

getDataType Object getDataType()

Gets the data type for the validation stamp, mapwith id and config, or null if not defined.


Gets the validation stamp image (see DSL Imagesand documents)



getValidationStampWeatherDecoration Object getValidationStampWeatherDecoration()

Gets the validation stamp weather decoration.

image Object image(Object o, String contentType)

Sets the validation stamp image (see DSL Imagesand documents)


Sets the validation stamp image (see DSL Imagesand documents)

setCHMLDataType Object setCHMLDataType(String warningLevel,Integer warningValue, String failedLevel,Integer failedValue)

Sets the data type for this validation stamp to'CHML' (number of critical / high / medium / lowissues).

setDataType Object setDataType(String id, Object config)


setFractionDataType Object setFractionDataType(IntegerwarningThreshold = null, IntegerfailureThreshold = null, boolean okIfGreater =true )

Sets the data type for this validation stamp to'Fraction'.

setMetricsDataType Object setMetricsDataType()

Sets the data type for this validation stamp to'metrics'.

291

setNumberDataType Object setNumberDataType(IntegerwarningThreshold = null, IntegerfailureThreshold = null, boolean okIfGreater =true )

Sets the data type for this validation stamp to'Number'.

setPercentageDataType Object setPercentageDataType(IntegerwarningThreshold = null, IntegerfailureThreshold = null, boolean okIfGreater =true )

Sets the data type for this validation stamp to'Percentage'.

setTestSummaryDataType Object setTestSummaryDataType(booleanwarningIfSkipped = false )

Sets the data type for this validation stamp to'TestSummary'.

setTextDataType Object setTextDataType()

Sets the data type for this validation stamp to'text'.

call


Configuration of the promotion level with a closure.

getBranch

String getBranch()


getConfig

ValidationStampProperties getConfig()

Access to the validation stamp properties

getDataType

Object getDataType()

Gets the data type for the validation stamp, map with id and config, or null if not defined.

292

getImage

Document getImage()

Gets the validation stamp image (see DSL Images and documents)

See: Document

getProject

String getProject()


getValidationStampWeatherDecoration

Object getValidationStampWeatherDecoration()

Gets the validation stamp weather decoration.

The "weather" of the validation stamp is the status of the last 4 builds having been validated forthis validation stamp on the corresponding branch.

The returned object contains two attributes:

• weather which can have one of the following values:

◦ sunny

◦ sunAndClouds

◦ clouds

◦ rain

◦ storm

• text - a display text for the weather type

image

Object image(Object o, String contentType)

Sets the validation stamp image (see DSL Images and documents)

image


Sets the validation stamp image (see DSL Images and documents)

293

setCHMLDataType

Object setCHMLDataType(String warningLevel, Integer warningValue, String failedLevel, IntegerfailedValue)

Sets the data type for this validation stamp to 'CHML' (number of critical / high / medium / lowissues).

setDataType

Object setDataType(String id, Object config)


setFractionDataType

Object setFractionDataType(Integer warningThreshold = null, Integer failureThreshold = null,boolean okIfGreater = true )

Sets the data type for this validation stamp to 'Fraction'.

setMetricsDataType

Object setMetricsDataType()

Sets the data type for this validation stamp to 'metrics'.

setNumberDataType

Object setNumberDataType(Integer warningThreshold = null, Integer failureThreshold = null,boolean okIfGreater = true )

Sets the data type for this validation stamp to 'Number'.

setPercentageDataType

Object setPercentageDataType(Integer warningThreshold = null, Integer failureThreshold =null, boolean okIfGreater = true )

Sets the data type for this validation stamp to 'Percentage'.

setTestSummaryDataType

Object setTestSummaryDataType(boolean warningIfSkipped = false )

Sets the data type for this validation stamp to 'TestSummary'.

294

setTextDataType

Object setTextDataType()

Sets the data type for this validation stamp to 'text'.

295

Documents

Ontrack Reference Guide 3.42...2.3.3. Bulk update of validation stamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 2.4. Managing