Jenkins Configuration

1. Team for Capella Scheduler

Team for Capella provides many applications (Backups, diagnostics…) manageable by Jenkins jobs in order to have a web interface for managing your shared projects. You can refer to the documentation for the installation of Jenkins.

The full Jenkins documentation can be found at the following address: https://www.jenkins.io/doc/.

By default, it is available on port 8036: when logged on the computer running the Scheduler, type the following address in a web browser:

http://localhost:8036

By default, for all jobs, the last 100 job executions (called "builds" in Jenkins) results are kept by Jenkins (build’s artifacts and logs). Note that all these jobs can be changed with the Jenkins application.

The default view is the "Server Management" one.

1.1. Server Management

1.1.1. Server – List active repositories

This job lists the currently active repositories on the server.

The list result is logged in the console output of the job.

These repositories can be stopped by using the Server – Stop repository job.

1.1.2. Server – List connected projects and locks

This job lists :

the opened Capella shared projects with the associated username. It corresponds to the CDO sessions opened on the server.
the currently locked objects classified by opened projects with user information.

This job executes with "RepositoryName" as a parameter. As it is a list with only the default "repoCapella" value, it can be edited if your server configuration has more repositories or with a different name.

1.1.3. Server – Run

This job starts the server. By default, this job starts the server every Saturday at 05:15, It never stops (and must not be aborted) except if "Server – Stop" is launched.

1.1.4. Server – Start repository

This job starts a repository on the server, that was previously stopped by the job «Server - Stop repository». When a server starts, all its repositories starts as well.

1.1.5. Server – Stop

This job stops the server. By default, this job stops the server every Saturday at 05:00 (and is restarted one hour later by the previous job).

1.1.6. Server – Stop repository

This job stops an active repository on the server.

Use Server – List active repositories to list all active repositories.

The stopped repository cannot be reached, and remote projects existing in this repository cannot be modified. Using the Database – Backup job will not back up the stopped repository.

The server will still be running, and the other non-stopped repositories will still be reachable.

1.1.7. License Server – Run

This job is only present in the commercial versions of Team for Capella.

It allows managing the license server directly from the Scheduler. It is disabled by default.

1.2. Backup and Restore

1.2.1. Database – Backup

This job does a dump of the database into a zip file and keeps it as an artifact of the build. By default, it is launched automatically 3 times a day (07:30, 12:30 and 20:30) from Monday to Friday.

Note that this job will perform a backup of the whole server. If several repositories are started, it creates one zip file per repository.

We strongly recommend having one database path per repository. See How to Add a New Repository

1.2.2. Database – Restore

This job is intended to restore the database from a previously backed-up database.

The backup folder is a result of the "Database – Backup" job.

If you want to restore only one repository, move all other archives out of the backup folder to keep the one specific to your repository.

1.2.3. Projects – Delete

It executes the exporter application to delete a project from the given repository without any user interaction.

This job will delete a project according to its name on the server, given as parameter.

1.2.4. Projects – Export

It executes the exporter application to export projects automatically from a local folder (or archive) on the server without any user interaction. This job will export the projects from a specific source. This source can be

a folder that contains one or more projects to export,
a zip containing one or more sirius project that is aird file,
a folder that contains one or more zip files.

This job needs to be configured to specify the folder.

If the job fails, you may have a wrong folder path or none of the representation files have been found in the folder.

1.2.5. Projects – Import – repoCapella

It executes the importer application to import projects automatically from a server without any user interaction and archives them as Job’s artifacts. By default, it is launched automatically every hour from 07:00 to 21:00 Monday to Friday and targets the default repository (repoCapella).

This job will import the projects for a specific repository. It needs to be configured to specify the repository and optionally, a specific project list to import. If you have many repositories, you ought to have as many "import projects" jobs that may start at the same time. So you need to configure the number of job executors. Go to Manage Jenkins > configure systems menu if the number of T4C repositories has been extended: # of executors ≥ =nb of repo +3

This job is by default configured to use the Snapshot import strategy. Refer to the Importer strategies documentation for more details.

If the job fails, you may have corrupted data in your database that could prevent you from getting imported projects. To avoid further modifications of your projects and minimize data loss, the default behavior in case of import failure is to stop the repository. Then, in order to continue to work on your projects, you may:

analyze the failure by checking the console log output of the job,
diagnostic/repair the database with "Diagnostic and Repair" jobs,
reinitialize the database.

1.2.6. Repository – Commit history

It executes the importer application to import only the commit history.

This job executes with "RepositoryName" as a required parameter. As it is a list with only the default "repoCapella" value, it can be edited if your server configuration has more repositories or with a different name. There are additional parameters to this job that can be selected:

SquashCommitHistory: Squash consecutive commits done by the same user with the same description (default: true);
IncludeCommitHistoryChanges: Import the commit history detailed changes for each commit done by a user with one of the save actions;
ComputeImpactedRepresentationsForCommitHistoryChanges: Compute the impacted representations while exporting changes.

See importer documentation in Importer Parameters chapter for more information about these parameters.

1.2.7. Repository – Import projects from history

It executes the importer application to import projects of a repository at a given date.

This job executes with required parameters:

RepositoryName: the name of the repository to import from;
ProjectName: name of the project to import. By default the value is "*" in order to import all project of the repository;
CheckoutTimestamp: reference date to import from. By default the value is "HEAD" to import from the latest available commit. Otherwise, the date pattern is yyyy-MM-ddThh:mm:ss.SSSZ. See full documentation about the timestamp in Importer Parameters Notes

See importer documentation in Importer Parameters chapter for more information about these parameters.

1.2.8. Repository – List projects

This jobs list all available project in a given repository.

This job executes with required parameters:

RepositoryName: the name of the repository to import from;
CheckoutTimestamp: reference date to import from. By default the value is "HEAD" to import from the latest available commit. Otherwise, the date pattern is yyyy-MM-ddThh:mm:ss.SSSZ. See full documentation about the timestamp in Importer Parameters Notes

See importer documentation in Importer Parameters chapter for more information about these parameters.

1.2.9. User profile – Import model

This jobs extracts the user profile model from the database and saves it locally in the outputFolder.

It is disabled by default and must be enabled only if the repository is configured to use the "User Profiles" access control mode.

1.3. Diagnostic and Repair

These jobs cannot be started if the authenticator is based on an OpenID Connect. You must start the server with another mode of authentication or no authentication.

1.3.1. Repository – Diagnostic

This maintenance job needs to be manually launched. This job runs a diagnostic to detect inconsistencies described in Server Administration / Administration Tools / Repository maintenance application.

The diagnostic result is logged in the console output of the job. It is kept as an artifact of the job result.

The diagnostic is run for a specific repository and need to be configured according to your repository name.

1.3.2. Repository – Maintenance

This maintenance job needs to be manually launched. It is recommended to launch the Repository – diagnostic job first.

It runs a diagnostic in order to detect inconsistencies described in Server Administration / Administration Tools / Repository maintenance application. Then, it launches the maintenance tasks if some managed issues are detected: it will back up the server with capella_db command, perform the required changes on the database and close the server. The steps are logged in the console output of the job, and the corresponding log file is kept as an artifact of the job result.

The maintenance is run for a specific repository and needs to be configured according to your repository name.

1.4. Credentials

1.4.1. Server – Rest Admin – Manage User Tokens

This jobs executes the Tools Credentials Application to manage the access tokens to the Rest API for a specific user.

Launching a build requires setting values for four parameters:

13. View ServerManagement ManageUserTokens

Note that the login and password must be valid credentials for the REST Admin API.

1.4.2. Server – Rest Admin – Manage Users

This jobs executes the Tools Credentials Application to manage the Rest API registered users.

Launching a build requires setting values for five parameters:

Note that the login and password must be valid credentials for the REST Admin API.

1.4.3. Tools – Clear credentials

This job executes the credentials application to clear credentials in Eclipse Secure Storage, allowing the importer application to connect to the rest admin server or to connect to a CDO repository.

As credentials needs to be associated with a repository, when this job is executed, it will start by asking to fill the following parameters:

13. View ServerManagement ClearImporterCredentials

Note that credentials are required only with the Connected import strategy. See Importer strategies for more details.

This job executes with "REPOSITORY_NAME" as a parameter. As it is a list with only the default "repoCapella" value, it can be edited if your server configuration has more repositories or with a different name.

1.4.4. Tools – Store credentials

This job is the opposite of the previous one, it stores the credentials in Eclipse Secure Storage, allowing either to connect to the rest admin server or to connect to a CDO repository.

As credentials needs to be associated with a repository, when this job is executed, it will start by asking to fill the following parameters:

13. View ServerManagement StoreImporterCredentials

Note that credentials are required only with the Connected import strategy. See Importer strategies for more details.

1.5. Templates

This view contains templates of jobs which are disabled by default. They are provided as an example to show how to create backup jobs whose result is pushed to a Git repository.

See each job description in the Scheduler to see how to use them.

2. How to Start the Team for Capella Scheduler

The Jenkins installation should have included the creation of a new service (named Jenkins) that automatically starts Jenkins with the system.

2.1. Windows

If you do not have the Jenkins service, go to Jenkins (or start it manually from its installation folder), go to the Manage Jenkins configuration page and select Install as a Windows service.

2.2. Linux

The Jenkins service can be started or stopped by using the systemctl command:

systemctl start jenkins

2.3. How to start the Server when Scheduler starts

To start the Team for Capella Server automatically when the scheduler starts (i.e.: launch the Start server job), go to the configuration page of the Start server job and then check the box "Build when job nodes start", the "Quiet period" parameter allows delaying the start:

3. How to change job scheduling

Every job contains in its configuration page a text field called "Schedule". Use this field to change the Job’s scheduling configuration. It is visible on the previous screenshot.

4. How to Stop the Team for Capella Scheduler

To stop the Jenkins scheduler, go to the Manage Jenkins page and select Prepare for Shutdown

This allows sending a warning to anyone currently connected to the scheduler and end the jobs currently running or in queue. After that, you can simply go to the Windows services and stop the Jenkins service.

5. Activate Security in Jenkins

By default, in the scheduler, the security checks are disabled. This means that Jenkins is available to anyone who can access Jenkins web UI without asking for their login and password.

It is possible to configure security within Jenkins to define a group of users, which are allowed to log in to Jenkins or to check user passwords against the username in LDAP or in Jenkins' own user database. To do that, the procedure is the following:

Connect to Jenkins as a user with administration rights.
Select Manage Jenkins
Select Configure Global Security.
Select the Jenkins' own user database security realm radio button to register users in Jenkins or select the LDAP radio button to register configurations for the LDAP servers that Jenkins should search.
To configure an LDAP server, select the corresponding radio button and then the Advanced… button underneath the Server text field.
Enter the LDAP settings as shown in the following diagram:
Note: The group specified in Group search base and the username specified in Manager DN may need to be changed. The password specified in Manager Password is the password for the user in the Manager DN field.
To ensure that only logged-in users can perform actions, select Authorization → Logged-in users can do anything.
Save the configuration changes.
Log in to Jenkins via the log in link in the top right-hand corner of the screen.

You can also decide to use the Jenkins' own user database:

Connect to Jenkins as a user with administration rights.
Select Manage Jenkins.
Select Configure Global Security.
Select the Enable security checkbox, the Jenkins' own user database security realm radio button and then place a check mark next to Allow users to sign up.
Save
Create a user (menu in the top-right corner)
Log in to Jenkins via the log in link in the top right-hand corner of the screen and go back to http://localhost:8036/configure (or select Manage Jenkins and then Configure Global Security).
In the security realm section, remove the check mark next to Allow users to sign up
In the Authorization section, select the Matrix-based security mode,
In the text box below the matrix, type your username and click Add
Give yourself full access by checking the entire row for your username
Configure other users
- Repeat the two previous steps for other users who deserve full access.
- If you want to allow anonymous users to see the jobs: Give the Anonymous user only Overall Read access.
- You can also decide to create specific users who can only launch the jobs and see the results and hide everything for anonymous users.
Click Save at the bottom of the page. You will be taken back to the top page.
Restart Jenkins

More details can be found in https://www.jenkins.io/doc/book/system-administration/security/.

6. Microsoft Entra ID authentication for Jenkins

A Jenkins plugin allows the authentication to be handled by Microsoft Entra ID. This plugin is automatically installed by the Jenkins plugins for Team for Capella installation script, but if you have installed Jenkins by another mean, it can be installed as follows: First, go to Manage Jenkins > Manage Plugins. On the Available tab, look for Microsoft Entra ID Plugin. Before installing it, hover your mouse over the label and open the link on a new tab. This will open a documentation page useful later. Now, check the plugin and press the download and install button. Restart Jenkins. Once restarted, Jenkins is ready to be configured for an authentication with Microsoft Entra ID. For that, go to the tab that was opened previously and follow the documentation. There are two parts for this configuration, one in Microsoft Entra ID and one in Jenkins. Note that on the Jenkins setting part, when asked to fill the Tenant this corresponds to the Directory (tenant) ID in your Entra ID application. It is not necessarily the same value as in the CDO server configuration files (for instance, the value "organizations" can be used instead of Tenant ID for the purpose of OpenID discovery mechanism). Also, a test user is asked in order to verify the authentication parameters. This is not the name that is needed here but the User Principal Name or the Object ID of this user. Note that, if you want to have a different list of users having access to Jenkins (compared to the users that have access to the CDO server), you can create a new application on Entra ID dedicated to the scheduler access (Jenkins).

7. How to Change Backup and Import Files Purge Policy

Connect to the scheduler admin site
Select the "Database – Backup" job → Configure
In the section "Delete old builds" → Update the maximum number of build to keep and the max # of builds to keep with artefact

Select the "Projects – Import" job → Configure
Update the section "Delete old builds" like in the step 3)

8. How to Dissociate Multiple Projects in Jenkins

8.1. Purpose

I have 2 modeling projects (or more) working with Team for Capella and I want to isolate them in Jenkins (a person logged in Jenkins must see only Jenkins jobs dedicated to its project).

The proposed solution uses the internal Jenkins user database but is applicable with some changes to use a LDAP server.

Note that this section be adapted for different situations: multiple projects, multiple repositories or even multiple servers managed yby the same Scheduler.

8.2. Jobs Creation

When Jenkins is started for the first time, it contains all necessary jobs:

Let’s say the "Projects – Import" job will be used for Project 1. So, rename it to "Project 1 – Import":

Now we will create jobs for Project 2. Click on the "New Item" in the "Backup and Restore" tab.

Then select "Copy existing Job"). Copy the "Project 1 – Import" job and rename it into "Project 2 – Import".

The result is the following:

13. Projects Dissociation in Jenkins html m648d2ba5

Project 1 and Project 2 jobs have to be configured correctly to be used (their build step must be modified to add -projectName ProjectXName) and number of executors has to be increased.

8.3. Access Rights Definition (whole Jenkins instance level)

Go to "Manage Jenkins" / "Configure Global Security", set parameters as shown in the screenshot:

13. Projects Dissociation in Jenkins html 6c9d11d3

Do the following changes in the table:

For "Anonymous Users": check the "Overall" / "Read" check box if anonymous access can be granted,
For "Authenticated Users": check the "Overall" / "Read" check box,
Add a "SuperAdmin" user and give it all rights by checking all check boxes,

The table must be as follows:

13. Projects Dissociation in Jenkins html m1dad3455

Click on "Save".

Access rights are now activated:

13. Projects Dissociation in Jenkins html m5e4b52f6

Create the "SuperAdmin" account and use it to log in Jenkins.

8.4. Access Rights Definition (job/project level)

Go to the "Configuration" page of a job dedicated to Project 1 and check "Enable project-based security":

13. Projects Dissociation in Jenkins html m7d373370

Do the following changes in the table:

Add a "Project1Admin" and give it all rights on this job by checking all check boxes,
Add a "Project1User" and check "Read", "Build" and "Workspace" check boxes,

13. Projects Dissociation in Jenkins html 3c27d1a

Do the same work on all jobs linked to Project1.

Repeat all above actions with "Project2Admin" and all jobs linked to Project2.

8.5. Result

SuperAdmin has full rights on the whole Jenkins instance,
Project’s admins see and have full rights on jobs linked to their projects (e.g. they can add new admins/users),
Project’s users can only see, launch, get logs and artifacts on jobs linked to their projects.

8.6. Known Limitations

8.6.1. Inter-project Information Sharing

An admin/user dedicated to a project will not be allowed to see information on jobs of other projects.

For example, when logged as Project2Admin and with Project1’s server running.Project2Admin will see:

13. Projects Dissociation in Jenkins html m4da61786

9. Tips and Tricks

9.1. Configure Number of Scheduler Build Processes

The Team for Capella scheduler (Jenkins) can be configured for a maximum number of build processes that can execute concurrently.

In order to ensure the correct operation of all Team for Capella server jobs it is vital to set this maximum number of build processes correctly!

Select Manage Jenkins.
Select Configure System.
Locate the setting # of executors and set the value according to the following rule:

For example, if the server machine is to run 5 Team for Capella server processes, then the value of # of executors would need to be set to 6.

Setting this configuration parameter incorrectly can lead to complete system hangs, no Capella backups, etc!

9.2. Create Scheduler Job Environment Variables

Each Team for Capella server process relies on two network ports – a server port and a console port. In order to avoid confusion by using "magic" numbers for the ports within the scheduler jobs, it is best to create environment variables for these.

Select Manage Jenkins.
Select Configure System.
Within the section Global properties → Environment variables, press the Add button in order to add a new variable.
Enter the server port environment variable name and value as follows: Set name to TEAMFORCAPELLA_SERVER_PORT_<repoName>, where <repoName> is replaced by the name of the repository, e.g., TEST_01 Set value to the configured server port value, e.g., 2036.
Press the Add button in order to add a new variable.
Enter the console port environment variable name and value as follows: Set name to TEAMFORCAPELLA_CONSOLE_PORT_<repoName>, where <repoName> is replaced by the name of the repository, e.g., TEST_01 Set value to the configured console port value, e.g., 12036.

Note: the hyphen character is not allowed within the names of environment variables. Therefore, in the above example, although the repository name is test-01, within the environment variable name, the hyphen is replaced by an underscore, i.e., Test_01

9.3. Create an additional Server – Start Job

From the main page of the Team for Capella scheduler, select the New Item link from the menu on the left-hand side of the screen.
Enter the job name and source job template as follows: Set the Job name to "Start server <serverPort> (<repoName> )", where <serverPort> is replaced by the configured server port number, e.g. 2036 and <repoName> is replaced by the repository name, e.g. TEST-01. Activate the Copy existing job radio button. In the Copy from text field, start typing the word "TEMPLATE" and then from the drop-down list that appears, select the entry "TEMPLATE – Start server <serverPort> (<repoName>)". Press OK.
In the job configuration screen, amend the Description text by replacing the placeholders <serverPort> and <repoName> with the actual server port and repository name respectively.
Activate the job by deselecting the Disable this project checkbox.
Modify the Team for Capella server path within the Command field of the Build section, replacing serverPort and repoName within the path name with the configured server port and repository name respectively, for example:
Upon saving the changes to the job the main screen for the new job appears.

9.4. Create an additional Server – Stop Job

From the main page of the Team for Capella scheduler, select the New Item link from the menu on the left-hand side of the screen.
Enter the job name and source job template as follows: Set the Job name to "Server – Stop <serverPort> (<repoName>)", where <serverPort> is replaced by the configured server port number, e.g. 2036 and <repoName> is replaced by the repository name, e.g. TEST-01. Activate the Copy existing job radio button. In the Copy from text field, start typing the word "TEMPLATE" and then from the drop-down list that appears, select the entry "TEMPLATE – Stop server <serverPort> (<repoName>)". Press OK.
In the job configuration screen, amend the Description text by replacing the placeholders <serverPort> and <repoName> with the actual server port and repository name respectively.
Activate the job by deselecting the Disable this project checkbox.
Modify the Team for Capella console port environment variable within the Command field of the Build section, replacing TEAMFORCAPELLA_CONSOLE_PORT_repoName with the appropriate console port environment variable for this Team for Capella server/repo, for example:
```
cd TEAMFORCAPELLA_APP_HOME/tools
command.bat -consoleLog localhost TEAMFORCAPELLA_CONSOLE_PORT_TEST_01 cdo stopserver
```
Upon saving the changes to the job, the main screen for the new job appears.

9.5. Create an additional Database – Backup Job

From the main page of the Team for Capella scheduler, select the New Item link from the menu on the left-hand side of the screen.
Enter the job name and source job template as follows: Set the Job name to "Database – Backup <serverPort> (<repoName>)", where <serverPort> is replaced by the configured server port number, e.g., 2036 and <repoName> is replaced by the repository name, e.g., TEST-01. Activate the Copy existing job radio button. In the Copy from text field, start typing the word TEMPLATE" and then from the drop-down list that appears, select the entry "TEMPLATE – Database – Backup <serverPort> (<repoName>)". Press OK.
In the job configuration screen, amend the Description text by replacing the placeholders <serverPort> and <repoName> with the actual server port and repository name respectively.
Activate the job by deselecting the Disable this project checkbox.
Modify the Team for Capella console port environment variable within the Command field of the Build section, replacing TEAMFORCAPELLA_CONSOLE_PORT_repoName with the appropriate console port environment variable for this Team for Capella server/repo, for example:
```
del *-sql.zip
cd TEAMFORCAPELLA_APP_HOME/tools command.bat -consoleLog localhost TEAMFORCAPELLA_CONSOLE_PORT_TEST_01 capella_db backup ' WORKSPACE'
```
Upon saving the changes to the job the main screen for the new job appears.

9.6. Create an additional Projects – Import Job

From the main page of the Team for Capella scheduler, select the New Item link from the menu on the left-hand side of the screen.
Enter the job name and source job template as follows: Set the Job name to "Projects – Import <serverPort> (<repoName>)", where <serverPort> is replaced by the configured server port number, e.g., 2036 and <repoName> is replaced by the repository name, e.g., TEST-01. Activate the Copy existing job radio button. In the Copy from text field, start typing the word "TEMPLATE" and then from the drop-down list that appears, select the entry "TEMPLATE – Projects – Import <serverPort> (<repoName>)". Press OK.
In the job configuration screen, amend the Description text by replacing the placeholders <serverPort> and <repoName> with the actual server port and repository name respectively.
Activate the job by deselecting the Disable this project checkbox.
It is not recommended to have multiple Import jobs launched at the same time. Each Import job must be shifted in time by at least 30 minutes. In the job configuration, in Build Triggers section, modify the minutes and hours values within the schedule (first and second numeric cron fields) if needed.
Within the Command field of the Build section, modify the Team for Capella server and console ports environment variables and Team for Capella repository name as follows: Replace TEAMFORCAPELLA_SERVER_PORT_repoName with the appropriate server port environment variable for this Team for Capella server/repo Replace TEAMFORCAPELLA_HTTP_PORT with the appropriate rest API server port environment variable for this Team for Capella server/repo Replace <repoName> with the name for this Team for Capella repository:bc. del *.zip del *.txt del *.activitymetadata rd /s /q importer-workspace cd TEAMFORCAPELLA_APP_HOME/tools importer.bat -data "WORKSPACE/importer-workspace" -outputFolder "WORKSPACE" -archiveProject true -stopRepositoryOnFailure true -checksize 5 -importCommitHistoryAsText -port TEAMFORCAPELLA_SERVER_PORT_repoName -httpPort TEAMFORCAPELLA_HTTP_PORT -repoName TEST_01
Upon saving the changes to the job, the main screen for the new job appears.

10. Troubleshooting

10.1. Jenkins window service is not launched when there are multiple versions of Java installed

By default, Jenkins will be launched using the java executable found in Windows\System. If the java version from this java executable is different from the key Java Runtime Environment\CurrentVersion in the registry, the service cannot be installed. If this problem is encountered, there are 2 solutions:

Make sure that the version of the key Java Runtime Environment\CurrentVersion is the same as the java executable found in Windows\System.
Modify the jenkins.xml to replace java executable by the absolute path to the chosen installed java.