ARIS

UPDATE COOKBOOK

VERSION 10.0 - SERVICE RELEASE 18

MAY 2022
This document applies to ARIS Version 10.0 and to all subsequent releases.
Specifications contained herein are subject to change and these changes will be reported in
subsequent release notes or new editions.
Copyright © 2010 - 2022 Software AG, Darmstadt, Germany and/or Software AG USA Inc.,
Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.
The name Software AG and all Software AG product names are either trademarks or
registered trademarks of Software AG and/or Software AG USA Inc. and/or its subsidiaries
and/or its affiliates and/or their licensors. Other company and product names mentioned
herein may be trademarks of their respective owners.
Detailed information on trademarks and patents owned by Software AG and/or its
subsidiaries is located at https://softwareag.com/licenses.
Use of this software is subject to adherence to Software AG's licensing conditions and terms.
These terms are part of the product documentation, located at
https://softwareag.com/licenses and/or in the root installation directory of the licensed
product(s).
This software may include portions of third-party products. For third-party copyright notices,
license terms, additional rights or restrictions, please refer to "License Texts, Copyright
Notices and Disclaimers of Third Party Products". For certain specific third-party license
restrictions, please refer to section E of the Legal Notices available under "License Terms and
Conditions for Use of Software AG Products / Copyright and Trademark Notices of Software
AG Products". These documents are part of the product documentation, located at
https://softwareag.com/licenses and/or in the root installation directory of the licensed
product(s).
UPDATE COOKBOOK

Contents
Contents ........................................................................................................................................................... I

1 Scope & Motivation ................................................................................................................................ 1

2 Checklist .................................................................................................................................................. 2

3 Prerequisites ........................................................................................................................................... 3

4 How to prevent the setup to fail ........................................................................................................ 6

4.1 Check all files ............................................................................................................................. 7
4.2 Set write attribute to all files .................................................................................................. 8
4.3 Make files accessible that are used by other processes.................................................. 8

5 Clean up the installation ...................................................................................................................... 9

5.1 Archive and then delete all old log files (Optional) ............................................................ 9
5.1.1 Archive all log files ....................................................................................................... 10
5.1.2 Delete all log files .......................................................................................................... 10

I
UPDATE COOKBOOK

6 Backup data ........................................................................................................................................... 11

6.1 How to back up data manually............................................................................................. 12

7 Log modification steps and backup all manual changes ............................................................ 15

8 Update ARIS Agents on all nodes..................................................................................................... 16

8.1 Update ARIS Agents ............................................................................................................... 16
8.2 Validate the ARIS Agent update .......................................................................................... 16

9 Prepare ARIS Cloud Controller (ACC) ............................................................................................... 17

9.1 How to start ARIS Cloud Controller (ACC) ......................................................................... 19

10 Prepare and provide remote repository ......................................................................................... 22

10.1 Provide remote repository using a Web server ................................................................ 22
10.2 Provide remote repository using a local file folder.......................................................... 23

11 Update all runnables on all nodes .................................................................................................... 24

12 Adjust elasticsearch cluster .............................................................................................................. 26

12.1 Example: adjust elasticsearch cluster ............................................................................... 27
12.2 Getting elastic runnables started again ............................................................................ 28

13 Update the ARIS online help ............................................................................................................. 29

13.1 Stop the related runnables ................................................................................................... 29
13.2 Enhance help ........................................................................................................................... 30
13.3 Names of the help artifacts .................................................................................................. 31
13.4 Execute the help enhancement .......................................................................................... 32

14 Check for incompartible JDBC drivers (optional) ......................................................................... 33

15 Start ARIS .............................................................................................................................................. 34

16 Adjust timestamps (ARIS document storage)............................................................................... 35

17 ARIS Aware specific topics ................................................................................................................ 36

18 Update the demo databases for each tenant ............................................................................... 37

19 Check and upload missing fonts after updating ARIS 10.0.5 or earlier versions ..................38
19.1 Add fonts .................................................................................................................................. 39

20 Update the system database for each tenant .............................................................................. 41

21 Re-index modeling data for each tenant (optional)..................................................................... 42

22 Configure the ARIS Agents on all nodes to use the local repository (optional).....................44

23 Update completed ............................................................................................................................... 45

24 Legal information................................................................................................................................. 46
24.1 Documentation scope............................................................................................................ 46
24.2 Support ..................................................................................................................................... 46

II
UPDATE COOKBOOK

1 Scope & Motivation

This document describes the steps that you must perform if you manually update any ARIS
10.0 installation to any 10.0 SR.
Do not update ARIS manually if you have installed the current ARIS Server using the ARIS
Server setup. To update such an installation, start the most current ARIS Server setup
program to update your installation.
From ARIS 10.0.12.0, ARIS Risk and Compliance and ARIS Server use the same external
database management system if configured. When you update your ARIS Server, ARIS Risk
and Compliance still uses the database connection as configured for ARIS Risk and
Compliance. If you want ARIS Server and ARIS Risk and Compliance to use the same
connection, you must first update ARIS Server. Then configure the database connection
manually, as described in the ARIS Risk and Compliance Installation Guide.
Depending on the current version (source version) that you are going to update to (target
version), some of the steps described below are optional or might not be needed. Some steps
are only required if you are using an external database system, such as Oracle or Microsoft
SQL Server. In these cases, this is indicated at the beginning of the related steps. If there is no
such indication, the step is required regardless of current source or target version.
The steps described in this document are only necessary if you want to:
§ Update an ARIS installation that was originally installed manually by provisioning (either
on a single node or on multiple nodes). We consider an installation as manual if it was not
created with one of the product-specific setups, for example, the ARIS Server setup for a
single-node installation, but by manually installing (empty) ARIS Agents on the machines
and then using ARIS Cloud Controller (ACC) to install or configure the individual
components (so called runnables) that comprise an ARIS system on these agents.
§ Update a setup-based ARIS installation that was changed so that the update setup
refuses to update.
§ Learn about what goes on under the hood of an update setup. After all, the steps
described here are basically what the setup does (but of course only for simple single
node, that is, not distributed installations).

1
UPDATE COOKBOOK

2 Checklist
This list gives an overview about the procedure to be performed.
1. Ensure that required prerequisites are met (page 3)
2. Archive all log files (page 10).
3. Delete old log files (page 10).
4. Backup data (page 11).
5. Log modification steps and backup all manual changes (page 15).
6. Update ARIS Agents on all nodes (page 16).
7. Validate the ARIS Agent updates (page 16).
8. Prepare ARIS Cloud Controller (ACC) (page 17).
9. Provide a remote repository (page 22).
10. Update all runnables on all nodes (page 24).
11. Adjust elasticsearch cluster (page 26).
12. Start ARIS after the update of all runnables is completed (page 34).
13. Update the system database for each tenant (page 41).
14. Adjust timestamps (ARIS document storage) (page 35).
15. Optionally update ARIS Aware (page 36).
16. Update the demo databases for each tenant (page 37).
17. Check and upload missing fonts (ARIS 10.0.5 or earlier) (page 38).
18. Update the ARIS online help (page 29).
19. Optionally re-index modeling data for each tenant (page 42).
20. Optionally configure the ARIS Agents on all nodes to use the local repository (page 44).

2
UPDATE COOKBOOK

3 Prerequisites
Before updating an ARIS installation, you must assure that the following prerequisites are
met.
§ You know all required user credentials.
§ The ARIS Agent user name and password (default credentials: Clous/g3h31m) for
each node that is part of the installation to be updated.
§ The password of the superuser user (default credentials: superuser/superuser) or
the password of a user who has all function privileges for each tenant.
§ You have enough free disk space available.
For a successful update, sufficient free disk space must be available on each node that is
part of the update installation.
Warning
Do not try an update if free disk space is limited. The update might fail, and the
installation cannot be repaired. Try to clean up your current installation to delete content
that is not needed any longer (page 9).
The following is a rough guideline on how to determine the disk space required:
§ Determine the currently available free disk space f on the machine where ARIS Agent
runs.
§ Determine the current size w of all runnables working directories located in:
§ Windows: <installation directory>\server\bin\work
§ Linux: /home/ARIS/cloudagent/work).
§ Make sure that the condition f > w + 100 GB is met.
§ All runnables are activated (affecting source versions from 9.8.4 and later)
Starting with ARIS 9.8 SR4, individual runnables can be deactivated. A deactivated
runnable is ignored by the startup process of the runnables. This can be useful in cases
where the full product is installed, but where only a subset of the functionality is initially
used. For example, you might start out only with ARIS Design Server, but for an easier
upgrade to ARIS Connect, ARIS Connect Server was installed. In this case, the unneeded
runnables can be deactivated, such as ECP and PostgresECP.

3
UPDATE COOKBOOK

To keep an installation consistent, however, deactivated runnables must also be updated.

Hence, a deactivated runnable is not ignored by the update process. Some of the steps
described in this guide might require the entire installation or at least one instance of a
specific application to be started for the step to be successful. So, unless you fully
understand the dependencies of the different runnables and which runnables are
involved in which step, it is therefore highly recommended to activate all runnables
before proceeding and deactivate them again later.

4
UPDATE COOKBOOK

§ Sufficient amount of virtual memory is available (affecting ARIS Server installations on

Linux machines)
From ARIS 10 SR4, the elastic runnable (elastic search) requires more virtual memory on
your Linux operating system to prevent indices from causing out-of-memory exceptions.
On the machine where the elastic runnable is installed, check which value the
vm.max_map_count system parameter is currently set to.
For this, use the sysctl vm.max_map_count command. If the value is lower than
262144, change it to 262144.
To change the value for this session only, use the following command (root access
permissions required):
sudo sysctl -w vm.max_map_count=262144
This command changes the value for the current session only. After a reboot, this change
is undone.
To change the value permanently, add this line to the sysctl.conf configuration file that
is available in the ARIS installation directory on your machine:
vm.max_map_count=262144
§ Files are writable.
Make sure that no file in the installation directory is opened or in use by another process
(page 6). Locked files will cause issues while the patch setup is running. Use the task
manager or the process explorer to identify processes that may access related files, such
as notepad or notepad++.
§ Close all ARIS command-line tools, such as ARIS Cloud Controller, ARIS Server
Administrator, ARIS document storage Command-Line Tool, or Process
Governance Command-Line Tool.
§ Close all command prompt boxes that you use to start command-line tools, such as
y-datadump.bat, y-elasticsearch.bat, y-ldapsync.bat, y-password.bat, or
y-tenantmgmt.bat.
§ Sign off all other users to release all possible file locks.
The user account running the ARIS Agent 10.0 Windows service must have the
permission to delete and write files. This is the system user on Windows operating
systems and the ARIS10 user on Linux operating systems.

5
UPDATE COOKBOOK

4 How to prevent the setup to fail

If the prerequisites are not met and files are not writable (page 7), the setup fails because files
cannot be updated. In this case, your installation cannot be automatically restored and ARIS
may no longer run. To restore your installation, you must take further action.
It is a good idea to check whether all files stored in the ARIS Server installation directory are
not locked by other users or processes. You can also force all files to be writable. The user
account running the ARIS Agent 10.0 Windows service must have the permission to delete
and write files. This is the system user on Windows operating systems and the ARIS10 user
on Linux operating systems.

6
UPDATE COOKBOOK

4.1 Check all files

If you currently use ARIS 10.0.6 or a later ARIS version, the check file system permissions
ARIS Cloud Controller command is executed automatically when you run the setup. This
command checks whether all files in the ARIS Server installation work directory can be
deleted. This check takes quite a while if executed on a running ARIS system. As a result, the
first 10 detected files causing a problem are listed. If more files were found not to be writable,
they are listed in the agent.log file.
You can manually execute this command before you start the setup to discover possible
problems. If you do so while all runnables are started, this check will take a long time and a lot
of wrong warnings are reported. This is because some files are regularly locked when ARIS is
running, such as files related to the elastic runnable.
To reduce runtime and the number of warnings, you are recommended stopping all runnables
before you execute the check file system permissions ARIS Cloud Controller command.
This is an example for the check file system permissions ARIS Cloud Controller command
that was executed on a distributed ARIS Server installation containing three nodes.
Node n1: Permission problems found in one runnable:
Permission problems found for runnable adsadmin_l:
Found 1 file that is missing the permission WRITE:
U:\ARIS10.0\server\bin\work\work_adsadmin_l\tools\bin\Documents.zip

Node n2: No permission problems found.

Node n3: No permission problems found.

Problems were found on node n1 regarding the file permissions of the runnable adsadmin_l.
Command failed with exit code 100.
Elapsed Time : 0h 54min

7
UPDATE COOKBOOK

4.2 Set write attribute to all files

To force all files to be writable, execute the following commands.
In Windows operating systems, this command sets the write attribute to all files:
attrib -r <Installation Directory>\bin\work\*.* /s
In Linux operating systems, the following commands are executed by the RPM package. The
commands allow the aris10 user accessing all files:
ARIS Version >= 10.2
. /etc/aris10.conf
cd $TARGETDIR
chown -R aris10 *

ARIS Version < 10.2

cd /home/ARIS10
chown -R aris10 *

4.3 Make files accessible that are used by other

processes
Even if files are readable, they can be blocked when accessed by other processes. To release
all locks make sure to:
§ Close all ARIS command-line tools, such as ARIS Cloud Controller, ARIS Server
Administrator, ARIS document storage Command-Line Tool, or Process Governance
Command-Line Tool.
§ Close all command prompt boxes that you use to start command-line tools, such as
y-datadump.bat, y-elasticsearch.bat, y-ldapsync.bat, y-password.bat, or
y-tenantmgmt.bat. Use the task manager or the process explorer to identify processes
accessing the files.
§ Sign off all other users to release all possible file locks.
§ Reboot the machine to assure that no user has access to any file.

8
UPDATE COOKBOOK

5 Clean up the installation

During the update procedure, backups of the working directories of all runnables are created.
This is to be able to roll back to the original version if the update fails.
Depending on the number of files stored in the working directories of the runnables, backups
consume free disk space. Creating these backups can take a long time. Particularly in
environments with limited disk I/O, such as virtual machines or physical machines using SAN
or NAS as their IO subsystem, the time to create these backups can significantly influence the
total time for performing the update. Nonetheless, you are highly recommended to leave the
automatic backup of runnable working directories enabled.
However, as a preparation step, you can remove unnecessary files from the working
directories. Former ARIS versions used to write many log files that were not removed
automatically.
To provide more free disk space, you can first archive and then delete all log files from the
current ARIS installation. Make sure to store the archive file containing the log files on a
different drive or partition from the one where ARIS is installed.
To archive and delete all log files, use the collect log files and the delete log files ACC
commands. You can also use the batch files provided (see <ARIS installation
directory>\support: collectLogFiles and cleanLogFiles). On Linux systems you can find the
related sh files in the home directory of the ARIS user that was created by the ARIS Cloud
Controller Linux packages.

5.1 Archive and then delete all old log files (Optional)
To reduce the used disk space, you can first archive and then delete all log files of the ARIS
installation. Two batch files are provided for this: collectLogFiles and cleanLogFiles (.bat on
Windows, .sh on Linux). On Windows systems, the files are available in the support folder of
the ARIS installation directory>.

9
UPDATE COOKBOOK

On Linux systems, you can find them in the home directory of the ARIS user that is created by
the ARIS Cloud Controller Linux packages:

5.1.1 Archive all log files

This step is optional but recommended. The collectLogFiles utility collects all log files of all
runnables and the ARIS Agent and puts them into a single LogFiles.zip archive. If you want to
archive all log files before cleaning them, run collectLogFiles first. Depending on the amount
of log files accumulated in your installation, this can take quite a while and of course you need
additional free disk space for the log file archive.
After collectLogFiles has completed, copy the resulting logfiles.zip file to a safe location.

Warning
If you keep the logfiles.zip file with the log files on the same drive/partition where ARIS is
installed, make sure that there is still enough free disk space as described in the
Prerequisites chapter (page 3).

5.1.2 Delete all log files

After you successfully archived the log files, run the deleteLogFiles utility or use the delete
log files ACC command to remove them from the installation directory to increase free disk
space.

10
UPDATE COOKBOOK

6 Backup data
The very first step of an ARIS update is to back up all data.

Warning
If you run an update without having current and complete data backups, you bear the risk for
any data loss or system outage.
There are multiple ways to do a backup:
§ Start a tenant backup for all tenants using ARIS Cloud Controller (ACC). This backup
contains all essential data of a tenant, with the notable exception of any portal
customizations and tenant-specific portal settings.
§ Using the Tenant Management tool is a way to backup and restore the infrastructure
tenant (master) as well as all productive tenants.
By default, backups are stored in the ARIS Server installation directory
(..\server\bin\work\work_umcadmin_<s, m or l>\backup). If you have not yet defined a
different folder on a physical drive, make sure to save the backup folder. As the default
backup folder is overwritten by the update, all backups are lost.
§ Most ARIS components offer individual backup functionalities (page 12). You can back up
databases in ARIS Architect or you can backup user data in the ARIS Administration.
These components also provide command-line tools to be used, such as ARIS Server
Administrator or command line tools for the ARIS Administration.
§ Copy the working directories of all runnables to a safe place or copy the whole ARIS
installation folder. If an external DBMS is used, such as Oracle or Microsoft SQL Server,
create dumps of each schema containing ARIS data.

11
UPDATE COOKBOOK

6.1 How to back up data manually

Administrators have multiple alternatives for manually backing up data.

DATABASE
In ARIS Architect on the Administration tab, using the Backup functionality.
On the command line tool ARIS Server Administrator, using the backup or backupasn
commands.
In ARIS Server Administrator, use the backupsystemdb command to backup filters, method
modifications (such as user-defined attributes, model types etc.), configuration, queries,
report scripts, macros and semantic checks. Alternatively, you can back up the data
mentioned before individually as follows.

FILTER
In ARIS Architect on the 'Administration' tab (../../handling/ba/58888.htm), using the
function Export.

METHOD, CONFIGURATION, AND QUERIES

In ARIS Server Administrator, using the backupsystemdb command.

REPORT SCRIPTS, MACROS AND SEMANTIC CHECKS

In ARIS Architect on the Administration tab individually backup scripts with the function
Export in the pop-up menu for a script. If you have adapted standard scripts and standard
files instead of copies the individual backup is mandatory. All standard scripts and standard
files will be overwritten by an updated. Modifications will be lost.
In ARIS Server Administrator, using the backupsystemdb command.

ALFABET INTEROPERABILITY
If you use ARIS Alfabet interoperability, make sure to backup your modified
ARIS-ALFABET-integration.xml and ARIS-ALFABET-mapping.xml configuration files. You
must restore these files after the server update. Otherwise, your modified configuration will
be lost.

12
UPDATE COOKBOOK

QUERIES AND AD HOC ANALYSES

In ARIS Architect on the Administration tab with the Back up analysis data function.
When you perform an update installation, add languages, or uninstall a component, the
relevant files and directories are backed up automatically. A selection of files is listed here to
provide examples for server installations:
§ <ARIS installation directory>\server\backup
§ <ARIS installation directory>\server\data (saved databases after uninstallation)
§ <ARIS installation directory>\server\sysconfig
§ <ARIS installation directory>\server\templates

PORTAL CONFIGURATION AND MODIFICATION SETS

You can back up the configurations that you configured via the graphical user interface in
ARIS Administration on the Configuration tab with the Backup function (Portal > Manage
views).
The default and the classic configuration set must not be modified. These sets, holding all
new features, are used as template for all future modification sets. The default and the
classic configuration sets are automatically updated.
If the default or the classic configuration set was modified on file level, all changes are lost
after the update. To keep the modifications, proceed as follows:
Copy the folders of the modified default or custom configuration sets from <ARIS installation
path>\server\bin\work\, for example:
§ work_copernicus_<s, m or l>\base\webapps\ROOT\WEB-INF\config\default
§ work_abs_<s, m or l>\base\webapps\abs\WEB-INF\config\default
§ If a Heavy-duty Server (HDS) is in use, the related folder of the hds_<s, m or l> runnable
must be copied as well.

13
UPDATE COOKBOOK

After the update, the content of the default and the classic folders are updated, and your
modifications are lost. Paste the copied folders into the <ARIS installation
path>\server\bin\work\ subfolders, for example:
§ work_copernicus_<s, m or l>\base\webapps\ROOT\WEB-INF\config\<name of the
customized default configuration set>
§ work_abs_<s, m or l>\base\webapps\abs\WEB-INF\config\<name of the customized
default configuration set>
§ If a Heavy-duty Server (HDS) is in use, the related folder of the hds_<s, m or l> runnable
must be copied as well.
To make the content update-proof, the folder must be named other than default, for
example, customized_default.
New ARIS functionality will not be available in the copied configuration sets. You can manually
copy additional lines from the updated default or classic configuration sets and paste them
to the related customized configuration sets.
This advanced configuration requires high knowledge on XML configuration, that can be
acquired in the 742-<ID> ARIS Portal Configuration training
(https://learning.softwareag.com/enrol/index.php?id=198). Errors in XML configuration files
may cause strong impact. You might not be able to start ARIS again.
Depending to the level of customization, you are recommend using a prepared customization
package obtained by the original customizer. If you need help, contact Software AG
(https://empower.softwareag.com/) for a customization request. Customization and training
services are not subject to the standard Software AG software maintenance agreement.
Configuration changes can only be performed by Software AG if you requested and agreed on
them.

14
UPDATE COOKBOOK

7 Log modification steps and backup all manual changes

To modify the ARIS installation or add third party files to your installation, such as JDBC
drivers, SAP JCo adapters, SSL certificates, etc., you are recommended to use the ACC
reconfigure and enhance commands. However, some modifications cannot yet be
performed by ACC, for example, modifications made in configuration files, such as:
ARIS Server
<installDir>\server\bin\work\work_abs_<sizing>\base\webapps\abs\downloadClient\config
\arisloader.cfg
<installDir>\server\bin\work\work_abs_<sizing>\base\webapps\abs\config\defaultServerSe
ttings.cfg

Warning
Any changes made to these files will be lost after an update. You must repeat your
documented changes to those files after each update. Note that some of those changes
might also no longer be relevant in the new ARIS version.
Expect any files copied manually into an installation will be gone after an update. Therefore,
archive these files and document where they need to be copied back to after the update.
Certificates stored in the JRE of ARIS Agent are overwritten by an update. If you update ARIS
Server, the latest JRE containing its own cacert keystore are installed. Certificates stored in
the JRE of ARIS Agent are used, for example, if you use SSL access and ARIS Aware
Dashboards or LDAP.
If you previously had added certificates to your current system to allow SSL connections
between ARIS Server and external systems, you must make these certificates available again
after each update of ARIS Agent.
Any manual changes and physical modifications made on an ARIS installation, such as adding
files, are not preserved during an update. Only modifications made using the reconfigure and
enhance ACC commands are safe unless stated otherwise.
Make sure to note each manual step done after the initial ARIS installation in an installation
protocol.
Of course, all content that you enter into ARIS (models, users, documents, collaboration
comments etc.) via the UI or official interfaces is preserved during an update.

15
UPDATE COOKBOOK

8 Update ARIS Agents on all nodes

Assure that all installation files can be updated. Especially on Windows systems, a file that is
still being used by a process cannot be replaced during the update. Therefore, you must
assure that no program is still using any files or folders inside the ARIS installation directory.
Therefore, make sure that the following prerequisites are met:
§ All ACC commands are stopped
§ All ACC command-line prompts are closed
§ All Windows command-line prompts that access a folder inside the ARIS installation
directory are closed.
§ All Windows Explorers that point to the ARIS installation folder are closed.
All files inside the ARIS installation directory that are not used by external programs, for
example, log files opened by a text editor.

8.1 Update ARIS Agents

Update the ARIS Agents on all nodes of the installation by running the ARIS Agent setup (for
Windows machines) or use the update packages for Linux machines.
Refer to the ARIS Server Update Installation Guides for detailed instructions.
The ARIS Agent setup stops all runnables to update the Java runtime environment (JRE).

8.2 Validate the ARIS Agent update

After ARIS Agent was updated, run the following ACC command to check the new ARIS
version number of all ARIS Agents currently registered in ACC:
on all nodes get agent.version
Make sure that all lines show the same version of the latest update.

16
UPDATE COOKBOOK

9 Prepare ARIS Cloud Controller (ACC)

Copy the generated.apptypes.cfg file from the ARIS Server setup folder and overwrite the
existing file in the ARIS installation folder, for example, C:\SoftwareAG\ARIS10.0\server.
Then start ARIS Cloud Controller (ACC) (page 19) with the command-line option -c <path to
generated.apptypes.cfg> to provide ACC with the necessary information about the runnable
of the new ARIS version. Make sure that ACC is started from now on with the new
generated.apptypes.cfg file, for example, by creating or modifying a shortcut to ARIS Cloud
Controller.

Examples
acc.bat -c "C:\SoftwareAG\ARIS10.0\server\generated.apptypes.cfg"
acc.bat -c "C:\SoftwareAG\ARIS10.0\server\generated.apptypes.cfg" -n nodes.nf
nodes.nf (example):
add node n1 ARISServerNode1 Clous g3h31m
add node n2 ARISServerNode2 Clous g3h31m
add node n3 ARISServerNode3 Clous g3h31m
Add all nodes of your distributed ARIS installation:
§ Either use the add node command manually whenever you start ACC
§ Or use a node file containing all add node commands which you pass as command-line
option -n to ACC
The default settings for runnables provided in the generated.apptypes.cfg file can change
from version to version.
However, in versions prior to ARIS 9.8, changes to the settings in the new
generated.apptypes.cfg file (everything in the lines after defaults) will not be applied during
an update.
As of version 9.8, only a selected subset of the default parameter changes is applied. You can
identify the parameters in the generated.apptypes.cfg file that are changed during the
update. They are marked with the prefix ! or ~. For example:
register app type umcadmin_s com.aris.umcadmin.y-umcadmin-run-prod 10.0.18.0
defaults connector.ajp.executor.maxThreads=50
connector.http.executor.maxThreads=50 JAVA-Xmx="256m"
~connector.ajp.packetSize=32768 connector.ajp.port=14481
~connector.http.maxHttpHeaderSize=32768 connector.http.port=14480
JAVA-Dcom.sun.management.jmxremote.authenticate="false"
JAVA-Dcom.sun.management.jmxremote.port="14486"
JAVA-Dcom.sun.management.jmxremote.ssl="false"
JAVA-Dcom.sun.management.jmxremote="/enabled"
JAVA-Dcom.sun.management.jmxremote.local.only="true" ~"JAVA-XX\\:
+CrashOnOutOfMemoryError"="/enabled" ~"JAVA-XX\\:
+HeapDumpOnOutOfMemoryError"="/enabled" ~"JAVA-XX
:MaxHeapFreeRatio"="30" -"JAVA-XX

17
UPDATE COOKBOOK

:MaxPermSize" ~"JAVA-XX
:MinHeapFreeRatio"="10" JAVA_OPTS="-server"
zookeeper.connect.retry.time.ms="30000" !zookeeper.session.timeout.ms="60000"
§ Parameters marked with the prefix ~ are applied, if the parameter is NOT already set for
the runnable. Parameters that were set or changed manually are retained.
§ Parameters marked with the prefix ! are applied regardless of whether the parameter is
already set or not.
Warning
Parameters that were set or changed manually are overwritten.

18
UPDATE COOKBOOK

9.1 How to start ARIS Cloud Controller (ACC)

ACC is a command-line tool (see ARIS Cloud Controller (ACC) Command-Line Tool.pdf
(../../documents/3 Installation/31 Initial installation/312 Server/3121 Basic (Single node)/ARIS
Cloud Controller (ACC) Command-Line Tool.pdf)) for administrating and configuring an ARIS
installation. It communicates with ARIS Agents on all nodes.

Warning
Using ACC commands will deeply affect your system. This requires profound knowledge of
the technical ARIS infrastructure and environment. The required know-how can be acquired
only by attending the training course ARIS Server Installation, available via Global Education
Services (https://softwareag.com/training). If you use ACC commands without this
knowledge or without the services of Software AG, according to the standard Software AG
software maintenance agreement, we cannot guarantee proper functioning.
ARIS Cloud Controller (ACC) can be used in three modes:

INTERACTIVE MODE (DEFAULT)

ACC runs with an interactive shell, allowing you to manually issue commands.

BATCH MODE
Activated by specifying a command file with the -f command line parameter (see ACC
command line parameters below). ACC will execute the commands in the file in the given
sequence and exit after execution or if one of the commands fails.
A command file line starting with # will be interpreted as a comment line and ignored by ACC.

COMMAND MODE
You can directly pass a single command to ACC as a command line parameter. The command
will be executed and ACC will exit afterwards.
When passing commands directly as a command line parameter, you must be careful when
escaping strings in your command, for example, double-quote-delimited parameters. The
operating system command shell will consume the double quotes, leaving your string
parameter un-escaped. So please escape the quote characters and special characters.

19
UPDATE COOKBOOK

Examples
If you issue the command in command mode, for example:
set remote.repository.url="http://something.com/repo"
You must enter:
acc.bat -h localhost -u <user name> -pwd <remoteAccessPassword> set
remote.repository.url=\"http://something.com/repo\"
If you enter:
acc.bat -h localhost -u <user name> -pwd <remoteAccessPassword> set
remote.repository.url="http://something.com/repo"
ACC will return an error message, for example:
line 1:52 mismatched character '<EOF>' expecting '\n'
Invalid or erroneous command "set
remote.repository.url=http://something.com/repo ": line 1:30 extraneous
input ':' expecting EOF
Use "help" to display a list of available commands.
This also affects passwords and names containing special characters. If you try to back up
your tenants using the following command, make sure to escape the quote characters and
the special character & used in the password User&12345.
If your username or password includes any special character, add a backslash (\) before the
character for ACC to process the special character as a string. That is, if there is an
ampersand (&), in your password, add a backslash before the ampersand.
./acc.bat -h localhost -u Clous -pwd g3h31m -p 18011 -c
../generated.apptypes.cfg backup tenant default username=\"admin\"
password=\"User\&12345\"

To get information about the usage of ACC commands, enter help or help <command>.

20
UPDATE COOKBOOK

WINDOWS OPERATING SYSTEM

To start ACC under a Windows operating system click Start > All Programs > ARIS >
Administration > Start ARIS Cloud Controller. If you have changed agent user credentials
you must enter the user name and/or the password.

LINUX OPERATING SYSTEM

To start ACC under a Linux operating system, execute the acc10.sh shell script instead. To do
so, enter: su -c acc10.sh aris10. After the ARIS Server installation has completed on a Linux
operating system, the aris10 user is locked and has no password. Command-line tools (sh
files), such as ARIS Server Administrator or ARIS Cloud Controller can only be started by
the aris10 user related to the ARIS Agent.
§ To unlock the aris10 user, enter: passwd -u aris10
§ To interactively enter a password, enter: passwd aris10
§ To start the command-line tools, enter: su -c acc10.sh aris10 or su -c arisadm.sh aris10
§ To execute these command-line tools as an ARIS user that has no root privileges, you
must enter the password of the aris10 user.
§ To copy files manually into the ARIS directory, as the aris10 user use the commands: su
aris10 and sudo aris10
As an ARIS user that has no root privileges, you must make sure that the files have the
correct ownership (aris10).
§ To lock the aris10 user again enter: passwd -l aris10

21
UPDATE COOKBOOK

10 Prepare and provide remote repository

On all nodes, each ARIS Agent must be set so that it does NOT use the local repository. Enter
this ACC command:
on all nodes set local.repository.only=false

10.1 Provide remote repository using a Web server

Copy the Setup_Data folder from the downloaded installation package to a Web or FTP
server.
If you use Inter Information Server (IIS) to serve as remote repository, add the extension .war
with MIME Type text/plain to avoid issues that can occur when importing the ARIS help.
On all nodes, point each ARIS Agent to the prepared web server that holds the repository
containing the runnables of the new ARIS version. The following command points to a web
server:
on all nodes set
remote.repository.url="http://<your_webserver>/<full_path_to_Setup_Data_folder>
"

Example
If the host name of your Web server is intranet, the Web server is serving http requests on
port 8080 instead of using the default port 80, and the contents of the Setup_data folder
are copied the folder arisrepo/10.0.18.0 enter this command to provide a remote repository
using a Web server:
on all nodes set remote.repository.url=http://intranet:8080/arisrepo/10.0.18.0

22
UPDATE COOKBOOK

10.2 Provide remote repository using a local file folder

If you do not have a Web or FTP server available in your environment, and you do not want to
install one, you can copy the Setup_Data folder to a local folder on all nodes and point to
that location.

Warning
Note that each location must be a physical drive because mapped network drives do not work
as repositories, because the ARIS Agent runs in the security context system that can only
access physical drives.
Copy the Setup_Data directory from the ARIS installation package to a physical drive on
each node. Use the same folder on every node to simplify the procedure, because only if you
use the same name you can use the on all nodes command.
On all nodes, specify that each ARIS Agent uses a local folder by using a file URL in the
remote.repository.url ACC command set.
To use a local folder using a file URL in the ACC command set remote.repository.url enter:
on all nodes set remote.repository.url="file://<physicalPath>"
Replace <physicalPath> with the path to the folder that contains the Setup_data folder. If
you copy the physical path from your Windows Explorer, make sure to replace the
backslashes with forward slashes. The URL must only contain forward slashes.
For example, if you copied the Setup_Data folder to C:\temp\Setup_Data, enter:
on all nodes set remote.repository.url="file://c:/temp/Setup_Data"

23
UPDATE COOKBOOK

11 Update all runnables on all nodes

To update all runnables on all nodes, run this ACC command:
on all nodes updateall
or
on all nodes force updateall
The force updateall command prevents confirmation for each node.
This command creates a backup of all working folders before any change is made. The
backups are stored in the folder <ARIS Installation path>\server\bin\.backup.
These backups allow to reset to the previous ARIS version. This prevents a possible
impairment of the system. If an update fails, a mixture of runnables from the previous version
and the most recent version would result. Such an ARIS installation will most likely not work.
Note that reset to the previous ARIS version is not required for the ARIS Agent because the
ARIS Agent can use runnables of former ARIS versions.
The backup of the working folders takes some time and consumes a significant amount of
disk space.

Warning
Make sure to backup application data before starting the update setup because the backups
created automatically during the update process cannot be used as a backup of your
application data.
You can turn the backup option off. If you do so, a rollback to the previous ARIS version is no
longer possible. If you attempt an update without backing up your data, you run the risk of
system outages and/or data loss, for which Software AG assumes no responsibility.
The updateall command first checks whether enough disk space is available. If the required
amount is not available, a message is displayed, such as:
On node localhost 20,93 GB of usable space is available for back up, downloaded
artifacts, working directory, plugins and unpacked runnables, but 72,67 GB
must be available.
In this case, make sure that the requires amount of free disk space is available.
If the updateall ACC command was successful, the output looks like the following example of
a three-node installation. Of course, versions, node names, runnable instance IDs, etc. can
vary depending on the environment:
ACC+ >on all nodes updateall
WARNING! The updateall command will update ALL currently not running instances on
all nodes. Are you sure? (Y/N)
y
Runnable zoo0 on node n1 will be updated to version 10.0.18.0
Runnable cloudsearch_m on node n1 will be updated to version 10.0.18.0
Runnable umcadmin_m on node n1 will be updated to version 10.0.18.0
Runnable abs_m on node n1 will be updated to version 10.0.18.0

24
UPDATE COOKBOOK

Runnable apg_m on node n1 will be updated to version 10.0.18.0

Runnable copernicus_m on node n1 will be updated to version 10.0.18.0
Runnable zoo0 on node n2 will be updated to version 10.0.18.0
Runnable elastic_m on node n2 will be updated to version 10.0.18.0
Runnable couchdb_m on node n2 will be updated to version 10.0.18.0
Runnable adsadmin_m on node n2 will be updated to version 10.0.18.0
Runnable umcadmin_m on node n2 will be updated to version 10.0.18.0
Runnable octopus_m on node n2 will be updated to version 10.0.18.0
Runnable simulation_m on node n2 will be updated to version 10.0.18.0
Runnable loadbalancer_m on node n2 will be updated to version 10.0.18.0
Runnable zoo0 on node n3 will be updated to version 10.0.18.0
Runnable postgresECP_m on node n3 will be updated to version 10.0.18.0
Runnable cloudsearch_m on node n3 will be updated to version 10.0.18.0
Runnable couchdb_m on node n3 will be updated to version 10.0.18.0
Runnable adsadmin_m on node n3 will be updated to version 10.0.18.0
Runnable abs_m on node n3 will be updated to version 10.0.18.0
Runnable copernicus_m on node n3 will be updated to version 10.0.18.0
Runnable ecp_m on node n3 will be updated to version 10.0.18.0
Runnable loadbalancer_m on node n3 will be updated to version 10.0.18.0
Successfully updated runnable zoo0 on node n2 from version 10.0.0.2 to version 10.0.18.0
Successfully updated runnable elastic_m on node n2 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable couchdb_m on node n2 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable adsadmin_m on node n2 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable umcadmin_m on node n2 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable octopus_m on node n2 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable simulation_m on node n2 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable loadbalancer_m on node n2 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable zoo0 on node n1 from version 10.0.0.2 to version 10.0.18.0
Successfully updated runnable cloudsearch_m on node n1 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable umcadmin_m on node n1 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable abs_m on node n1 from version 10.0.0.2 to version 10.0.18.0
Successfully updated runnable apg_m on node n1 from version 10.0.0.2 to version 10.0.18.0
Successfully updated runnable copernicus_m on node n1 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable zoo0 on node n3 from version 10.0.0.2 to version 10.0.18.0
Successfully updated runnable postgresECP_m on node n3 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable cloudsearch_m on node n3 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable couchdb_m on node n3 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable adsadmin_m on node n3 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable abs_m on node n3 from version 10.0.0.2 to version 10.0.18.0
Successfully updated runnable copernicus_m on node n3 from version 10.0.0.2 to version
10.0.18.0
Successfully updated runnable ecp_m on node n3 from version 10.0.0.2 to version 10.0.18.0
Successfully updated runnable loadbalancer_m on node n3 from version 10.0.0.2 to version
10.0.18.0
23 of 23 runnables updated.

25
UPDATE COOKBOOK

12 Adjust elasticsearch cluster

If you update from an ARIS version prior to 10.0.12, you must update all cluster-related
configuration parameters of all elastic runnables. To do so, run this ACC command (see
example (page 27)):
adjust elasticsearch cluster

Warning
If you do not execute this command before you start all runnables, all elastic runnables will
remain in the STARTING state and the system cannot be started. In this case, you must take
more extensive action (page 28) to get all elastic runnables started.

26
UPDATE COOKBOOK

12.1 Example: adjust elasticsearch cluster

If you updates all runnables on all nodes, you must execute the adjust elasticsearch cluster
command:
ACC+ >adjust elasticsearch cluster
Checking current cluster state
Determining required adjustments.
Found 3 Elasticsearch instances that must be adjusted:
Instance elastic_l on node n1:
JAVA-Xms will be set to 4g
ELASTICSEARCH.cluster.initial_master_nodes will be set to
sbrvmaris01_eur_com, sbrvmaris02_eur_com, sbrvmaris03_eur_com
Instance elastic_l on node n2:
JAVA-Xms will be set to 4g
ELASTICSEARCH.cluster.initial_master_nodes will be set to
sbrvmaris01_eur_com, sbrvmaris02_eur_com, sbrvmaris03_eur_com
Instance elastic_l on node n3:
JAVA-Xms will be set to 4g
ELASTICSEARCH.cluster.initial_master_nodes will be set to
sbrvmaris01_eur_com, sbrvmaris02_eur_com, sbrvmaris03_eur_com
There were no errors or warnings.

Do you want to continue with the adjustment? (Y/N) y

Checking current cluster state

Determining required adjustments.
Adjusting instance elastic_l on node n1.
OK
Adjusting instance elastic_l on node n2.
OK
Adjusting instance elastic_l on node n3.
OK
3 Elasticsearch instances were adjusted:

Instance elastic_l on node n1:

JAVA-Xms was set to 4g
ELASTICSEARCH.cluster.initial_master_nodes was set to
sbrvmaris01_eur_com, sbrvmaris02_eur_com, sbrvmaris03_eur_com
Instance elastic_l on node n2:
JAVA-Xms was set to 4g
ELASTICSEARCH.cluster.initial_master_nodes was set to
sbrvmaris01_eur_com, sbrvmaris02_eur_com, sbrvmaris03_eur_com
Instance elastic_l on node n3:
JAVA-Xms was set to 4g
ELASTICSEARCH.cluster.initial_master_nodes was set to
sbrvmaris01_eur_com, sbrvmaris02_eur_com, sbrvmaris03_eur_com
There were no errors or warnings.

27
UPDATE COOKBOOK

12.2 Getting elastic runnables started again

If you did not execute the adjust elasticsearch cluster ACC command before you started all
runnables (page 26), you must take more extensive action to get all elastic runnables started
again.
§ If elastic runnables remain in the STARTING state, enter:
on all nodes stopall
§ If runnables cannot be stopped, enter:
on all nodes killall
on all nodes startall to zoo<m or l>
§ If runnables still do not start properly, you must delete the migration node from the leader
node of the elastic runnable in the ARIS Zookeeper. To do so, enter:
force zk delete /aris/services/elasticsearch/migration
force adjust elasticsearch cluster
Because all ARIS Agents that contain nodes holding elastic runnables, you must restart
all related ARIS Agents. To do this prevent the autostart of the ARIS agents.
To get all runnables started after you executed the adjust elasticsearch cluster ACC
command, follow the steps in the following examples:
§ If n1 contains an elastic runnable, enter:
on n1 set autostart.mode="off"
on n1 restart agent
on n1 set autostart.mode="all"
on n1 get autostart.mode
§ If n2 contains an elastic runnable, enter:
on n2 set autostart.mode="off"
on n2 restart agent
on n2 set autostart.mode="all"
on n2 get autostart.mode
§ If n3 contains an elastic runnable, enter:
on n3 set autostart.mode="off"
on n3 restart agent
on n3 set autostart.mode="all"
on n3 get autostart.mode
§ To start all runnables, enter:
on all nodes startall

28
UPDATE COOKBOOK

13 Update the ARIS online help

In newer ARIS versions, the online help files are no longer part of the runnables. That is why
help files must be updated by so-called enhancements that add files to a runnable. Updating
a runnable removes such enhancements. Hence, the help files of the new ARIS version must
be added again after the update.
The online help files for ARIS Publisher Server are part of the runnable and do not have to be
enhanced.
The same applies to ARIS Risk and Compliance up to and including version 9.8 SR1. Since
version 9.8 SR2 the ARIS Risk and Compliance online help must be added as with ARIS.

13.1 Stop the related runnables

Even if the system was not started yet, check that on all nodes all runnables that are to be
enhanced are in the STOPPED state.
To check the state, enter:
on all nodes list
You can stop all runnables with a specific instance ID on all nodes using the ACC command:
on all nodes stopall

29
UPDATE COOKBOOK

13.2 Enhance help

The basic structure of an enhancement command for adding the help to runnables apg,
umcadmin, adsadmin, octopus, and copernicus is as follows:
on <node name> enhance <instance ID> with help <help artifact> <version> type war
where:
<node name> is the logical name of the node, for example, n1.
<instance ID> is the instance ID of the runnable you want to add the help to, for example,
octopus_m.
<help artifact> is the technical name of the actual set of help files, for example,
com.aris.documentation.architect. The technical name can be different for the help of
different runnables.
<version> is the version you are updating to, for example, 10.0.18.0.
For the abs runnable, some parts of the online help have been separated into dedicated files
for different languages. The language can be specified with an additional option, the
<classifier> in the enhance command. For adding help to the abs runnable, the structure of
the enhance command is therefore:
on <node name> enhance <instance ID> with help <help artifact> <version> classifier
<lang> type war
The placeholders <node name>, <instance ID>, <help artifact>, and <version> have the
same meaning as described above.
<lang> is the language of the help artifact. Currently, there are abs help files for five different
languages available: en (English), de (German), fr (French), es (Spanish), and ja (Japanese).
You can easily add all languages using multiple enhancement commands or just select the
languages you need depending on your user base.
We recommend using the enhanceall command (see ACC help).

30
UPDATE COOKBOOK

13.3 Names of the help artifacts

The name of the help artifacts of the different runnables are the following:

Runnable Help artifacts (since version) Languages

abs com.aris.documentation.architect de, en, fr, es, ja

pt (since 9.8.2)
ru, zh, nl (since 9.8.6)

com.aris.documentation.architect-scripthelp -

com.aris.documentation.architect-methodhelp -1, de, en, fr, es, ja

pt, ru, zh, nl (since
9.8.6)

adsadmin com.aris.documentation.administration.ads -

umcadmin com.aris.documentation.administration.administ -
ration -
com.aris.documentation.administration.tm
com.aris.documentation.administration.infrastru
cture (since 10.9.0)

copernicus com.aris.documentation.connect -

apg com.aris.documentation.processboard -

arcm com.aris.documentation.arcm.arcm -

1
The ARIS method help consists of a common part (an artifact without language classifier) and
parts for the different languages. The common part should always be enhanced, while the
language specific parts can be chosen depending on the languages required by users.

31
UPDATE COOKBOOK

13.4 Execute the help enhancement

To add all required enhance commands, take the basic structure of the enhance commands
shown above and replace the parameters <node name>, <instance ID>, <artifact name>,
<version>, and for the abs runnable only the parameter <lang> accordingly.
enhanceall abs_l with help com.aris.documentation.architect-methodhelp 10.0.18.0 classifier
de type war
enhanceall abs_l with help com.aris.documentation.architect-methodhelp 10.0.18.0 classifier
en type war
enhanceall abs_l with help com.aris.documentation.architect-methodhelp 10.0.18.0 classifier
fr type war
enhanceall abs_l with help com.aris.documentation.architect-methodhelp 10.0.18.0 classifier
es type war
enhanceall abs_l with help com.aris.documentation.architect-methodhelp 10.0.18.0 classifier
ja type war
enhanceall abs_l with help com.aris.documentation.architect-methodhelp 10.0.18.0 classifier
pt type war
enhanceall abs_l with help com.aris.documentation.architect-methodhelp 10.0.18.0 classifier
ru type war
enhanceall abs_l with help com.aris.documentation.architect-methodhelp 10.0.18.0 classifier
zh type war
enhanceall abs_l with help com.aris.documentation.architect-methodhelp 10.0.18.0 classifier
nl type war
enhanceall abs_l with help com.aris.documentation.architect-methodhelp 10.0.18.0 type war
enhanceall abs_l with help com.aris.documentation.architect-scripthelp 10.0.18.0 type war
enhanceall umcadmin_l with help com.aris.documentation.administration.administration
10.0.18.0 type war
enhanceall umcadmin_l with help com.aris.documentation.administration.tm 10.0.18.0 type war
enhanceall adsadmin_l with help com.aris.documentation.administration.ads 10.0.18.0 type war
enhanceall apg_l with help com.aris.documentation.processboardhelp 10.0.18.0 type war
enhanceall copernicus_l with help com.aris.documentation.connect 10.0.18.0 type war
enhanceall abs_l with help com.aris.documentation.architect 10.0.18.0 classifier de type war
enhanceall abs_l with help com.aris.documentation.architect 10.0.18.0 classifier fr type war
enhanceall abs_l with help com.aris.documentation.architect 10.0.18.0 classifier en type war
enhanceall abs_l with help com.aris.documentation.architect 10.0.18.0 classifier ja type war
enhanceall abs_l with help com.aris.documentation.architect 10.0.18.0 classifier es type war
enhanceall abs_l with help com.aris.documentation.architect 10.0.18.0 classifier pt type war
enhanceall abs_l with help com.aris.documentation.architect 10.0.18.0 classifier ru type war
enhanceall abs_l with help com.aris.documentation.architect 10.0.18.0 classifier zh type war
enhanceall abs_l with help com.aris.documentation.architect 10.0.18.0 classifier nl type war
enhanceall arcm_l with help com.aris.documentation.arcm.arcm 10.0.18.0 type war

32
UPDATE COOKBOOK

14 Check for incompartible JDBC drivers (optional)

This action is only required if you use an external database system, such as Microsoft SQL
Server or Oracle, and you update from an ARIS version that uses an outdated JDBC driver.
This can result in runnables that will remain in the STARTING state. The listed runnables use
JDBC drivers and can be affected: adsadmin, umcadmin, copernicus, octopus, abs, hds,
apg, ecp, dashboarding, and arcm.
If you had enhanced a JDBC driver in your former ARIS installation using an ACC connand,
such as:
enhanceall abs_l with commonsClasspath path "<JDBC Driver name with version>jar"
this JDBC driver file was copied to the <ARIS installation
directory>\server\bin\work\work_abs_l\base\lib.
If you add the latest file to update your JDBC driver with the enhance ACC command, both
driver files, the obsolete file and the latest file are present. As a result, runnables will not start
correctly because the JDBC driver to be used cannot be determined.
If abs and copernicus runnables remain in the STARTING state, delete obsolete JDBC driver
files from the <ARIS installation directory>\server\bin\work\work_abs_l\base\lib.

33
UPDATE COOKBOOK

15 Start ARIS
To be able to perform the next steps, ARIS must be started. Start ARIS on all nodes with this
ACC command:
on all nodes startall
Wait for the command to complete and all runnables have started properly on all nodes. Check
this with the following ACC command:
on all nodes list
This should show all runnables in status STARTED.
If any node does not start up properly, you may have missed an essential step during the
update. Known problems are failed database accesses, indicated by umcadmin instances
with the status FAILED, and/or abs and copernicus instances stuck in the STARTING state
(page 33). If elastic runnables do not start properly (page 28), you did not repair the
elasticsearch cluster before starting the runnables.

34
UPDATE COOKBOOK

16 Adjust timestamps (ARIS document storage)

In previous ARIS versions, ARIS document storage stored timestamps, for example Creation
time and Update time, referred to documents and folders in local server time and without
any time zone information. If data was moved between ARIS Servers or if a tenant was
restored from a backup file, timestamps were likely adjusted using a wrong time offset.
Since ARIS 10 SR6, Coordinated Universal Time (UTC) is mandatory for timestamps stored
by ARIS document storage. Because time zone information in existing data is not available,
the timestamps of existing documents and folders cannot be adjusted automatically. After
the update to ARIS 10 SR6, you must manually adjust timestamps. In a Windows-based
installation with local time UTC-2, for example, use the y-admintool.bat command-line tool
and, considering UTC offset of your ARIS Servers>, enter the following:
y-admintool.bat -s https://localhost -t default adjustTimestamps -offset "-120" -u
system -p manager
If you have restored a tenant from backup file created with ARIS 10 SR5 or earlier, you must
adjust the timestamps as well.

35
UPDATE COOKBOOK

17 ARIS Aware specific topics

The predefined ARIS Aware content of the dashboarding runnable is covered by the tenant
backup.

Warning
Please note that if you restore dashboarding content, all existing dashboards, feeds and
documents stored in ARIS document storage are overwritten. You are recommended to
import ARIS Aware content only initially on a completely new ARIS Server installation.

36
UPDATE COOKBOOK

18 Update the demo databases for each tenant

You find the most current demo databases in the the downloaded ARIS installation package
(<ARIS_Installation_and_Documentation-<version>>\Content\Databases). Demo
databases contain predefined contents for demonstration purposes. With each new ARIS
version, demo databases come with updates and corrections which are required to properly
demonstrate new ARIS functionalities.
Available demo databases:
§ ARIS Connect Governance Models.adb
§ Governance Automation Models.adb
§ Performance.Ready - light.adb
§ United Motor Group.adb
In new ARIS installations, you can rely on the auto-import mechanism to import the latest
United Motor Group demo database. However, the existing demo database is not overwritten
when ARIS is updated. You must update it manually if required.
If you are not sure whether users have made changes to any of the demo databases in the
ARIS installation, rename the old databases and import the new demo databases.

37
UPDATE COOKBOOK

19 Check and upload missing fonts after updating ARIS

10.0.5 or earlier versions
Fonts define how text attribute values are displayed, such as names or descriptions in
models, tables, output files, print outs and PDF outputs. These fonts are related to languages
used in ARIS. The fonts used are taken from different sources, such as the operating system
(OS), the JRE used and the system database of the tenant.
Since ARIS version 10.0.6, Azul Zulu JRE is used as an internally used JRE. This JRE provides
no fonts anymore.
Make sure that all needed fonts are available on the operating system of the machine were by
ARIS Server is installed or in the related tenant.
§ To make fonts available server wide, use the tools and procedures related to the
operating system in use.
If you add fonts to the operating system or delete fonts, you must restart ARIS Server so
that the changes take effect.
§ To make fonts available tenant wide, you must add (page 39) the missing fonts to the
system database of each tenant.
Adding fonts to the system database has the advantages that font sets are update-prove
and there is no need restarting ARIS Server to make changes available.

38
UPDATE COOKBOOK

19.1 Add fonts

Fonts define how text attribute values are displayed, such as names or descriptions in
models, tables, output files, print outs and PDF outputs. These fonts are related to languages
used in ARIS. The fonts used are taken from different sources, such as the operating system
(OS), the JRE used and the system database of the tenant.
When ARIS Server is installed on a Windows® operating system, all fonts saved in the Fonts
folder of the operating system are available for report and model graphic generation. Linux
operating systems usually provide a smaller set of fonts.
If you use additional fonts in report scripts or in models, you must add the missing fonts to
the system database of this tenant. If a used font is missing, unreadable content appears in
report output files or incorrect line breaks show up in model graphics. This can occur, for
example, in Japanese, if the default attribute font MS UI Gothic is missing. In this case, add at
least the msgothic.ttc font file.
Warning
If ARIS Server is installed on a Linux operating system, usually no Windows® standard fonts
are available. To prevent unreadable content or incorrect line breaks, make sure to add all
used fonts from your Windows® operating system to the system database of the tenant.

Prerequisite
§ You are script administrator for this tenant.
§ You have access to the required font file (*.ttf or *.ttc).

Procedure

1. In ARIS Architect, click ARIS > Administration.

2. Click Navigation in the bar panel if the Navigation bar is not activated yet.

3. In the navigation tree, click the folder Evaluations > Fonts. All additional fonts
available in the system database of this tenant are listed. If no fonts are displayed, only
the fonts of the Windows® operating system are in use. These fonts are not displayed
here.

4. Click Add font. The dialog for file selection opens.

5. Navigate to the required ttf or ttc file.
If you want to add fonts, such as the msgothic.ttc font file from your Windows/Fonts
folder, you must first copy them to a different folder. The Windows/Fonts folder cannot
be used as source folder because the Windows® operating system does not allow direct
access.
6. Select the font files and click Open.
The fonts are added to the system database of this tenant. They are available for reports and
model graphic generation.

39
UPDATE COOKBOOK

If you want to delete a font, move the mouse pointer to the required font, right-click, and click
Delete.

40
UPDATE COOKBOOK

20 Update the system database for each tenant

The system database holds content available for all databases of a tenant, such as the ARIS
method (all model, object, connection, and symbol types), filters, templates, macros, reports,
semantic checks, and similar content.
In a new ARIS installation, the system database only contains predefined ARIS content
provided by Software AG. ARIS users can customize the system database and add new
content, for example, by defining custom method extensions, writing reports, or adding other
content to the system database.
Each tenant in your ARIS installation has a different system database. Therefore, each ARIS
tenant can have a specific set of ARIS method elements, a special set of reports, or other
content that is not shared by the tenants.
Because the default content of the system database shipped together with ARIS is updated
as part of a new ARIS version, the new version of the system database is applied to an
existing installation during an update. It only updates filters, reports, and templates shipped
with the standard product. Usually, you have your own filters and templates and do not need
updates for those that came with the standard product.
If you have an issue with any of the default reports, macros or scripts, or default Mini
workflows, or you ran a patch setup, you can update the system database. In this case, it
might also make sense to create a test tenant and only execute this command for this
tenant. Then you can export individual report scripts or other content and distribute the
required content to other tenants.
Run the updatesystemdb ACC command for all operational tenants one after another
starting with the default tenantdefault tenant. Do not execute this command for the master
tenant. Enter, for example:
invoke updatesystemdb on <abs_instance ID> tenant.name=default \
tenant.user.name=superuser tenant.user.pwd="<superuser password in default>"
invoke updatesystemdb on <abs_instance ID> tenant.name=<tenant1> \
tenant.user.name=superuser tenant.user.pwd="<superuser password in tenant1>"
invoke updatesystemdb on <abs_instance ID> tenant.name=<tenant2> \
tenant.user.name=superuser tenant.user.pwd="<superuser password in tenant2>"
If you use multiple nodes, you must prefix the invoke command with on <node name>.
Alternatively use set current node to switch to those nodes with abs runnables.
If you have more than one abs instance in your installation, you only need to update the
system database once per tenant on each instance.
If you do not update the system database for all tenants, the system will work but the latest
updates and fixes for SAG default reports, semantic checks, macros, etc. will not be available.

41
UPDATE COOKBOOK

21 Re-index modeling data for each tenant (optional)

This step is optional, but highly recommended, when updating from ARIS 10.0.9 or an older
version to an ARIS 10.0.10 service release or a newer ARIS 10 version.
By default, re-indexing is started automatically at the first login to each database. This causes
some delay and the delayed login may bother users. Therefor we recommend you to re-index
all databases on each tenant within the update maintenance window.

Warning
Do not use ARIS while databases are re-indexed using the maintainAll ACC command. Make
sure that no scheduled tasks are running, such as, backups or reports. During maintainAll
users cannot log into a database.
If you attempt an update without backing up your data, you run the risk of system outages
and/or data loss, for which Software AG assumes no responsibility.
The syntax of the ACC command is as follows:
on <node name> invoke maintainAll on <abs instance ID> tenant.name="<tenant ID>"
tenant.user.name="<user name>" tenant.user.pwd="<password>"
§ <node name>: Name of a node that contains an ABS instance.
§ <abs instance ID>: Iinstance ID of this ABS instance.
§ <tenant ID>: ID of the related tenant.
§ <user name> and <password>: User credentials of a user related to the specified tenant.
This user must have ether have the Database administrator or the Server administrator
function privilege. You can also enter the credentials of the superuser user. Make sure to
use quotes to avoid any problems with special characters.

42
UPDATE COOKBOOK

EXAMPLE (ACC)
If you want to re-index your databases contained in the mycompany tenant on node n1 that
contains the abs_m instance, and you use the system user (password is 1234ArisAdmin),
enter:
on n1 invoke maintainAll on abs_m tenant.name="mycompany"
tenant.user.name="system" tenant.user.pwd="1234ArisAdmin"

EXAMPLE (ARISSERVER> ADMINISTRATOR)

As an alternative to the maintainAll ACC command, after login to each tenant, you can use
the maintain all ARIS Server Administrator command:

INTERACTIVE MODE
server <server name>:<port> <tenant> <user> <password> maintain all

BATCH MODE
arisadm.bat -s <server name>:<port> -t <tenant> -u <user> <password> maintain all

43
UPDATE COOKBOOK

22 Configure the ARIS Agents on all nodes to use the local

repository (optional)
Because all runnables were updated at this stage, the remote repository is no longer needed,
and it can be shut down. However, if you want to configure another instance of a runnable
later, you must keep the remote repository. Otherwise, configuring a new runnable will fail,
because ARIS Agent first checks the remote repository for the most recent runnable version,
and uses its local repository only if the file in the remote repository is of the same version. If
you want to be able to configure additional runnables, you can now switch the ARIS Agents to
again only use the runnables already contained in their local repository. To do so, enter this
ACC command:
on all nodes set local.repository.only=true
Note that you can only configure additional instances of those runnables that are already in
the local repository of the related ARIS Agent in the respective version.
For example, if you have configured, an abs runnable on a node n1, after applying the setting
above, you can configure an additional abs runnable on the same node (or configure it again if
you had de-configured it). However, you cannot configure an additional abs runnable that
runs on node n2, for example, if no instance of the abs runnable exists on this node.
If the server you are using is running and the disk space is not a critical factor so that you can
leave the remote repository in place, you are recommended to leave the
local.repository.only parameter set to false. In this case, you can configure additional
instances of any runnable on any node. Only if you must shut down the remote repository due
to limited disk space after the update has completed, use the setting mentioned above.

44
UPDATE COOKBOOK

23 Update completed
If no problems have occurred yet, you have successfully updated your ARIS installation. You
can use the application, find all your data as before and use all functions and bug fixes of the
new ARIS version.

45
UPDATE COOKBOOK

24 Legal information

24.1 Documentation scope

The information provided describes the settings and features as they were at the time of
publishing. Since documentation and software are subject to different production cycles, the
description of settings and features may differ from actual settings and features. Information
about discrepancies is provided in the Release Notes that accompany the product. Please
read the Release Notes and take the information into account when installing, setting up, and
using the product.
If you want to install technical and/or business system functions without using the
consulting services provided by Software AG, you require extensive knowledge of the system
to be installed, its intended purpose, the target systems, and their various dependencies. Due
to the number of platforms and interdependent hardware and software configurations, we
can describe only specific installations. It is not possible to document all settings and
dependencies.
When you combine various technologies, please observe the manufacturers' instructions,
particularly announcements concerning releases on their Internet pages. We cannot
guarantee proper functioning and installation of approved third-party systems and do not
support them. Always follow the instructions provided in the installation manuals of the
relevant manufacturers. If you experience difficulties, please contact the relevant
manufacturer.
If you need help installing third-party systems, contact your local Software AG sales
organization. Please note that this type of manufacturer-specific or customer-specific
customization is not covered by the standard Software AG software maintenance agreement
and can be performed only on special request and agreement.

24.2 Support
If you have any questions on specific installations that you cannot perform yourself, contact
your local Software AG sales organization
(https://www.softwareag.com/corporate/company/global/offices/default.html). To get
detailed information and support, use our websites.
If you have a valid support contract, you can contact Global Support ARIS at: +800
ARISHELP. If this number is not supported by your telephone provider, please refer to our
Global Support Contact Directory.

46
UPDATE COOKBOOK

ARIS COMMUNITY
Find information, expert articles, issue resolution, videos, and communication with other ARIS
users. If you do not yet have an account, register at ARIS Community.

PRODUCT DOCUMENTATION
You can find the product documentation on our documentation website.
In addition, you can also access the cloud product documentation. Navigate to the desired
product and then, depending on your solution, go to Developer Center, User Center or
Documentation.

PRODUCT TRAINING
You can find helpful product training material on our Learning Portal.

TECH COMMUNITY
You can collaborate with Software AG experts on our Tech Community website. From here
you can, for example:
§ Browse through our vast knowledge base.
§ Ask questions and find answers in our discussion forums.
§ Get the latest Software AG news and announcements.
§ Explore our communities.
§ Go to our public GitHub and Docker repositories and discover additional Software AG
resources.

PRODUCT SUPPORT
Support for Software AG products is provided to licensed customers via our Empower Portal
(https://empower.softwareag.com/). Many services on this portal require that you have an
account. If you do not yet have one, you can request it. Once you have an account, you can,
for example:
§ Download products, updates and fixes.
§ Add product feature requests.
§ Search the Knowledge Center for technical information and tips.
§ Subscribe to early warnings and critical alerts.
§ Open and update support incidents.

47