Jenkins Configuration

Team for Capella Scheduler

Team for Capella embeds a Jenkins server as a scheduler.

The version shipped in Team for Capella is Jenkins LTS 2.150.1.

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

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

http://localhost:8036

Many jobs are built-in, already configured and organized in views: "Server Management", "Backup and Restore", "Diagnostic and Repair" and "Templates". 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.

Server Management

Server - Start

This job starts the server. It never stops (and must not be aborted) except if “Server - Stop” is launched.

Server - Stop

This job stops the server.

List connected projects and locks on model

This job lists :

Importer - Store credentials

This jobs stores the credentials that are used by the Importer. As credentials needs to be associated with a repository, when this job is executed it will start by asking to fill the following parameters:

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

Importer - Clear credentials

This jobs is the opposite of the previous one, it clears the stored credentials that are used by the Importer. As credentials are associated with a repository, when this job is executed it will start by asking to fill the following parameters:

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

License Server - Start

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

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

Backup and Restore

Database - Backup

This job does a dump of the database into a zip file and keep it as an artefact of the build.

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 to have one database path per repository. See How to Add a New Repository

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.

Projects - Import

It executes the importer application to import projects automatically from a server without any user interaction and archives them as Job’s artifacts.

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.

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 to get imported projects. Then you could have data loss if one day you really need those imported projects. In that case, you may:

User profile - Import model

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

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

Diagnostic and Repair

Repository - Diagnostic

This maintenance job needs to be manually launched. This job runs a diagnostic in order 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.

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 backup 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 need to be configured according to your repository name.

Templates

This view contains templates of jobs which are disabled by default.

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

How to Start the Team for Capella Scheduler

There are two ways to start the Scheduler: as a classic process or as a Windows service.

How to Start the Team for Capella Scheduler as classic process

Launch /scheduler/scheduler.bat to start the scheduler as a classic process.

Once scheduler.bat file has been launched, the following command dialog should be raised :

How to Start the Team for Capella Scheduler as Windows service

If the Scheduler was launched as a classic process (scheduler.bat), just stop the process (the opened command dialog can be closed).
Launch /scheduler/winservice.bat to install the service "TeamForCapellaScheduler", then open Windows service management application Start > run > "services.msc" , the service should be visible


Menu > Properties on it , the service configuration dialog is shown


Set the "Startup type:" parameter to "Automatic" (making the service start with the computer).

In the "Log On" tab, configure the Windows account that will run the service. This account must have correct access rights to allow the Scheduler and the Team For Capella Server to access their data files.

If needed, start the service.

Note : /scheduler/jenkins_home/jenkins.xml file contains the definition of the service.


How to Stop the Team for Capella Scheduler


Activate Security in Jenkins

By default in the scheduler, the security checks are disabled. This means:

To enable these security checks, users can use the option "Configure Global Security" as follows:

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

  1. Connect to Jenkins as a user with administration rights.
  2. Select Manage Jenkins .
  3. Select Configure Global Security .
  4. Select the Enable security checkbox, the LDAP security realm radio button and then the Advanced... button underneath the LDAP server text field.
  5. 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.
  6. To ensure that only logged-in users can perform actions, select Authorization -> Logged-in users can do anything.
  7. Save the configuration changes.
  8. 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:

  1. Connect to Jenkins as a user with administration rights.
  2. Select Manage Jenkins .
  3. Select Configure Global Security .
  4. 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 .
  5. Save
  6. Create a user (menu in top right corner)
  7. 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 ).
  8. In the security realm section, remove the check mark next to '' Allow users to sign up '
  9. In the Authorization section, select the Matrix-based security mode,
  10. In the text box below the matrix, type your user name and click Add
  11. Give yourself full access by checking the entire row for your user name
  12. Repeat for other users who deserve full access.
  13. 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.
  14. 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://jenkins.io/doc/book/system-administration/security/ .

How to Change the Port Used by Scheduler Admin Site

java -Djava.io.tmpdir=%JENKINS_HOME%\temp -Djenkins.install.runSetupWizard=false -jar %JENKINS_HOME%/jenkins.war --webroot=%JENKINS_HOME%/war --httpPort=8036 --extractedFilesFolder=%JENKINS_HOME%\temp

--httpPort=$HTTP_PORT Runs Jenkins listener on port $HTTP_PORT (being the port you want Jenkins to run on) using standard http protocol. The default is port 8080.

Ex:

--httpPort=8036 to access the scheduler admin page using http://hostname_of_teamforcapella_server:8036

--httpPort=8080 to access the scheduler admin page using http://hostname_of_teamforcapella_server:8080


<executable>java</executable> <arguments>-Xrs -Xmx256m -Djava.io.tmpdir=%JENKINS_HOME%\temp -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -jar "%BASE%\jenkins.war" --httpPort=8036 --webroot="%BASE%\war" --extractedFilesFolder="%JENKINS_HOME%\temp"</arguments>

How to Change Backup and Import Files Purge Policy


How to Dissociate Multiple Projects in Jenkins

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.

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 “Jenkins” tab, “New Job” and select “Copy existing Job”). Copy the “Project 1 - Import“ job and rename it into “Project 2 - Import“. The result is the following:

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.

Access Rights Definition (whole Jenkins instance level)

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

Do the following changes in the table:

The table must be as follows:

Click on “Save”.

Access rights are now activated:

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

Access Rights Definition (job/project level)

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

Do the following changes in the table:

Do the same work on all jobs linked to Project1.

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

Result



Known Limitations


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:

Tips and Tricks

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!

  1. Select Manage Jenkins .
  2. Select Configure System .
  3. 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 .

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

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.

  1. Select Manage Jenkins .
  2. Select Configure System .
  3. Within the section Global properties -> Environment variables , press the Add button in order to add a new variable.
  4. Enter the server port environment variable name and value as follows: Set name to CAPELLA_TEAM_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 .
  5. Press the Add button in order to add a new variable.
  6. Enter the console port environment variable name and value as follows: Set name to CAPELLA_TEAM_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 names is test-01, within the environment variable name the hyphen is replaced by an underscore, i.e. Test_01

Create a Server - Start Job from Template

  1. From the main page of the Team for Capella scheduler, select the New Job link from the menu on the left-hand side of the screen.
  2. 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 .
  3. 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.
  4. Activate the job by de-selecting the Disable this project checkbox.
  5. 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:
  6. Upon saving the changes to the job the main screen for the new job appears.

Create a Server - Stop Job from Template

  1. From the main page of the Team for Capella scheduler, select the New Job link from the menu on the left-hand side of the screen.
  2. 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 - Server - Stop _serverPort_ (_repoName_ )". Press OK .
  3. 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.
  4. Activate the job by de-selecting the Disable this project checkbox.
  5. Modify the Team for Capella console port environment variable within the Command field of the Build section, replacing CAPELLA_TEAM_CONSOLE_PORT_repoName with the appropriate console port environment variable for this Team for Capella server/repo, for example:
    			cd %TEAMFORCAPELLA_APP_HOME%/capella/eclipse
    			command.bat -consoleLog localhost %CAPELLA_TEAM_CONSOLE_PORT_TEST_01% cdo stopserver
  6. Upon saving the changes to the job the main screen for the new job appears.

Create a Database - Backup Job from Template

  1. From the main page of the Team for Capella scheduler, select the New Job link from the menu on the left-hand side of the screen.
  2. 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 .
  3. 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.
  4. Activate the job by de-selecting the Disable this project checkbox.
  5. Modify the Team for Capella console port environment variable within the Command field of the Build section, replacing CAPELLA_TEAM_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%/capella/eclipse
    			command.bat -consoleLog localhost %CAPELLA_TEAM_CONSOLE_PORT_TEST_01% capella_db backup '%WORKSPACE%'
  6. Upon saving the changes to the job the main screen for the new job appears.

Create an Projects - Import Job from Template

  1. From the main page of the Team for Capella scheduler, select the New Job link from the menu on the left-hand side of the screen.
  2. 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 .
  3. 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.
  4. Activate the job by de-selecting the Disable this project checkbox.
  5. It is not recommended to have multiple Import jobs launched at the same time. Each Import jobs 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.
  6. 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 CAPELLA_TEAM_SERVER_PORT_repoName with the appropriate server port environment variable for this Team for Capella server/repo Replace CAPELLA_TEAM_CONSOLE_PORT_repoName with the appropriate console port environment variable for this Team for Capella server/repo Replace <repoName> with the name for this Team for Capella repository:
    			del *.zip
    			del *.txt
    			del *.activitymetadata
    			rd /s /q importer-workspace
    			cd %TEAMFORCAPELLA_APP_HOME%/capella/eclipse
    			importer.bat -data "%WORKSPACE%/importer-workspace" -archivefolder "%WORKSPACE%" -closeserveronfailure true -checksize 5 -importCommitHistoryAsText -port %CAPELLA_TEAM_CONSOLE_PORT_TEST_01% -consoleport %CAPELLA_TEAM_CONSOLE_PORT_TEST_01% -repoName TEST_01
  7. Upon saving the changes to the job the main screen for the new job appears.

Troubleshooting

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: