UPF 4.1 - Configuration Builder Guide

CONFIGURATION
BUILDER GUIDE
UP FRAMEWORKTM
RELEASE 4.1
ACI WORLDWIDE, INC.

Table of contents
Document revision history .................................................................................................. 5
About this publication .......................................................................................................... 6
1 Overview ........................................................................................................................ 7
1.1 Configuration Builder features ................................................................................ 7
1.2 Basic concepts ....................................................................................................... 8
1.2.1 Environment ............................................................................................... 8
1.2.2 Configuration repository ............................................................................. 8
1.2.3 Cartridges................................................................................................... 8
1.2.4 Deployment ................................................................................................ 9
1.2.5 Edit offline .................................................................................................. 9
1.2.6 Validation ................................................................................................... 9
1.2.7 Clone configurations .................................................................................. 9
1.2.8 Menus and toolbar ................................................................................... 10
1.2.9 Status bar ................................................................................................. 10
1.2.10 Expression list option ............................................................................... 10
2 Installation and setup................................................................................................. 11

2.1 Installation prerequisites....................................................................................... 11
2.1.1 Minimum hardware requirements ............................................................ 11
2.1.2 Java™ Virtual Machine requirements...................................................... 11
2.1.3 Encryption requirements .......................................................................... 11
2.2 Install the ACI UPF End-User Application ............................................................ 11
2.3 Firewalls and port usage ...................................................................................... 12
2.4 End User Application (EUA) diagnostics .............................................................. 13
2.4.1 Diagnostics control panel ......................................................................... 14
2.4.2 Accessing diagnostics control panel ........................................................ 15
2.4.3 Actions available in the diagnostic control panel ..................................... 15
2.4.4 Sorting and filtering diagnostics list ......................................................... 15
2.4.5 Change current level of diagnostic .......................................................... 16
2.4.6 Disable all sensitive diags ........................................................................ 16
2.4.7 Reset all diags to default level ................................................................. 16
2.4.8 Filtered set ............................................................................................... 17
2.4.9 Filtered reset ............................................................................................ 17
2.4.10 Secure delete sensitive output files ......................................................... 17
2.4.11 Access control, permissions, and auditing ............................................... 18
2.4.12 Storing of changed settings ..................................................................... 19
3 Navigate Configuration Builder ................................................................................ 20

3.1 Configuration Builder components ....................................................................... 20
3.1.1 Switch workspace .................................................................................... 20
Configuration Builder Guide 2

UPF 4.1
3.1.2 Change maximum JVM Heap size........................................................... 21
3.1.3 Starting multiple instances of EUA application ........................................ 21
3.2 Script Runner ....................................................................................................... 22
3.2.1 Starting Script Runner .............................................................................. 22
3.2.2 Add trace variable .................................................................................... 24
3.3 Application components ....................................................................................... 25
3.3.1 Repository Explorer ................................................................................. 25
3.3.2 Configuration Explorer ............................................................................. 27
3.3.3 Search for information in a configuration ................................................. 28
3.3.4 User preferences ..................................................................................... 28
3.4 Change Log .......................................................................................................... 29
4 Prepare and deploy configurations .......................................................................... 30

4.1 UPF environment ................................................................................................. 30
4.1.1 Typical runtime environment configurations ............................................ 30
4.2 Add and delete UPF environments ...................................................................... 31
4.2.1 Delete UPF environments ........................................................................ 31
4.3 Build a configuration from clone ........................................................................... 32
4.4 Import and export switch configurations............................................................... 32
4.4.1 Import UPF configuration ......................................................................... 32
4.4.2 Import from a binary file ........................................................................... 33
4.4.3 Import from XML ...................................................................................... 34
4.4.4 Export a configuration .............................................................................. 34
4.5 Load a configuration ............................................................................................. 35
4.6 Edit a configuration............................................................................................... 35
4.7 Clone a configuration ........................................................................................... 35
4.8 Compare and view changes between configurations .......................................... 36
4.9 Enable advanced configuration settings .............................................................. 38
4.10 Test a UPF connection ......................................................................................... 39
4.11 Deploy configurations ........................................................................................... 39
4.11.1 When changes are applied ...................................................................... 40
4.11.2 Change oriented deployment commands ................................................ 40
4.12 Cartridge projects ................................................................................................. 41
4.12.1 Import a cartridge project ......................................................................... 41
4.12.2 Load a project .......................................................................................... 41
4.12.3 Import cartridges ...................................................................................... 42
4.12.4 Create a new cartridge............................................................................. 42
4.12.5 Upgrade cartridges .................................................................................. 42
4.12.6 Saving cartridge project ........................................................................... 42
5 Cartridges .................................................................................................................... 43
5.1 User cartridges ..................................................................................................... 43
5.1.1 Primary users ........................................................................................... 43

UPF 4.1
5.1.2 User cartridge contents ............................................................................ 43
5.1.3 Level of modularization ............................................................................ 44
5.2 Versioning ............................................................................................................ 44
5.3 Compatibility ......................................................................................................... 45
5.4 Dependencies ...................................................................................................... 45
5.5 Template components .......................................................................................... 46
5.5.1 When to build a template component entity............................................. 46
5.5.2 Building A Template Component Entity ................................................... 46
5.6 Cartridge management tasks ............................................................................... 52
5.6.1 Import cartridge into Configuration Builder .............................................. 53
5.6.2 Switch views............................................................................................. 53
5.6.3 Cartridge Editing Mode view .................................................................... 53
5.6.4 Create a new User Cartridge ................................................................... 55
5.6.5 Export cartridges ...................................................................................... 56
5.6.6 External version control systems ............................................................. 57
5.6.7 Move plugin entries to cartridge ............................................................... 57
5.6.8 Circular Dependency ............................................................................... 58
5.6.9 Deploy cartridges ..................................................................................... 61
5.6.10 Clean the configuration cartridge ............................................................. 65
5.6.11 Removing the User Cartridges................................................................. 66
5.6.12 Spring Cleaning the Database ................................................................. 66
5.6.13 Upgrade cartridges .................................................................................. 67
5.7 Update user cartridge information ........................................................................ 71
5.8 Cartridge upgrade information ............................................................................. 72
5.8.1 Upgrade mechanisms for cartridges ........................................................ 73
5.8.2 Upgrade considerations ........................................................................... 73
5.8.3 Upgrade Modes ....................................................................................... 74
5.9 User Cartridge Rollback ....................................................................................... 74

UPF 4.1
Document revision history
This document applies to the release number stated on the title page. A summary of the changes to the document
are described in the table below. If there are no changes to the document for a release, no entry is logged.
Release number Revision date Description of changes
• Added User Preferences

section
• Updated Deploy
Configurations section
4.1 December 11, 2018
• Added Configuration Projects
section
• Updated Cartridge Projects
section
Updated NetBeans version to 8.2
Configuration Builder is valid in

4.0 May 31, 2018 Windows 10
Updated Screenshots based on

new UI of Configuration Builder
5: Cartridges
3.6 December 20, 2017 Added information regarding
supported Upgrade Modes
4: Prepare and deploy

configurations
3.4
Updated importing and exporting
configurations
5: Cartridges
3.3.1
Updated screenshots

UPF 4.1
About this publication
This document explains how to install and use ACI's UPF Configuration Builder, including managing configurations
and cartridges.

UPF 4.1
1 Overview
1.1 Configuration Builder features

Configuration Builder is a rich-client application designed to simplify modifying, updating, validating, and deploying
configurations in the ACI UPF. Configuration Builder is a stand-alone client application which runs on Windows,
MacOS, and X11 windowing environments. It features a tree-style navigation pane for quick access to configuration
panels. It has a context-sensitive main panel that depends on the selected node in the navigation panel.
Configuration Builder provides a comprehensive feature set for developing and managing UPF cartridges and
configuration. There are two primary modes that the tool supports; Configuration Editing and Cartridge Editing. The
main features of Configuration Builder include:
• Importing configurations from an ACI UPF platform.

• Offline configuration review and edit support.
• Offline configuration cartridge edit support.
• Real-time configuration updates, applied to a running UPF plaform.
• Real-time cartridge deployment and activation on a running UPF platform.
• Cartridge and configuration validation.
• Context-sensitive help throughout the application.
Organizations typically have a variety of different environments (for example, development, integration, test,
staging, and production) and follow a formal process for the promotion of configurations between environments.
Configuration Builder is designed to plug into existing organizational version control processes when possible.
Configuration Builder functions in both offline and online modes. In offline mode, you can work with configurations
in a development or test environment. In online mode, you can connect to a variety of UPF environments and
download and upload configurations from and to live UPF runtimes. Administrators can validate changes to
configurations for auditing and accounting purposes.

UPF 4.1
Panels
The panels available for an instance of the ACI UPF depend on the ACI UPF configuration (that is, which
components have been installed and configured). This guide is generic and uses generic ACI UPF panels as
examples.
Field validation
When a new configuration entry is built in Configuration Builder, that configuration is constructed and attached to
the configuration tree (see Configuration explorer for more information about configuration trees).
Simple validation occurs as you enter text. Configuration Builder highlights changes to a field. When you create a
new configuration entry, a changed field is any field that no longer contains its default value. Configuration Builder
will also highlight any fields in error.
Permissions
ACI UPF enforces user access and permissions. You must authenticate when connecting to an instance of the ACI
UPF. You are assigned a user group and a user role, which determines your access rights. The license installed on
a UPF platform also impacts which configuration items are available to view and edit.
Users and User Groups are created and modified in Platform Manager. See the UPF Platform Manager Guide for
details.
1.2 Basic concepts

This section provides an overview of the basic concepts of Configuration Builder.
1.2.1 Environment
Configuration Builder supports configurations across multiple UPF platforms located on different physical hardware
installations. Configuration Builder refers to any set of hosts capable of running a UPF instance as an environment.
UPF configurations are independent of the environment, so a configuration can be migrated through development
and test environments and on to production. Typically, more rigorous testing is applied in each successive
environment before the configuration is approved for release to production.
1.2.2 Configuration repository
Configuration Builder stores its configurations in a local repository. Administrators download configurations from an
existing UPF environment. Each Configuration Builder installation can have any number of local configurations.
Administrators can edit, import, compare, merge, and deploy configurations.
Note: The configurations in the Configuration repository are stored locally on the machine in the working directory
of Configuration Builder. The location is: <workspace>/config/LocalRepos. The files have a suffix of .ser.
1.2.3 Cartridges
ACI UPF uses cartridges to support the dynamic loading and removal of functionality from a live UPF instance. A
cartridge is a packaging unit containing compiled code, configuration components, resources, and so on. A
configuration cartridge hosts the configuration parameters of the entire UPF.
Typically, changes that you make to the configuration will be stored in the configuration cartridge. It is possible to
move a configuration between the Configuration and User Cartridges. This is described in more detail in section
4.12.
UPF 4.1
1.2.4 Deployment
Deployment is the process where you deliver an amended or updated configuration to a live UPF environment.
This might be from a developer's workstation to a local development UPF or from a UPF administrator's
workstation to a production environment.
1.2.5 Edit offline
Configuration Builder maintains copies of UPF configurations in a local repository, so it does not need a direct
connection to a live UPF instance for you to manipulate a configuration. This feature allows for greater control over
how a UPF configuration changes, facilitating integration with existing enterprise change management systems and
processes.
1.2.6 Validation
Validation is the process where a UPF validates a pending configuration before activating it for live use. This
process ensures the integrity of the configuration by validating properties, references, and dependencies.
1.2.7 Clone configurations
You can use the Clone and New from clone functions to duplicate configuration entities. This increases productivity
by allowing existing configurations to be reused and preventing arduous and error prone manual entry of
configuration parameters.
The Clone function creates a copy of the configuration that is stored on the application clipboard. This configuration
is available for selection from the clipboard for subsequent New from clone operations, if the component type is the
same.
Features of the Clone and New from clone functions include:
• allow cloning of any complex component.

• allow configuration to be pasted (New from clone function) if the component type is the same.
• multiple configuration entities to be cloned at the same time.
• list the compatible cloned types when building from clones.
• support of the duplication of a configuration entity from one configuration to another.
In Configuration Builder, a configuration is stored and manipulated in a Property Context tree. Configuration Builder
uses this configuration tree in conjunction with a set of component definitions to determine what type of
configuration is allowed at any point in the tree. Therefore, Configuration Builder has no domain knowledge of the
configuration it works with, and relies entirely upon the component definitions to define the structure of the tree.
As the configuration is merely a tree, it is possible to treat any branch of the tree as a clone target. The tree can be
easily cloned and stored in Configuration Builder (in the clipboard) for later use.
Configuration Builder determines whether a cloned configuration tree is suitable for pasting at a given point.
Defined configurations can also be cloned from one UPF configuration to another. This uses a global clipboard that
allows configuration trees to be stored, regardless of whether the UPF configuration from which the configuration
entity was cloned is open or not. This means that in the clipboard, each tree should be associated with its source
UPF configuration and the user readable path in the UPF configuration.
Once the application is closed, the contents of the clipboard are cleared.

UPF 4.1
1.2.8 Menus and toolbar
ACI's Configuration Builder and Platform Manager applications follow standard Windows conventions for mouse
and keyboard usage; however, the space bar is sometimes used like the Enter key, for example, instead of clicking
the highlighted button in a dialog box.
Behavior in Linux environments follows existing Linux mouse and keyboard usage conventions.
You can use the menu bar at the top of the application to access application functionality and the Configuration
Builder hot-keys for common menu commands.
1.2.9 Status bar
The Configuration Builder status bar on the lower side of the application window displays information about events
in the application. The status bar shows after loading a UPF configuration.
1.2.10 Expression list option
The scripting widget allows multi-line scripts with validation and error messages included for expression fields. You
can configure multiple expressions to create criteria to match.
Line numbers are indicated for each expression, and errors are indicated with a red line under the expression and
an indicator in the side bar. You can edit expressions in a multi-line editor. The error message is shown when you
hover the mouse over the error indicator in the side bar.

UPF 4.1
2 Installation and setup
2.1 Installation prerequisites

The following sections explain requirements that must be met before installing the Configuration Builder
application.
2.1.1 Minimum hardware requirements
See the UPF Hardware and Software Requirements guide for information about minimum requirements.
2.1.2 Java™ Virtual Machine requirements
Configuration Builder and Platform Manager require a valid Java™ Virtual Machine (JVM) installed on the host
machine before installation can begin. JVMs are available for almost all modern desktop, workstation, and server
platforms. This section focuses on installation for Windows desktop and generic UNIX platforms.
For more information, see Sun Java at: https://www.oracle.com/java/index.html.
Note: During the installation process in Windows, you might be requested to select the path to the relevant JVM.
Choose the same version of Java used by UPF instance.
2.1.3 Encryption requirements
The UPF stores cartridges in encrypted database tables to ensure compliance with PCI DSS (that is, passwords
must not be stored in the clear). The data offload/load configuration settings might contain sensitive data like user
names and passwords. These must be protected.
Because Configuration Builder can download this sensitive data as well, adequate protection must be provided on
the Configuration Builder side. The easiest way to do this is to install End User Applications on an encrypted file
system; Configuration Builder will store the downloaded configurations in the installation directory.
2.2 Install the ACI UPF End-User Application

The AciEUAInstaller.jar is a executable JAR. On most systems, you can execute this by double-clicking the file. If
this fails to runm you can install from the command line.
1. Copy AciEUAInstaller.jar to a temporary location on your computer.

2. Open a command window and change the directory to the temporary folder where you copied the installer.
3. Type java -jar AciEUAInstaller.jar to open the installer.
Ensure that java is in your command path (or type the full path of the java executable).
EUA applications are built on top of the Netbeans Platform however, this platform is not distributed with ACI UPF.
The EUA installer can obtain the required dependencies from either an installed Netbeans IDE location or a zip file
containing the required Netbeans Platform files.
To download the Zip file:
1. Go to https://netbeans.org/downloads/.
Note: Confirm that the download page is for version 8.2. If not, go to version 8.2.
2. From the Platform drop-down on the top-right, select "OS Independent Zip".

UPF 4.1
3. Download a bundle of Netbeans IDE v8.2. (HTML5 & PHP bundle is recommended as the size is smaller and
contains necessary files).
4. Enter the location of this zip file when you install the EUA.
The ACI UPF End-User Application Installer enables you to install both Configuration Builder and Platform
Manager. The minimum requirements for the EUA are:
Minimum Hardware Requirement Operating Systems Virtualization
Processor: Intel Pentium 4, 3.0 Windows 10 (64 bit)

Ghz, Windows Server (Standard/
No Virtualization 1
Disk Storage:500 MB of free Enterprise Edition, 2008/2012, 64
space, Network enabled bit)
Memory: At least 1.4 gigabyte of

Redhat Linux v5+
free memory
See the UPF Hardware and Software Requirements for more information.
2.3 Firewalls and port usage

If there is a firewall between the UPF and Configuration Builder, the ports listed in the following table must be
opened to allow access to the UPF. When the UPF is installed, it binds to port numbers based on the UPF port
base - 3150 for the first UPF instance on first Platform. For each subsequent UPF Instance on the same Platform,
add 100 to get the correct portbase. For each subsequent Platform, add 1000 to get the correct portbase.
If the configuration of the UPF is non-standard, confirm the portbases by checking the platform definition file, which
defines which ports must be configured on the firewall and which to use when connecting from Platform Manager
and Configuration Builder. The PlatformDefinition.txt which contains this type of configuration can be found in the
UPF installation directory (for example: /home/ACI/ACI/switch/log/switch1/).
Section Description
Platform 1 - UPF Instance One:

3151, UPF Instance 2: 3251, UPF
Used by the RMI registry (for
Instance Three: 3351, and so on
UPF port base + 1 example, Configuration Builder
and Platform Manager)

UPF 4.1
RMI interface (used by
UPF port base + 4 Configuration Builder and Platform
Manager)

RMI management interface (used
UPF port base + 5 by Configuration Builder and
Platform Manager)

RMI interface (used by
UPF port base + 8 Configuration Builder for Cartridge
deploy)
Platform Manager and Configuration Builder use the Java network protocol RMI to connect to the UPF. TCP
connections to multiple ports are utilized in an RMI connection. RMI connections use SSL.
Note: For the full list of port usage, see the Firewalls and Port Usage section in the UPF Installation Guide and
UPF Pre-Installation Guide.
2.4 End User Application (EUA) diagnostics

EUA Diagnostic capabilities log diagnostic information related to EUA Tools general activities, errors, warnings,
and so on to various output files on the server or workstation where Platform Manager or Configuration Builder is
running to allow you to debug issues with the tools.
EUA Tools use a list of diagnostics, also known as diags, to emit output related to specific subsystems, functions,
or activities within EUA Tools. Each diagnostic has a name, a default level, a trigger level (that is, at what level it
starts emitting output), an indicator whether it may emit sensitive data or not, and a description. The amount of
output generated by diagnostics is controlled by changing the level of the diagnostic. Higher levels for diagnostics
emit verbose output. The output generated by diagnostics contains the information about activities happening in
EUA Tools warnings, errors generated, and so on.
The diagnostic output generated by the diags are captured into different files. These files are created in the var/logs
directory of user's workspace. A workspace is a user specific directory where files related to the user are stored.
There are three different types of EUA diagnostic output files:
UPF 4.1
• diag<yyymmdd>.txt
The diagnostic output related to general activities that are happening in EUA Tools is captured in diag files. The
diag files are retained for 10 days before they are removed from the system.
• sdiag<yyyymmddhhmm>.txt
The diagnostic output which can contain sensitive data is captured in sdiag files. These files have a timestamp
associated with them and are rolled over every hour. The sdiag files are retained for 10 days before they are
removed from the system.
• messages.log
The warnings and errors, including program exceptions, that resulted while using EUA Tools are captured in the
messages.log file. Other information generated by the Netbeans platform is also logged in this file. The file is
automatically rolled over, and up to three files are retained as messages.log, messages.log.1, and
messages.log.2.
The EUA diagnostic capabilities such as UPF diagnostic adhere to following guiding principles:
• Control - access to diagnostics is controlled. Users must be authenticated and authorized to access and
change settings related to diagnostics.
• Visibility - the system gives clear indication when sensitive data is captured in the output files. Also, any
change to the diagnostic setting is captured in the audit log, that is, who made a change, what was changed,
when was the change, and so on.
• Limited - the system assists the users to ensure that only the minimum amount of sensitive data is collected.
Sensitive data is captured in its own files, thereby making it easier to securely dispose of that sensitive data.
• Protection - output files are protected using disk encryption, file system encryption, or similar encryption
methods. The locations of all files are described in the PCI PA-DSS Implementation Guide and System Object
Security Standard documents. A Secure Delete tool is provided to securely delete output files that may contain
sensitive data. The file name clearly indicates whether sensitive data might be in the file
2.4.1 Diagnostics control panel
Platform Manager and Configuration Builder provide a diagnostics control panel that allows you to interact with the
available list of diagnostics. The panel offers following functions to interact with the diagnostics:
• View available list of diagnostics and their current level

• Change the levels of diagnostics, that is, enabling or disabling diagnostic output or varying the level of
detail/verboseness of the output
• Reset diagnostic levels to default levels
• Securely delete diagnostic files containing sensitive data
Initially, the Diagnostics Control Panel lists ui filtered diagnostics in a table. The list shows the Name, Current
Level, Default Level, Trigger Level, Enabled, Sensitive Data, and Description of diagnostics. You are only allowed
to change the value for Current Level for diagnostics. However, you must have adequate permission to change the
level of diagnostics.

UPF 4.1
2.4.2 Accessing diagnostics control panel
To access the Diagnostics Control Panel, go to View > Diagnostics or in the toolbar click Diagnostics. In
Configuration Builder, you must enter your credentials before accessing the Diagnostics Control Panel because the
Configuration Builder is an offline tool. However, you are not required to enter credentials in Platform Manager.
2.4.3 Actions available in the diagnostic control panel
In addition to listing available diagnostics, the following actions are available to customize lists and change the
settings of diagnostics.
2.4.4 Sorting and filtering diagnostics list
In the table, click a column header to sort the list of diagnostics on each column.
You can also apply a filter on each column to limit the number of diagnostics listed. Right click any column header
to open a filter dialog where you can add a column filter. Type a plain value or regular expression to filter a list of
diagnosis to display in the table. You can also clear the column filter applied.
UPF 4.1
For example:
ui.* Lists all the diagnostics with name starting with ui
*.debug.* Lists all the diagnostics whose name contains debug
ui.(debug|comp).* Lists all the diagnostics whose name starts with ui, followed by either debug or comp
2.4.5 Change current level of diagnostic
From the Diagnostics List table, go to the Current Level column and select a level to change the current level of
diagnostics. The change takes place immediately, and diagnostics will output based on the new level set.
2.4.6 Disable all sensitive diags
In the Diagnostics Tasks pane, click Disable All Sensitive Diags to disable all the sensitive diagnositcs emitting
sensitive information. This action affects all sensitive diagnostics including the ones not listed in the table.
2.4.7 Reset all diags to default level
In the Diagnostics Tasks pane, click Reset All Diags to Default Level to reset the Current Level of diagnostics to
default value. This action affects all diagnostics including the ones not listed in the table.

UPF 4.1
2.4.8 Filtered set
You can set Current Level of a group of diagnostics by filtering with the diag name filter and sensitive flag. From the
Diagnostics Tasks pane, select Filtered Set. In the dialog box, enter the diag name, specify whether to include
sensitive, normal, or all diags, and set the preferred level.
After you click Set, the current level for a group of diagnostics returned from the filter are updated to the new value.
You can use wildcard characters to create the Diag name filter. The question mark (?) matches a single character
and the asterisk (*) matches multiple characters. The diag name filter is different than the Table Column filter
described previously, where you can use normal regular expression.
2.4.9 Filtered reset
Like Filter set, you can use the diag name filter and sensitive flag to reset the Current Level of a group of
diagnostics filtered. From the Diagnostics Tasks pane, select Filtered Reset. In the dialog box, enter the Diag
name filter, specify whether to include sensitive, normal, or all diags.
After you click Reset, the current level for a group of diagnostics returned from the filter will be reset to the default
value.
2.4.10 Secure delete sensitive output files
Some of the diagnostics generate sensitive data which is captured in sensitive output files. Configuration Builder
and Platform Manager have a sensitive diag indicator on the toolbar. The indicator alerts the users whenever any
diag is emitting sensitive information to output file.
In the Diagnostics task pane, click Secure Delete Sensitive Output Files to remove all sensitive output files
securely.

UPF 4.1
2.4.11 Access control, permissions, and auditing
Changing the settings of the diagnostics is restricted to the users that have been granted permissions. In the
Configuration Builder, go to Role Configuration, to see a configuration setting where you can set appropriate level
of access to different roles. The options available are No Access, View-only Access, and Command Access.
Configuration Builder and Platform Manager check the role permission when displaying the diagnostics control
panel. If a user has No Access set to Diagnostics Access, the diagnostics control panel is not displayed to the user.
If the user has View-Only access then the diagnostics settings are shown, but the user cannot perform any actions.
The user with the Command-Access can view and perform actions. Whenever an action is performed, the
authorization check is done on the UPF system, and the action is logged in audit log.
Configuration Builder ensures that the user cannot elevate or bypass the access control check and access the
diagnostics or perform unauthorized actions.
For example, if the user has access to multiple UPF systems (for example, development and preproduction) but is
only allowed to access diagnostics in the development system, then Configuration Builder prevents the user from
accessing diagnostics while working with configuration data retrieved from preproduction.

UPF 4.1
2.4.12 Storing of changed settings
Every time a user opens or closes a UPF configuration in Configuration Builder from a UPF switch, the diagnostic
settings are reset to their default level. However, Configuration Builder persists these settings to optimize this
process. If the user opens and closes configurations of the same source or the user connects to the same switch,
then the diagnostics are not reset.
For example, consider following scenario:
• User opens a configuration imported from a development system. User turns on a sensitive diag (authenticating
and authorizing against the UPF development system). In this example, the user has been granted access for
that action in the UPF development system and therefore the action is successful.
• User closes the configuration and opens another configuration imported from a pre-production system. The
user does not have access to that diagnostics in the pre-production system.
In this scenario, Configuration Builder recognizes that the source of the configuration has changed, and it resets
the diagnostics to the default level. If the user wants to turn on the sensitive diag, then the user needs to
authenticate and authorize against the UPF preproduction system.
Note: In Configuration Builder, if the role permission of a user has changed but the user opens the configuration
(stored configuration) from the same source, then the diags settings are still restored. This is because the
Configuration Builder is an offline tool, and it does not have the current credential information. This is a known risk.

UPF 4.1
3 Navigate Configuration Builder
3.1 Configuration Builder components

The next sections describe the main components of Configuration Builder and how they are used to manage UPF
configurations and environments.
Note: After the startup is complete, you must choose certain launching parameters - a workspace and the
maximum value of Java heap size to be used for running this instance. A workspace is a folder name where the
application stores various data such as saved switch configurations, application settings, application logs, and so
on. A default workspace is selected along with a default value of Java heap size and Skip on startup is checked
by default. Click Ok to open the application with the selected workspace and the given maximum JVM heap size.
The default workspace for Configuration Builder is INSTALLED_DIRECTORY\builder_userdir.
Configuration Builder displays the main application window, which is a standard graphical user interface. It contains
a menu bar across the top of the window, a toolbar for quick access to commonly used features, Config and
Repository Explorer tabs, and a Start page. The check box on the Start page toggles the display of the Start page.
You can click links in the Start page to open the Online Help. To populate the Repository Explorer, you must import
a configuration (see Import and export switch configurations) from a running UPF instance or use a previously
exported configuration file and the option to import from file.
Note: The UPF Environments collection is populated with the nickname that is given to the configuration during the
Import Switch Configuration process.
3.1.1 Switch workspace
Switching workspaces closes the current instance and starts a new instance with the selected workspace. Save all
changes made to the current configuration before switching workspaces.
1. Go to File > Show Launcher Dialog to switch to a different workspace.
2. From the EUA Launcher: Configuration Builder dialog box, select another workspace.

UPF 4.1
3.1.2 Change maximum JVM Heap size
To change the maximum JVM Heap size of Configuration Builder, access the EUA Launcher: Configuration Builder
dialog box as described in the Switch workspace section.
3.1.3 Starting multiple instances of EUA application
To run multiple instances of the EUA application, specify different workspaces. Only one instance of the application
can run with a given workspace at a time.
Initially, a workspace can be an empty directory. After selecting the directory as workspace, the application
generates the necessary files.
When the application starts, the EUA Launcher: Configuration Builder dialog box opens with the default workspace
selected. The Skip on startup checkbox is selected by default. If Skip on startup is selected, the next time the
application starts, it will use the previously selected workspace and skip the EUA Launcher: Configuration Builder
dialog box. If an instance of the application is already running with the workspace, a warning is shown:
"Configuration Builder appears to be running within the selected workspace already. Please try another one."
After you click OK, you are prompted to select a different workspace. When you select a different workspace, it will
start another instance of the application.
If the Skip on startup checkbox is not selected, each time the application starts, it shows the EUA Launcher:
Configuration Builder dialog box from which a different instance of the application can be started by selecting a
different workspace.
You can access the Skip on startup checkbox from File > Show Launcher Dialog which opens the EUA Launcher:
Configuration Builder dialog box.

UPF 4.1
3.2 Script Runner
You can use Script Runner to write and test UPF Scripts.
The scripts run in real-time and display the results of UPF Script execution immediately.
Script Runner does not require a running instance of UPF. As such, some of the UPF script functions that require
interaction with a running platform might not operate as expected.
Some of the features of Script Runner include:
• executing UPF scripts in real-time

• the ability to save a variable state into a file for later use
• the ability to load an initial variable state from a JSON file
3.2.1 Starting Script Runner
Script Runner contains a variable window, script editor window, script editor tasks pane, and a results window. For
more information about Script Runner and its various windows and tasks, see the Online Help.
You can start Script Runner from the toolbar icon, from the context menu on the Script Widget, or from the Script
Runner Task pane.

UPF 4.1
From the toolbar, click the Script Runner icon.
On the Script Widget, you can start Script Runner from the connect menu in editor forms on Script Widgets. Script
Runner will carry the same context available to the Script Widget, which helps in auto-completing the variables
known to the widget.
From the Script Runner Tasks pane, you can click New script runner to open multiple Script Runner editor
windows.

UPF 4.1
3.2.2 Add trace variable
UPF variables are printed in UPF logs and HTML trace files at different stages of transaction processing. These
printed variables can be imported into Script Runner to use them as input for the scripts.
From Script Runner Tasks, select Add trace variable. In the dialog box, paste the copied variables. After you click
Ok, the variables are listed in Input Variables.

UPF 4.1
3.3 Application components
The main Configuration Builder application window has three major components.
• Repository Explorer – Browse the configuration repository, download and upload configurations to and from the
repository for known environments.
• Configuration Explorer - Browse through the configuration for the selected switch.
• Search Tool - Search the entire configuration to locate parameters based on criteria.
3.3.1 Repository Explorer
Use the Repository Explorer to browse through the local repository.
The repository contains copies of configurations as well as references to known environments capable of executing
a UPF instance.
Note: The Org ID field may or may not be relevant for an environment. The environment properties are:
Parameter Description

UPF 4.1
A descriptive name for the environment that is
Description created from the Nickname field when you download
a configuration.
Host The name of the host running the UPF.
Port The host port to connect to.
(On/Off) Indicates whether a user ID and password

Security Credentials
are required to connect.
(admin) Admin is the normal super user account

The user name for a secure logon to the UPF
name.
The first part of the explorer shows the top-level components of the repository, which include:
• UPF environments representing physical environments known to Configuration Builder, which allow you to
download and upload configurations.
• UPF configurations representing a directory-like structure that Configuration Builder uses to store local copies
of configurations.
• UPF deployment history from Configuration Builder to known environments. For each deployment,
Configuration Builder keeps audit information describing the changes.
When you select a configuration in the repository, Configuration Builder displays its properties.
A description for each item in the repository is displayed in the description box at the bottom of the Repository
Explorer as each item is selected or as a tool-tip as you hover over the repository items with the mouse.
3.3.1.1 UPF parameters
Parameter Description
General
Unique ID A unique number that identifies the configuration.
UPF configuration
(UPF) Name The name of the UPF.

UPF 4.1
The version number of the UPF.
Version This number is incremented each time a new
configuration is saved.
Description A description of the UPF.
A check box to enable display settings considered to

be advanced configurations.
Advanced Configuration Note: Do not select this box and change advanced
configuration settings unless instructed to do so by
ACI.
Source information
Source The source of the UPF configuration.
UPF instance host The host from which the configuration was loaded.
UPF instance port The port the UPF was listening on.
Imported by user The name of the user who imported the configuration.
Role of user The role of the user who imported the configuration.
Date/time of import The date and time the configuration was imported to
Configuration Builder (dd/mm/yyy hh:mm:ss).
3.3.2 Configuration Explorer
After a configuration is loaded, you can browse through it with the Configuration Explorer.
The tree view in Configuration Explorer shows the configuration hierarchy. You can sort the folders alphabetically
and choose whether the keyed properties are displayed in natural or case-insensitive alphabetic order. You can
right-click any sortable container on the tree to toggle the preference; only keyed properties are sortable.
The round LED indicates whether the preference is enabled and can be toggled by clicking. Toggling this property
does not happen immediately; you are notified that the preference is saved and it will take effect the next time a
configuration is opened.

UPF 4.1
3.3.2.1 Displaying configuration options
The exact structure of the configuration categories and nested entries depends on the UPF instance from which the
configuration derives and on the user's permissions. The Configuration Browser consists of three panels:
• List panel
• Details panel
• Command Button Panel
When the items to be configured represent multiple values, the Configuration Browser displays a tabulated list of
entries in the List panel. Select an entry in this list to display its details, along with a variety of action commands
relevant to that entry.
Configuration Builder normally displays data as read-only in the Configuration Browser. Double-click an entry in the
List panel or select Edit in the Command Button panel to open Configuration Builder's Configuration Editor for that
component.
3.3.2.2 Cartridge Explorer
For configurations that have been downloaded and stored in Cartridge Editing mode, an additional cartridge editing
view option is available in the Configuration Explorer. To change the view, click the View option and select from the
drop-down list. By default, configurations which contain cartridge information will display in cartridge editing mode
on opening.
Cartridge Editing mode is largely read-only. You can browse the configuration parameters stored within each
cartridge: however, all modifications are to be performed within the Configuration Editing mode.
3.3.3 Search for information in a configuration
Use the Search tool to search through the entire UPF configuration.
1. Click the Search icon on the toolbar to access the search panel. Alternatively, you can click the View menu and
then click Search.
2. Enter the item you want to search for.
Note: The Search panel offers multiple ways to filter results including the Search case-sensitive and Include
Advanced Settings checkboxes. There is also a drop-down list with the following options:
– Find results with the exact phrase (This is the default option.)
– Find results with all of the words
– Find results with at least one of the words
– Find results without the words
– Find results that are partially configured
3. Click the Search icon.
The search results will be shown for all matching entries of the currently loaded configuration. Each search result
shows the appropriate set of actions available (depending on the type of configuration item found).
3.3.4 User preferences
To access the user preferences, go to Tools > Options.

UPF 4.1
Use this window to enable or disable the following preferences in Configuration Builder.
• Enable strict validation – if enabled, strict validation will be checked by default when applying configuration
changes.
• Save form automatically – if enabled, removes the Accept button from forms and saves changes
automatically. When disabled, the Accept button is shown and the user must click the button to save their
changes.
• Enable pop-up menu on mouse over – when enabled, pop-up menus will display when the mouse hovers
over the menu button. When disabled, the menu button must be clicked to show the pop-up menu.
3.4 Change Log

The Change Log is maintained by the UPF itself and is a central repository of all changes made, for example,
configuration and dataset changes. In addition, if you have the privileges, you can revert changes, delete
scheduled changes, and update the activation date and time settings of scheduled changes.
The Configuration Builder must connect to the UPF to retrieve the Change Log information. The Platform Manager
also provides a panel for viewing the Change Log.
You must select the UPF Environment to enable the View change log menu option in the Environment menu.
Change Log tasks vary with different types of change. For scheduled changes the options are:
• Update activation date/time - change the schedule for the change.

• Delete change - delete the change before it is applied.
For activated changes, the options are:
• Revert change - if the change can be reverted, the change is undone.

• Delete change - removes this change from the log, but does not undo it.
The following details are presented for each change:

UPF 4.1
Change
Description
parameters
Change ID Each change is given a unique ID.
Created on The date the change was created.
Scheduled
The date and time the change is scheduled to be applied.
activation
User ID The ID of the user who made the change.
Activation started
The date and time the change activation started.
on
Activation finished
The date and time the change activation completed.
on
Status The status of the change.
Error message Any error message associated with the change.
4 Prepare and deploy configurations
4.1 UPF environment

Configuration Builder supports the definition of several runtime environments. Each environment represents a
physical running UPF instance that can act as the source or destination of a configuration. It is common practice to
use formal organizational change management processes to transition configurations from one environment to the
next.
For developers, the runtime environment might be a single development UPF instance running locally on their
personal desktop machine. A release manager for a mission critical production system might have a large array of
environments defined which represents the full lifecycle of a UPF configuration from system test, user acceptance
test, staging, and production.
Note: The Org ID field may or may not be relevant for an environment.
Environment names are defined during the import UPF configuration process by specifying a value in the
Nickname field.
Select one of the runtime environments to show its settings in the Properties window. When importing
configurations from the UPF or when applying configuration changes to the UPF, you must provide security
credentials for identification and authentication purposes. Descriptive text also accompanies the environment
definition.
4.1.1 Typical runtime environment configurations
The following are example runtime environments from a typical financial services organization.

UPF 4.1
Environment Description or purpose
Used for development purposes by business analysts configuring new UPF operating
parameters before test and production deployment. Also, used by developers during
the development and testing of new functionality.
• Little change management
DEVELOPMENT • Typically small scale hardware, for example, a single desktop PC with simulated
connections to external systems
• Potentially many development environments, for example, one per developer or
business analyst workstation
• Changes often, used for development and experimentation
Used for integration, system, and user acceptance testing

• Lightweight change management, designed to suit test cycles
• Typically larger scale hardware, for example, two or more servers, test and/or
TEST simulated links to external systems
• Changes less frequently than development, but still quite often to support changes
for bugs found during user acceptance tests
Formal staging environment prior to production release, used to socialize changes, with
changes run for prescribed period of time before production release.
• Formalized change management, in line with production releases
STAGING • Typically of similar scale to production hardware, with dedicated test links to
external systems
• Changes only in relation to a production release cycle
The real production system.

• Highly formalized change management
PRODUCTION
• Large scale hardware, typically dedicated operations center
4.2 Add and delete UPF environments

Add a new environment when you want to upload or download a UPF configuration from a remote UPF instance
that is not defined in your list of existing environments.
1. In the Repository Explorer tab, right-click UPF Environments.

2. Click Add UPF Environment.
A new environment is created and shown under the UPF Environments entry.
4.2.1 Delete UPF environments
In the Repository Explore tab, select an existing environment and press the Delete key on your keyboard.
Note: This only deletes the reference to the environment from the local Configuration Builder repository and does
not affect the physical environment itself.
UPF 4.1
4.3 Build a configuration from clone
You can build a new entity based on the configuration of another entity.
Before you begin, you must load the configuration you want to clone. See Load a configuration for more
information.
Cloning a configuration can be useful when building multiple endpoints with similar component types, for example,
if you want to create a new acquiring endpoint that closely resembles an existing one.
1. Click Clone in the Tasks buttonto copy the configuration to the clipboard.
Note: Any part of the configuration tree can be cloned. Multiple configuration entries can be cloned to the
configuration clipboard for later use. To view the contents of the clipboard that stores cloned information, display
the Cloned Configurations window.
A confirmation message is shown, for example, "Cloned 'Endpoints/BATCH-IN'".
2. Click New from clone in the Tasks button. This option is only available when there is an existing, compatible
type of entry in the clipboard.
The available entries are shown in the configuration clipboard.
3. Select the configuration you wish to clone and click Build.
The new endpoint will be created with the same underlying configuration as the original.
In the new endpoint, you must complete the unique fields. These include Endpoint ID, Description, Switch Port
(Route ID) parameter for routes, and so on. When cloning a channel, the Switch Port (Route ID) value is omitted,
so you must add a new value to the field.
4.4 Import and export switch configurations

The first task when using Configuration Builder is to import a configuration. You can import a switch configuration
from a running switch or from a binary file (created previously using the Export feature).
Use the Configuration Builder to export the entire UPF configuration to a binary file or to export configurations in a
Configuration Cartridge to an XML file. You can import the XML configuration to another UPF of the same version.
This option can be used to save a configuration from one environment (for example, a development environment)
and import it into another environment (for example, a test environment)
Warning: You can only import a configuration from the same UPF version; that is, a configuration exported from a
UPF version 3.2-xy can only be imported to another UPF running version 3.2-xy. Importing an incompatible version
may cause loss or corruption of configuration settings. ACI cannot guarantee the integrity or reliability of any
system configured with incompatible UPF versions. To see the version in Configuration Builder, click Repository
Explorer->UPF Environments, then right click on your Environment and select Platform Information.
You can use XML tools to make modifications to the exported XML configuration file before importing it back into
Configuration Builder. This is useful for doing bulk changes and made easier by the ability of most XML editors to
perform advanced search and find and replace operations.
4.4.1 Import UPF configuration
Use this process to import a configuration from a running UPF instance.
1. Use one of the following methods to open the Import Configuration Wizard:
– From the Configuration menu, click Import Configuration.

UPF 4.1
– In the Repository Explorer tab, under UPF environments, right-click New environment setting and select
Import Configuration.
– Press Ctrl+Shit+I.
This starts the Import UPF Configuration Wizard.
2. Complete the details for the Host, Port, Username, Password, and Nickname fields. The Nickname field must
be entered to create the Environment entry in Configuration Explorer, which is used when applying
configuration changes to a UPF. If this is not the first configuration imported, the nicknames of previously
imported UPF instances are available in the Environments drop-down list. Select an option from this list to
populate the fields with previously used values.
Note: The Org ID field may or may not be relevant for an environment. Contact your local system administrator
to determine if the Org ID must be entered on this page.
3. Click Next to continue.
The wizard displays the details of the host (UPF) being imported from, the name of the configuration file, the
version of the UPF configuration, and the progress of the import.
4. Click Next to continue once the wizard completes and displays that the UPF configuration downloaded
successfully.
The "mode" that the configuration is to be stored in is selectable using the "Editing Mode" drop-down. The
options are configuration editing and cartridge editing.
5. Complete the fields for name and the default storage location. You can use your own naming conventions and
storage locations or accept the ACI defaults. Click Next to continue.
Progress is displayed as Configuration Builder saves the configuration. When the import is complete, the wizard
will display the message, "The wizard has completed successfully!"
6. Click Finish.
The configuration you have imported will now be loaded into Configuration Builder, ready for browsing with
Configuration Explorer and editing with Configuration Editor.
4.4.2 Import from a binary file
This import creates a new configuration in Configuration Builder which is loaded when the import has successfully
completed.
Warning: You can only import a configuration from the same UPF version, that is, a configuration exported from a
may cause loss or corruption of configuration settings. ACI strongly advises against this practice and cannot
guarantee the integrity or reliability of any system configured this way. To see the version in Configuration Builder,
click Repository Explorer > UPF Environments, then right click on your Environment and select Platform
Information.
1. Close any open configuration.

2. Click File in the menu and select Import from file from the drop-down list.
3. Select the file to import and click Import from file.
The progress indicator may show for a few seconds while the configuration is imported. Once imported, and
loaded, a new entry will be created in the Repository. Also, the status bar will confirm the successful import.

UPF 4.1
4.4.3 Import from XML
When a configuration is exported to an XML file, only parts of the configuration are included in the file. For this
reason, an XML file can only be imported into an existing configuration, which updates the configuration with the
settings stored in the XML file.
Warning: You can only import a configuration from the same UPF version; that is, a configuration exported from
may cause loss or corruption of configuration settings. ACI cannot guarantee the integrity or reliability of any
system configured with incompatible UPF versions. To see the version in Configuration Builder, click Repository
Explorer->UPF Environments, then right click on your Environment and select Platform Information.
1. With a configuration already loaded, from the menu select Configuration > Import from XML.
2. Go to XML file to import, select it, and click Import from XML.
A warning message states that your existing configuration will be overwritten.
3. Click Yes to overwrite your configuration or No to stop the import from overwriting your configuration.
The status bar confirms a successful import.
4.4.4 Export a configuration
The configuration must be loaded before it can be exported.
1. In the menu, select Configuration > Export to XML.

2. Name the file and select where to store it.
3. Click Export to XML to complete the export.
The success of the export is confirmed in the status bar.
4.4.4.1 Export a binary file
You can export a UPF configuration to a binary file, which can be imported to another UPF.
A configuration must be loaded to enable the Export to file function.
Warning: You can only import a configuration from the same UPF version; that is, a configuration exported from
may cause loss or corruption of configuration settings. ACI strongly advises against this practice and cannot
guarantee the integrity or reliability of any system configured this way.
1. In the menu, select File > Export to file.

2. Name the file and select where to store it.
3. Click Export to file to complete the export. The success will be confirmed in the status bar.
4.4.4.2 Export Cartridge
You can export a cartridge to jar file or a zip file which contains the cartridge and all its dependencies.
A configuration must be loaded in cartridge editing mode to enable the Export to cartridge function.
As a cartridge contains compatibility information, it will only import successfully into a configuration with which it is
compatible.

UPF 4.1
1. Switch the Configuration Explorer to the cartridge editing view.
2. Right-click a cartridge and select Export Cartridge.
3. Follow the prompts in the wizard to export to either jar or zip.
4.5 Load a configuration

Load a configuration in the Repository Explorer
1. Use one of the following methods to load a configuration:

– Click File in the toolbar and select Load Configuration.
– Right-click a configuration in the Repository Explorer window and select Load Configuration.
– Press Ctrl+Shift+O on the keyboard.
A Loading status bar will appear, and when complete, the icon next to the configuration in the repository viewer
will change to a folder. The status bar at the bottom of the Configuration Builder screen will confirm that the UPF
is loaded.
4.6 Edit a configuration

Use the Configuration Editor panel to edit simple parameters, such as Endpoint and Description, as well as
configuration parameters that are edited in their own sub-editors (for example, Meta Configuration, Message
Protocol, and so on).
1. In Configuration Explorer, select the item you want to edit.

A Configuration Editor panel opens. Mandatory parameters are in bold, such as Endpoint ID. Use the tasks
section in Meta Configuration to edit or clone the configuration.
2. Edit each field as needed.
3. Click Validate to check that the changes are valid, or click Accept and Close to save the changes.
Note: These changes apply to the local copy of the configuration only. Changes will not affect an active UPF
instance until you deploy the configuration to an environment (see "Load a configuration").
4.7 Clone a configuration

Configuration Builder supports the duplication of configuration entities with the Clone and Build from clone
functions. With the focus on the ability for users to quickly and easily configure new endpoints, productivity benefits
from allowing existing configurations to be reused and preventing arduous and error prone manual entry of
configuration parameters.
The Clone function creates a copy of the cloned configuration that is stored on the application clipboard. This
configuration is then available for selection from the clipboard for subsequent Build from clone operations, if the
component type is the same.
Features of the Clone and Build from clone functions include:
• Allow cloning of any complex component

• Only allow configuration to be pasted (New from clone function) if the component type is the same
• Provide an ability for multiple configuration entities to be cloned at the same time

UPF 4.1
• Only list compatible cloned types when building from clones
• Support of the duplication of a configuration entity from one configuration to another
Within Configuration Builder, configuration is stored and manipulated in a Property Context tree. Configuration
Builder uses this configuration tree in conjunction with a set of component definitions to determine what type of
configuration is allowed at any point in the tree. This means that Configuration Builder has no domain knowledge of
the configuration it works with and relies entirely upon the component definitions to define the structure of the tree.
As the configuration is merely a tree, it is possible to treat any branch of the tree as a copy (clone) target. The tree
can be easily cloned and stored within Configuration Builder (in the clipboard) for later use.
Configuration Builder determines whether a copied configuration tree is suitable for pasting at a given point.
Defined configurations can also be copied from one UPF configuration to another. This uses a global clipboard that
allows configuration trees to be stored, regardless of whether the UPF configuration from which the configuration
entity was copied is open or not. This means that within the clipboard, each tree should be associated with its
source UPF configuration and the user readable path within the UPF configuration.
Once the application is closed, the contents of the clipboard are cleared. Therefore, when Configuration Builder is
opened, the clipboard will be clean and uncluttered.
4.8 Compare and view changes between configurations

You can compare and view changes between the currently loaded configuration and another configuration in the
repository.
1. Load the configuration you want to compare.

2. Use one of the following methods to open the View Changes window:
– Right-click the unopened configuration to compare and click Compare and view changes.
– Select the unloaded configuration, click Configuration in the menu bar, and click Compare and view
changes.
– Select the unloaded configuration and press Ctrl+Shift+D.
Configuration Builder will start the Compare and View Configuration changes Wizard. The wizard first compares
two configurations and lists all the changes related to Entity Models if there are any. You can select all changes,
or a subset of changes, to import into the current configuration.

UPF 4.1
3. You right-click the column heading to access the row filter on the Changes Panel. Enter the filter in the drop-
down list, which includes a combination field of text and a history of previously used filters.
The history is displayed when you click the arrow. The Clear filter: none button is enabled when you have an
active filter. The regular expression check box can be selected to specify patterns.
You can also filter list of changes based on type of changes. The filter is visible at the top of changes panel. Only
the changes related to selected change types are displayed in changes panel. For example, if you do not want
remove operations to be listed, then clearing the Deleted checkbox filters out all the changes related to remove
operations from the list.
4. Click Next to display the list of other configuration related changes.

UPF 4.1
The wizard validates the user selected configuration changes and imports the changes to current configuration.
If any incompatible changes are identified, the wizard notifies the user.
The changes are imported only to the local copy of the configuration. These changes can then be applied to a
running UPF environment, if necessary.
4.9 Enable advanced configuration settings

You can enable Advanced Configuration settings to provide additional options.
Note: You must discuss specific Advanced Configuration options with ACI before changing any advanced
configuration settings. Do not use the Advanced Configuration option unless instructed to do so by ACI.
1. Click the Repository Explorer tab.

2. The configuration must be closed to enable Advanced Configuration settings. If the configuration is open, right-
click the configuration under UPF Configurations and select Close Configuration. Alternatively, you can press
Ctrl+Shift+C.
In the confirmation box, click Yes to close the configuration or No to cancel.
3. Right-click on the configuration again and click Properties.
4. In the Properties window, click the box for Advanced Configuration.

UPF 4.1
An example of advanced configuration settings is Read Only Advanced Configuration. In some Configuration
Builder panels, a Read-Only configuration moves information that is not modifiable or not useful in daily
operations to the Advanced Configuration area of the panel.
Warning: Changing some Advanced Configuration settings may result in transactions being rejected or
processed incorrectly. Always discuss Advanced Configuration options with ACI before changing any of these
settings.
Details of Advanced Configuration options are provided in other documents, including the UPF Configuration
Builder Toolkit Guide, EFT User Reference, and sometimes in project-specific documents, depending on the
customer project requirement.
4.10 Test a UPF connection

Test a UPF instance to ensure it is running and available to work with Configuration Builder.
1. Click the Repository Explorer window.

2. Right-click an environment.
3. Click Platform Information. Alternatively, you can select the environment and press Ctrl+Shift+T.
4. In the Credentials window, enter your user name and password.
Note: The Org ID field may or may not be relevant for an environment. You must contact your local system
administrator to determine if the Org ID is necessary.
If the connection is available and the test is successful, Configuration Builder presents an information screen with
the name of the configuration that is currently running on that environment.
4.11 Deploy configurations

Deployment is the process whereby Configuration Builder sends configuration changes to a live UPF instance.
After making changes to a configuration, the changes only exist in the local copy. You must apply the changes to a
known environment to deploy the changes to a live UPF instance.
1. Load the configuration that you want to change and make the desired changes.
2. In the menu bar, select Configuration > Apply Config Changes. Alternatively, you can press
Ctrl+Shift+A.
The Apply Configuration Change Wizard opens.
3. In the Review changes step of the wizard, select the check boxes to the left of the changes as needed. To find
out more information about the change, click the change to highlight it, then click View Details. Click Next to
continue.
4. Select the Validate without apply checkbox to indicate that the selected changes need to be validated only. This
is useful when user wants to perform validation on changes without applying them in situation when the switch
is down or inaccessible.
5. Select the Strict validation checkbox to show all validation errors from both the original and updated
configuration. If the checkbox is not selected, validation will only be performed on the updated configuration
and will not show errors from the original configuration.
6. In the Select target step, enter the required username and password and other fields as needed. The Detailed
description will be visible in the Change Log. The Org ID field may or may not be relevant for an environment.
Contact your local system administrator to determine if the Org ID must be entered.
Optional: Click Test connection next to the password field to test the connection to the live UPF instance.
UPF 4.1
Note: Select target step is skipped if the Validate without apply checkbox is selected in earlier step.
7. The Validate selection step confirms that the changes are compatible. Incompatible changes are highlighted. If
necessary, deselect a change to omit it.
Note: Changes that are invalid can be amended and then applied again.
8. Click Next to continue to the Changes complete screen.
The changes are validated and applied. If there are any validation errors, a notification screen will describe the
errors so you can correct and reapply the changes. An error message will be displayed if a problem occurs such as
a connection error or invalid change error.
Note: Configuration Builder performs a configuration value reference check to ensure that reference configuration
parameters (through ConfigValueDefinition) may not be deleted without deleting the references, too. This check
occurs when you click Apply configuration changes but will also occur if you select a subset of changes on the
Apply Config Changes page. The Apply changes button on the Apply Config Changes page will change to Review
errors if errors are detected. After you click this button, a page opens with a list of paths containing a reference to a
deleted configuration item. The change is never applied to the UPF if this page is shown.
4.11.1 When changes are applied
Some changes made to the UPF are applied immediately while others require a restart.
Changes made through Configuration Builder are effective immediately when the change is applied to the UPF,
although the change may take up to 60 seconds to be reflected in Platform Manager.
In rare circumstances, typically as the result of a configuration merge, UPF may determine that the changes being
applied cannot be safely applied in real-time. In these instances, the change will be accepted but not activated. An
alarm is raised and the platform needs to be restarted for the changes to take effect.
Changes made in Platform Manager to user and user groups are also affected immediately, which may result in
termination of active user sessions if they are the target of modifications. This is to ensure that modifications to
user permissions are not dependent on that user logging off and back on again.
4.11.1.1 Deployment history
Configuration Builder keeps a local deployment history of all configuration changes applied. This is in addition to
the Change Log which is maintained by the UPF, and it is a consolidated log of all changes made by any user.
4.11.2 Change oriented deployment commands
The following change-related commands can be executed in Platform Manager in the Change Log panel:
• Change Activation Time - modifies the activation date and time for a scheduled change
• Revert - reverts a change
• Remove - removes a change from the Change Log

UPF 4.1
4.12 Cartridge projects
Cartridge projects are Apache Maven projects for developing UPF cartridges. A cartridge project encloses cartridge
configurations as files in an expanded directory structure. This file-based representation allows the configuration
files to be version controlled and multiple users to collaboratively make changes to the configuration.
Using cartridge projects allow users to configure different tools to support various project functionalities like project
compilation, dependency management, artefact generation, validation, packaging, deploying etc. ACI provides
plugins and project archetypes for Maven which streamline the build process and add validation for the generated
cartridges (available from version 4.1).
The Development Methodology Guide describes, in detail;
• the project structure
• tools that can be used for the cartridge development process
• lists of artifacts and plugins necessary to create and build projects and their locations
• steps to create a project
Note: After the project is created with the steps mentioned in the Development Methodology Guide, the project
must be built with Maven before loading the project into the Configuration Builder.
4.12.1 Import a cartridge project
To import a cartridge project, go to the File menu and select Load Project. Locate the directory of the project to be
imported and select the directory of the project or the project.xml file, itself. After the project is imported, the most
recently opened projects will be stored under UPF Projects in the Repository Explorer with the latest imported
project shown first.
4.12.2 Load a project
To load a project, right click a project that has been previously imported from the Repository Explorer under UPF
Projects, then select Load Configuration or click the load configuration button in the toolbar (open book icon).

UPF 4.1
4.12.3 Import cartridges
Importing cartridges into a project works like importing cartridges into a configuration. Change to Cartridge Editing
mode. Then, right-click User Cartridges and select Import User Cartridge. The panel displays a drop-down
menu with the available cartridges that are referenced in the project’s POM file but not the project.xml file. To
import a cartridge that isn’t in the drop-down list, you must add the dependency to the project’s POM file and
rebuild the project.
Alternatively, click Browse and locate the cartridge file to import. If you import cartridges this way, the location of
the cartridge file will be stored in the project file as a path relative to your machine, which means the project is no
longer portable between different systems.
4.12.4 Create a new cartridge
To create a new cartridge, right-click User Cartridges and select Create New. Enter the ID, version, compatibility,
and description fields and click the Browse button below Project Details to specify where you would like the new
cartridge to be stored. The cartridge reference will be added to the project file with its location path relative to your
system.
4.12.5 Upgrade cartridges
To upgrade a cartridge in a project, right-click the cartridge to upgrade and select Upgrade Cartridge. A newer
version of the cartridge must be referenced in the project’s POM file before upgrading. If the Upgrade User
Cartridge Wizard doesn’t allow you to continue with the upgrade, update the dependency of the cartridge to a
newer version in the POM file and rebuild the project.
4.12.6 Saving cartridge project
Click Save to save the changes made to cartridge projects. This saves the cartridge configuration back to the
filesystem.

UPF 4.1
5 Cartridges
5.1 User cartridges

UPF uses cartridges to modularize the system. UPF offers a component model that is used to assemble
components (which are packaged into cartridges). Components can be considered the building blocks of the
applications which are run within UPF. Plug-ins are the instantiation and configuration of these components. When
the UPF starts up, the top-level cartridge (known as configuration cartridge) is used to load all dependent cartridges
(and their plug-ins and component definitions). At a high level the following steps are performed:
• Determine the active configuration cartridge version

• Determine the required cartridges based on the list of dependent cartridges
• Load each cartridge and construct a global plug-in tree
The configuration cartridge is also responsible for storing changed plug-ins, that is, the plug-ins in the dependent
cartridges are constant (but can be redefined). For example, if you add a new RDBMS entity, then the impacted
plug-in (in this example the entity model plug-in) is copied to the configuration cartridge.
On a fresh install of UPF, the configuration cartridge is empty and the plug-in tree contains only those plug-ins that
were preconfigured in the dependent cartridges. As changes are made to the system, those changed plug-ins are
copied to the configuration cartridge.
Configuration Builder is used to perform configuration changes to the system. Many components expose properties
that can be viewed and edited in real-time using Configuration Builder.
User cartridges allow an implementation team to package configuration parameters or plug-ins as a single cartridge
artifact. These cartridges can be inserted as dependencies into the configuration cartridge allowing for better
portability of configuration between systems.
5.1.1 Primary users
Working with user cartridges is a relatively minor part of the configuration of a new project. Typically, the team
responsible for configuring a solution uses Configuration Builder in the standard configuration editing mode and
pushes their changes to a master system. The role of maintaining the User Cartridge artifacts generally fall to a
configuration manager or managers who maintain the configurations on the master system.
At regular intervals throughout the implementation phase of a project, the configuration manager may decide to
migrate the tested configuration from the master UPF instance or instances into User Cartridges. The frequency at
which new or updated user cartridges are generated depends on the scope, modularity, and complexity of the
project.
5.1.2 User cartridge contents
Typically, the following items go into a user cartridge:
• Entity models, for example, template components, RDBMS entities, component entities
• Plug-ins (instances) based on the component entities configured in entity models
• File IDs, Audit and alarm definitions (instances) used by endpoints and sessions
Component instances, such as endpoints and sessions, are not necessarily packaged inside user cartridges.
Endpoints and sessions typically contain environment specific configuration such as the hostnames of external
systems in the case of a channel on an endpoint. It is recommended that these instances be created by the user

UPF 4.1
who installs a user cartridge into a given instance of UPF. Alternatively, a sample configuration cartridge can be
used to distribute preconfigured component instances.
5.1.3 Level of modularization
The best approach for packaging configuration into cartridges depends on several factors, such as the granularity
of the upgrading of cartridges, the number of reusable components, number of collaborating team members, and
so on.
Depending on those factors, a single user cartridge containing all new customizations may be all that is necessary,
or many smaller cartridges may be required.
5.2 Versioning
The author of the user freely determines the version. However, some suggested practices for versioning of user
cartridges are:
• Final versions should be major.minor, for example, "1.0", "1.5"

• Work in progress versions can have snapshot label, for example, "1.0-20140506-SNAPSHOT" or a
milestone/release candidate label (such as "1.0-M4" or "1.0-RC5"). This avoids bumping up the version number
during the development/testing phase of a user cartridge.
Where necessary UPF updates the revision number of a user cartridge on deploy. In practice this means that
deploying a user cartridge with the version '1.0-M3' when it has already been stored results in two versions of the
cartridge being stored in the UPF database:
• '1.0-M3.000': The initial revision

• '1.0-M3.001': The new revision
This allows a project team to deploy multiple copies of the same cartridge to UPF without being concerned about
overwriting a working cartridge. When deploying user cartridges, remember the following:
• The database capacity decreases as each revision of a user cartridge will take up some space.
• The UPF managed revision of a user cartridge increments each time. UPF does not presume to know whether
a revision being deployed is older or newer than an already active revision. Management of the deployment of
user cartridges is left to the processes followed by the configuration manager on a given project.
UPF supports several different, well known tags or identifiers for cartridges. They include designations, which
resolve in the following order:
• alpha or a
• beta or b
• milestone or m
• rc (short for release candidate)
• snapshot
• ga or final (or nothing, indicating a final release)
• sp (short for service pack)
More '0' characters within a version identifier are considered equivalent. A few examples of versions and whether
they are considered equivalent are:

UPF 4.1
• 1.0 = 1.0.0.0
• 1.0-alpha4 > 1.0-alpha1
• 3.2-0-GA = 3.2.0
• 2.4-SP1 > 2.4
5.3 Compatibility
In addition to assigning the version of a User Cartridge, you must assign a compatibility version to the cartridge.
The purpose of this field is to define the range of cartridges with which the specified release is compatible. The
compatibility version indicates the oldest version of the same cartridge which the current version supports, that is
its backwards compatibility.
Configuration Builder often does not have all the information available to automatically determine the backwards
compatibility of a specified cartridge, so setting the version is left to the configuration manager.
When loading a configuration, UPF allows a newer cartridge to substitute an existing cartridge provided the version
requested falls within the compatibility range of the cartridge that has already been loaded. UPF never loads two
versions of the same cartridge simultaneously, so be aware of potential backwards incompatible changes when
releasing updated versions of cartridges.
A non-exhaustive list of backward incompatible changes to avoid includes:
• Removal of an entity or entity model

• Removal of properties on an entity
• Addition of a new mandatory property on an entity
• Removal of component entity plugin
• Reduction in the size of an RDBMS Entity property
• Change in the type of an RDBMS Entity property.
• Addition of validation to an existing entity property
5.4 Dependencies
Each cartridge that is loaded by UPF may have a dependency on other cartridges which must also be loaded for
the full configuration to be loaded successfully. The Configuration Cartridge includes all the dependencies of a
specified configuration and the version of each cartridge which should be loaded.
A User Cartridge will also contain dependencies. There are several ways that a cartridge may be dependent on
another, including:
• Direct
• Indirect
• Dynamic
A direct dependency is introduced to a cartridge when one cartridge uses a configuration defined in another.
Adding an entity model to a User Cartridge introduces a direct dependency between the User Cartridge and the
System cartridges which define the entity model components.

UPF 4.1
It is possible to have direct dependencies between a User Cartridge and System cartridges and direct
dependencies between a User Cartridge and another User Cartridge. An example of this would include the
definition of a plug-in component entity defining a new type of configuration such as "Countries". A second User
Cartridge may be used to store all the country instances.
An indirect dependency between cartridges may arise if one cartridge contains a configuration reference to another
type of configuration. Consider a User Cartridge which defines an entity for storing institution information. If you
configured one of the fields within the entity "Country" to provide a drop-down list of the countries defined in a
separate User Cartridge, then you have introduced an indirect reference between the cartridges.
A dynamic dependency is a dependency between cartridges where one cartridge uses one of the types defined by
another cartridge. An example of a dynamic dependency is the use of an RDBMS Entity operation within a UPF
Script.
Configuration Builder can determine both direct and indirect cartridge dependencies and updates the dependencies
of cartridges as necessary. Configuration Builder will also search for, and add cartridge dependencies, for dynamic
dependencies such as those defined by complex validation types and references in UP Scripts where possible. Be
careful when working with cartridges to design their solutions in such a way as to avoid circular dependencies.
Configuration Builder detects and prevents user action that will introduce a circular dependency between two
distinct cartridges as UPF will be unable to load and activate the configuration successfully. A more detailed
description on circular dependencies can be found in section 5.6.8 below.
5.5 Template components

A template component is a type of component based entity. It differs from a standard component entity in that it
allows you to create a template of one of the built-in types within UPF. Common use cases for template component
include sessions and endpoints.
The resulting component generated by Entity Builder exposes only a subset of the properties configured within the
entity. As a result, template components are a great way to encapsulate the internals of a component while still
retaining visibility into the internal structure. For example, you can create a template component for an endpoint
that only exposes the essential parameters including; the endpoint ID, security configuration, custom parameters
and channel configuration. These are typically environmental parameters that would be configured per instance of
an endpoint, whereas the configuration encapsulated within the component template entity would be shared.
This is a good compromise as the initial configuration of an endpoint instance is greatly reduced, yet the internal
structure is available for analysis that is to be performed during tracing and debugging of an endpoint.
As multiple instances of a template component share a common structure, a benefit of components defined in this
way is that a change made to the template component entity will be reflected in each of the instances of that
component in real-time when changes are applied.
5.5.1 When to build a template component entity
As previously mentioned, endpoints and sessions are the types of configuration that are best suited for converting
into a template component entity. This is especially true if you consider that this enables you to package a
configuration, such as an endpoint configuration in a user cartridge for distribution between different environments.
Typically, you would create the template entities toward the end of a project when the component to be converted
into a template component entity is complete and fully tested.
5.5.2 Building A Template Component Entity
A template component entity is essentially the encapsulation of another type of component.

UPF 4.1
1. After the implementation and testing of the base component, clone it. For more information about the Clone
feature see Cloning configuration.
2. In the configuration, go to the Entity Model within which the new template component entity should be logically
grouped. It may make sense to create a new entity model. The scope and complexity of the project determines
whether the new entity is best housed alongside other entities such as RDBMS and Component plug-in entities
or within its own model alongside other template entity artifacts. Consider creating a new entity model to house
simulation endpoints, for example, since this would allow project deliverable artifacts to be package into a
different user cartridge to the simulation and testing artifacts.
3. In the Build new Entities task pane, select Build from Cloned Configuration.
You will use the wizard to convert the previously cloned configuration entry into a template component entity.
4. Select the cloned configuration entry.

UPF 4.1
5. Select the test-endpoint endpoint and click Next.
6. Select which parts of the configuration are exposed as formal parameters for configuration. Use the tree to
select the configuration entries, which will load a form where the parameter itself is defined. For an endpoint,
the typical parameters include:
– Endpoint ID
– Custom Parameters (or perhaps just the value field of named parameters)
– Security Configuration
– Channels
In many instances the generated parameter definition is suitable, although you should review all values and
modify them if necessary.
The following screenshot shows the change parameter creation form with the changes already made.

UPF 4.1
7. After all the changes have been made, click Accept below the table as shown in the screenshot above. This
saves the new parameter, adds it to the parameter list, clears the form, and updates the tree to indicate that the
node selected is now a parameter reference.
8. Click Finish at the lower right of the wizard to construct the new template component entity and display it in the
entities table. You must populate the following fields:
– ID
– Display Name
– Description
These fields determine the information used to reference and describe the newly constructed endpoint definition.

UPF 4.1
This form shows the parameters defined in the wizard and the Template Configuration entry. The template
configuration is where the configuration of the entire endpoint is encapsulated.
On saving the newly created Template Component, entity build runs its artifact generation and produces a new
component definition for the My Test Endpoint. This endpoint is then available to build within the "Build " menu
on the Endpoint panel.

UPF 4.1
Note: The items in the "Build" menu are loaded at panel initialization, so the Endpoint panel only displays the
newly created endpoint following entity builder artifact generation if the panel is reopened.
If you build this endpoint, you can see that the configuration form created shows only the defined parameters.
As already discussed, the remainder of the parameters have been encapsulated in the Template Component
configuration entry in the My Test Endpoint Template Component entity.

UPF 4.1
9. Select Edit to see the internal configuration of the new endpoint. The panel looks like a normal endpoint
configuration panel, and you can make small tweaks to the configuration of an endpoint template. The main
difference is that primitive fields contain a button next to them allowing the user to toggle whether the field has
a static value or a parameter reference.
The Endpoint Id field is a parameter reference to the parameter created earlier. The Description field is a normal
free form text field.
5.6 Cartridge management tasks

You must understand numerous tasks to configure and work with User Cartridges. Each of the major tasks is
described next.
Use the standard Configuration Explorer in the Configuration Builder to edit configurations in the same way that
you would do it when the user is not working with a cartridge. The result is that all the configuration entries which

UPF 4.1
are modified are migrated to the Configuration Cartridge which is obvious when switching from the standard
configuration editing tree view to the Cartridge view within the Configuration Explorer. Importing into Configuration
Builder.
5.6.1 Import cartridge into Configuration Builder
First, to make changes to the cartridges stored in a UPF configuration you must import the cartridge hierarchy from
a running platform. Once the configuration is loaded into Configuration Builder, we need to switch to Cartridge
Editing Mode.
In Cartridge Editing mode, right-click User Cartridge and select Import User Cartridge, to import a cartridge into
an opened configuration,
You can select either a user cartridge archive or the folder containing cartridge.xml file (if the cartridge was
extracted or exported to Directory), and it will import the cartridges as appropriate.
The Import wizard does not perform a cartridge upgrade and, as such, cannot be used if the cartridge being
imported already exists in the configuration.
5.6.2 Switch views
In the Configuration Explorer, select the desired editing mode to switch between the configuration editing and
cartridge editing mode.
Configuration Editing Mode presents configuration in the standard configuration editor tree. This mode allows
configuration modification.
Cartridge Editing Mode presents configuration as cartridge hierarchy. This mode allows performing actions related
to cartridges.
5.6.3 Cartridge Editing Mode view
The Cartridge Editing Mode presents the cartridge hierarchy within the current configuration. There is a tree
containing three major categories:
• Configuration Cartridge
• User Cartridges
• System Cartridges

UPF 4.1
When you make configuration modification in Configuration Builder, you will typically modify the configuration
cartridge. It contains all the installation specific configuration, such as endpoints with all their environment specific
host address and port configurations. The modified configuration entries are copied from their source cartridge into
the configuration cartridge. When there are duplicate configuration entry keys at the top level, the one within the
configuration cartridge (or cartridge closest to the configuration cartridge within the cartridge hierarchy) is loaded
and activated within UPF.
The User Cartridges category contains all the remaining user configurable cartridges within the active
configuration.
System Cartridges are shown for illustration purposes only. You cannot perform any actions on a System
Cartridge; however, you can browse the configuration stored in them.
Within each of the categories is a list of cartridges of that type. The order of the cartridges is such that a cartridge
may only depend on cartridges listed above it.
Within each of the cartridge nodes is a list of each of the configuration items available within that cartridge.
When selecting a category or a cartridge, Configuration Builder loads a document showing a summary of the
cartridge metadata and its dependencies.

UPF 4.1
5.6.4 Create a new User Cartridge
1. Right-click the User Cartridges node and select Create New to create a User Cartridge.
2. Use the wizard to configure the metadata describing the cartridge:

– Id: The cartridge name
– Version: The cartridge version which may include text such as RC for a release candidate

UPF 4.1
– Compatibility: A version of the cartridge with the same name with which this cartridge is deemed to be
backwards compatible
– Description: A brief description of the purpose of the cartridge
After the form is complete and validated, Configuration Builder creates the new cartridge and inserts a reference
to it into the currently loaded configuration cartridge.
The newly created cartridge has been inserted into the User Cartridges section of the Cartridge Explorer tree.
5.6.5 Export cartridges
Configuration Builder supports two different ways of exporting User Cartridges, Archive (Jar, Zip) and Directory.
The archive file format produces either a jar or zip file depending on whether the Include Dependent Cartridges
checkbox is selected or not. You can specify the filename and directory to where the cartridges are exported.
The jar file format is the native format for a user cartridge. Contained within are several xml documents with the
cartridge metadata and its configuration.
The zip format is a Configuration Builder export/import format which allows multiple cartridges to be exported into a
single artifact. Within the zip archive is the exported user cartridge and each of its user cartridge dependencies.
The benefit of the Zip archive is that a cartridge can be distributed and imported using a single file. This is useful
when sending a cartridge to a team member using a different UPF installation.

UPF 4.1
The Directory format is a Configuration Builder export/import format which enables cartridges to be exported as a
list of XML files and folders. You can use Include Dependent Cartridge checkbox to export a single cartridge with
dependent cartridges. You can specify the location for the cartridge and its dependencies to write the cartridge
files.
To export a cartridge in either format, right-click the desired User Cartridge in the Cartridge Explorer tree and select
Export Cartridge.
Note that you can use the operational scripts installed alongside UPF to export a cartridge from UPF. You can
download a specified cartridge configuration, user, or system cartridge from a running UPF. See the Cartridge
Management section of the UPF Operations Guide for more information.
5.6.6 External version control systems
Often, you will want to store work in progress user cartridges in a version control system such as Subversion or Git.
Version control systems typically work better with text-based files rather than the binary jars. Hence, it is
recommended that you export the cartridge in Directory Format or if you export it to jar, then you must extract the
cartridge and store the XML content in the version control system.
The User Cartridge jar contains:
• cartridge.xml
• multiple <plugin-name>.xml files
• multiple <plugin-name> directories
• multiple <plugin-name>/<plugin-id>.xml files
The cartridge.xml file contains the metadata associated with the cartridge including the name, version, compatibility
description, and each of the dependencies. The other XML files are names based on the type of configuration they
include and are referenced within the cartridge.xml.
To reconstruct a user cartridge from its constituent parts, re-jar all the files into a single jar.
5.6.7 Move plugin entries to cartridge
Since all configuration editing is performed in the Configuration Editing tree view, all the plugin entry changes made
within Configuration Builder are stored within the Configuration Cartridge.

UPF 4.1
Therefore, moving plugin entries is a common task performed by the Configuration Manager role.
Within each of the cartridge nodes in the Cartridge Explorer tree is a list of the plugin entries within the cartridge.
Typically, plugin entries under user cartridges or configuration cartridge can be migrated or moved to a different
cartridge.
To move plugin entries to a user/configuration cartridge, right-click on the cartridge and select Move Plugin
Entries to Cartridge. This example moves plugin entries from other user cartridges and configuration cartridge to
a new User Cartridge, "My New Cartridge".
In the tree view, you can select plugins from other cartridges to be moved to the target cartridge.
After selecting plugin entries to be moved, the Configuration Builder attempts to modify the source cartridges and
the target cartridge. The process of rebuilding and validating the impacted cartridges may take some time as each
cartridge is validated, its dependencies are updated to add new cartridge dependencies and to remove any that are
no longer required. Sometimes, moving the plugin entries may not be allowed as it would result in a circular
dependency between the cartridges within the configuration. If a circular dependency occurs, Configuration Builder
will alert you. Click the link to view details about the circular dependency. When you close the Move Plugin entries
dialog, the cartridges return to their initial state.
Once completed, the moved plugin entries are removed from the original, or source cartridges, and are available to
view within the target, or destination cartridge.
5.6.8 Circular Dependency
Moving plugin entries into cartridges can result in two cartridges being dependent on each other directly or
indirectly, creating a Circular Dependency between cartridges. Configuration Builder will alert you that it cannot
rebuild the cartridges due to a circular dependency. Click the link for details.

UPF 4.1
When you click the link in the error dialog, you can view the details about the Circular Dependency. Then, you can
use the information to resolve the issue.
The Circular Dependency detail dialog provides the dependency details for each of the cartridges. It shows whether
the cartridges have direct dependency or indirect. In case of indirect dependency, a Dependency Path section lists
all intermediate paths of dependency from one cartridge to another.
The Details section explains why a cartridge is dependent on another cartridge. For indirectly dependent
cartridges, each of the dependency paths are explained. Currently, cartridge dependencies are determined based
on the Configuration Entries references and the Component Definitions references generated from Component
Entities.
The dependency detail lists all the Configuration Entries and Component Entities in the dependent cartridge
followed by all the configuration entries in current cartridge which refers to them.
Currently the Details section lists only three of each entry, which can be changed with
"eua.cartridge.circular.dependency.entries" option. However, all details are printed in diag files. The diag "
eua.cartridge.circular.dependency" is used to print the output. The diag is on by default.
Press the Open as Document button to open the detail information in a document. This allows you to review the
details with the configuration.

UPF 4.1
The circular dependency information available in the detail dialog can be explained with an example where user-
cartC has circular dependency with user-cartA. The image above shows the detail information about the
dependency. You can derive the following information.
1. There is a circular dependency between user-cartC and user-cartA.

2. user-cartA transitively depends on user-cartC.

UPF 4.1
3. The Dependency Path section shows that user-cartA depends on user-cartB and user-cartB depends on user-
cartC
4. In DETAILS section for user-cartA, you can see that:
1) user-cartA depends on user-cartB because user-cartB contains Component Entity, Entity Models/ep-em,
which is referred by configuration entries like Enpoints/my-ep in user-cartA
2) user-cartB depends on user-cartC because user-cartC contains Component Entity, Entity Models/sess-em,
which is referred by Sessions/my-sess Configuration Entry, Session/test-session, which is referred by
configuration entries like plug-em/Plugin/my-plug4 etc., in user-cartC
1) user-cartC has direct dependency on user-cartA
5. Similarly, in DETAILS section for user-cartC, you can see that:
1) user-cartA contains Component Entity, Entity Models/plug-em, which is referred by configuration entries
plug-em/Plugin/my-plug
5.6.9 Deploy cartridges
The process to deploy user cartridges to UPF is slightly different from applying normal configuration changes.
1. Right-click the Configuration Cartridge category node in the Cartridge Explorer and select Deploy Cartridges to
open the Cartridge Deploy Wizard.
2. Select the cartridges to be deployed.

UPF 4.1
The list of cartridges available shows the cartridge name, version, and the action to be performed on the active
UPF instance. Actions include Upgrade and First Deploy.
– Upgrade indicates that the cartridge is already available within the running UPF, but has been modified
since it was downloaded.
– First Deploy indicates that the cartridge is newly created or was imported into Configuration builder from an
externally distributed cartridge artifact.
When selecting the cartridges to deploy, Configuration Builder ensures that all cartridge dependencies are met.
In the previous example, the user can select "invalid_cartridge" to deploy by itself, but selecting "UPF", which is
the Configuration Cartridge, automatically selects all other user cartridges as the UPF cartridge has dependency
on all other cartridges.
3. Select the Validate without deploy checkbox to indicate that the selected cartridges be validated only. This is
useful when user wants to perform validation on cartridges without deploying them.
4. Enter the target platform information. The information is later used to deploy the cartridges automatically once
the cartridge validation is successful.

UPF 4.1
You might be unfamiliar with the following fields:
– Schema update mode
– Activate cartridge after deploy
Schema update mode determines how UPF should handle updating the database schema as a result of
changes to RDBMS Entities within the configuration being applied. Typically, when deploying cartridges to a
development system, you select "Disruptive Update" as it allows the configuration to be activated in real-time but
may slow the performance of the system due to potentially disruptive changes being made to the database. This
includes, for example, adding a new index to an existing table. In production, the more conservative, "Delayed
Disruptive Update" would likely be used, requiring a staggered database restart but having a lower impact on a
running system. More information on update modes is available in the Upgrade Modes section.
Activate cartridge after deploy determines whether the cartridges, and the configuration within them, being
deployed to a running UPF should be activated in real-time. The alternative is that the cartridges are simply
stored within the UPF database and not activated. In practice, you would select activate cartridge after deploy
would be selected. When deploying the Configuration Cartridge, which should be the most common action, the
Activate cartridge after deploy is selected and cannot be changed by the user.
Note: The Select target step is skipped if the Validate without deploy checkbox is selected in the previous step.
5. If the wizard finds any validation errors in the cartridges that were selected for deployment, you will receive an
error. All the validation errors can be reviewed on next step.
It is recommended that all the validation errors are reviewed and fixed before deploying and activating the
cartridges. However, the wizard allows you to deploy the cartridges with validation errors by selecting the Deploy
cartridges with error(s) checkbox. This allows you to deploy and activate old cartridges which have validation
errors.

UPF 4.1
UPF 4.1
If there are no validation error, the cartridges are deployed and activated using the platform information provided
earlier in step 2.
Occasionally, you must restart the platform. If a restart is required, you will be informed during the fourth step of the
wizard. In the previous example, the activation was successful.
5.6.10 Clean the configuration cartridge
Specified User Cartridges allow configuration to be packaged and easily exported from one system to another. It
then becomes far simpler to repurpose a system for use within another project. All that is required is the following
steps:
• Clean the Cartridge

• Remove the User Cartridges
• Spring Clean the Database
To clean the configuration cartridge from within the Cartridge Explorer, right-click on the Configuration category
node and select Clean.

UPF 4.1
The result of this action is that all the configuration in the presently loaded configuration cartridge is removed.
5.6.11 Removing the User Cartridges
Once the Configuration Cartridge is empty, you can remove the User Cartridges one by one.
1. Select the User Cartridges node in the Cartridge Explorer tree to display the user cartridge summary
document.
2. Cartridges are displayed in dependency order, so remove them from the bottom up, Click the Delete button
next to each currently active user cartridge.
Removing the cartridges takes some time as the configuration cartridge needs to be regenerated and validated
to ensure that there are no lingering references to the user cartridge within the configuration.
After all cartridges have been removed, use the Upload pending cartridges wizard to deploy changes to the switch.
See the Deploying Cartridges section for more information.
5.6.12 Spring Cleaning the Database
1. In the Repository Explorer, go to the environment that you want to clean and right-click the environment to
begin spring cleaning.

UPF 4.1
2. Enter your user name and password and run the command on the switch. The command completes
immediately; however, the running UPF analyzes the database schema and delete extraneous tables, columns
and indices from the database.
5.6.13 Upgrade cartridges
In the Configuration Builder, you can use a wizard to upgrade a cartridge that is already deployed to a newer
version. The wizard performs an in-depth analysis of the configuration and provides you with a series of guided
steps allowing for the migration of configuration based on the initial cartridge version to be updated. The process of
upgrading a cartridge is complex and even more so than with regular cartridge editing, an expert level user is
required.
1. Go to the user cartridge to upgrade, and right click to access the upgrade cartridge wizard.
2. Select the location of the new user cartridge archive. This is typically a JAR file created on a different instance
of UPF and packaged for distribution.

UPF 4.1
Once selected, the wizard loads and analyzes the supplied cartridge. If there were no issues, a summary of the
new user cartridge file opens.
3. Review the changes to the entity models and their entities:
This step shows you entities that have changed (updated, added, or deleted) between the current version of the
user cartridge and the new version of the user cartridge. For those that have changed, the wizard also checks if
the entity is in the current configuration and has been changed, such as if there is a need to upgrade entity in the
current configuration (this is optional and needs to be confirmed). Note that if there is no potential conflict with an
updated entity in the current configuration, then the change is shown as "Info only" because you cannot opt out.
The upgrade is mandatory.
UPF 4.1
The wizard categorizes the entities in four categories:
– Template Component entities
– Component entities (plug-ins and standard ones)
– RDBMS entities
– Other entities such as PIM
You can take the following actions:
– View compatibility information: shows information about the compatibility between the entity in the current
user cartridge, the new user cartridge, and (if applicable) in the current configuration. This is useful to be
alerted to potential manual merge actions required after the upgrade wizard has completed.
– View changes: shows the changes between the entity in the current user cartridge and the new user
cartridge
– View merge actions: shows the merge actions that will be performed on the entity in the current
configuration if the upgrade is confirmed
4. Before displaying the second review step of the wizard, the merge actions selected within the first review step
are applied to the entities and entity models. Review the changes to configuration entities:
The wizard examines what plugins have changed between the current user cartridge and the new one. The
changes (added plugins, updated plugins, and deleted plugins) are shown in the table. The wizard also checks
whether the plugin exists in the current configuration and if so, whether it has been changed. If it has changed, it
offers the option to upgrade the configuration entry again. This is an optional action for each plugin because you
might want to retain the redefined plugin in the current configuration rather than upgrading. Note that if there is
no potential conflict with an updated configuration entry in the current configuration then the change is shown as
"Info only" because you cannot opt out; the upgrade is mandatory.
If you have a large set of configuration entries that are impacted with this step, you can use the actions Include
All or Exclude All. Where a merge action is offered, you can click the View Merge Actions button to see them in
detail.

UPF 4.1
5. The third review step in the wizard presents the differences between resources (wsdls/xsds) in the source and
target cartridges. The change information includes whether the new files have been added, removed, or
modified (if file with same name already exists).
Before applying all merge actions, the result of all review steps which can include changes to entity models, their
entities, configuration entries, and changes to resources will be shown where you can review the merge actions
one more time in a single list.

UPF 4.1
Note that this list includes all items that you explicitly selected by clicking the Upgrade checkbox and the
mandatory Info only items.
The final step of the wizard applies all merge actions required for entity models, their entities and configuration
entries. It also adjusts any configuration entry if it had any incompatibilities. This can happen because of
changes to Template Components and Component Entities (for example, a property has been deleted in a
Template Component - this requires deleting that property from any configuration entry of that Template
Component).
6. Review the summary of all the changes (merge actions or adjustments):
That is the last step of the wizard but not the last step for the upgrade. After closing the wizard, you might have
to edit some of the configuration entries that were merged or adjusted (such as to add any new properties that
may have been introduced).
Then, you can deploy the upgraded cartridge to UPF using the Upload pending cartridges wizard. See the
Deploying Cartridges section for more information.
5.7 Update user cartridge information

Follow these steps to update user cartridge information.
1. Right-click the User Cartridge node and select Update Cartridge Info.
A wizard opens so you can modify the metadata that describes the cartridge.

UPF 4.1
2. Update the metadata. You can only update the version, compatibility, and description of a user cartridge.
3. Click Update to validate the changes.
The cartridge information is updated, as well as the information in other cartridges where the modified user
cartridge is referenced.
5.8 Cartridge upgrade information

Any ACI UPF MCAS based solution consists of a series of cartridges containing all configuration items and code.
Cartridges are uniquely named and versioned which allows them to be easily identified.
To ascertain whether a cartridge can be deployed in a compatible manner, the cartridge contains a metadata
describing how far back it is compatible. That is, in addition to its current version number the cartridge contains a
backward compatibility version number indicating an older cartridge with which it is backward compatible.
The use of this compatibility information becomes apparent when a cartridge also contains metadata listing all
cartridges that are referenced by itself. That is a list of cartridge names and versions that were referenced when
UPF 4.1
creating the cartridge. In this way, cartridges can form a hierarchy to allow one cartridge to extend and build upon
models and components from other cartridges. One example is the IP framework, where a hierarchy of cartridges
are integrated to deliver the faster payments functionality including UPF cartridges and features. Given the
reference metadata, UPF MCAS can make sure that all required cartridges are present before applying a given
configuration.
This is where the compatibility information becomes important. UPF MCAS does not require the latest or a specific
version of each cartridge to be present. It simply requires a compatible cartridge. If, for example, a cartridge A v3.2
is built using another referenced cartridge B v2.1, UPF MCAS will be able to start with a newer cartridge B v2.7
provided B v2.7 is backward compatible with B v2.1. Since all cartridges are likely to have references to other
cartridges, and these cartridges may evolve separately, the backward compatibility mechanism helps to keep track
of the whole solution and guarantees that no features are missing.
5.8.1 Upgrade mechanisms for cartridges
All upgrades involve changing one or more cartridges in an existing solution. Certain upgrades can be performed
quite easily in real-time whereas others require more forethought and more complex deployment.
Even though the fundamental mechanism is the same, cartridge upgrades are performed in two basic ways:
Upgrades to product cartridges received from ACI for specific UPF based products such as Immediate Payments
or FPS.
1. Changes made to a cartridge or configuration through the Configuration Builder and applied directly to a
running solution.
2. Changes made by Configuration Builder are applied directly from the Configuration Builder or through a
command line equivalent. Whereas the mechanism for deployment and activation differ, the underlying
consideration for applying a configuration is the same.
5.8.2 Upgrade considerations
Applying an upgrade involves upgrading one or more cartridges in an existing and running solution. Changes fall
into three main categories:
1. Changes that may be applied directly without significant impact on processing

2. Changes that may be disruptive and interfere with the performance of the system
3. Changes that require a process restart
Changes from category 1 are the least disruptive and, in general, the most common. These changes can involve
additions as well as changes to information structures, validation, and protocols.
Disruptive changes from category 2 typically involve certain types of database changes that can take some time,
and during which transactions may be wholly or partially paused. Such changes include changes to key/index
structure, for example where an index rebuild can take a while to execute.
The final category involves changes that cannot be applied in real-time and require processes to be restarted,
which are rare. Generally, this involves changes that impact the whole platform.
The different categories of changes give an indication of how much the change affects the solution. For releases,
the release notes will list all major changes and will categorize these changes. Changes applied from Configuration
Builder will be categorized in the list of changes shown in the Configuration Builder screen before deployment.
The three categories (light, disruptive, and restart-required) are only indicative. The actual impact depends on the
capacity of the underlying platform (servers, databases etc.), and amount of changes as well as the transaction

UPF 4.1
processing load at the time of activation. In general, it is always safest to apply changes during periods of relatively
low load. Also, during recovery from an earlier partial failure such as a database outage, an additional activity may
be going on to bring the system back to full operational status. During such recovery periods, it is similarly wise to
not activate new configurations.
5.8.3 Upgrade Modes
There are three different upgrade modes that impact the running solution differently. They are:
1. NON_DISRUPTIVE_UPDATE
2. DELAYED_DISRUPTIVE_UPDATE
3. DISRUPTIVE_UPDATE
Light changes are simply applied to the running solution without further considerations, although applying a
configuration will consume more CPU and database IO. During the upgrade process, throughput and latencies may
be temporarily affected. This upgrade mode is known as NON_DISRUPTIVE_UPDATE. Unless specified
otherwise, this is the recommended mode to use for configuration and cartridge updates.
Potentially disruptive changes make use of a mechanism whereby each database is temporarily taken offline
during the upgrade process, and then re-activated resulting in a data resynchronization phase. Once the database
is up-to-date, the next database instance is taken offline and so forth. This upgrade mode is known as
DELAYED_DISRUPTIVE_UPDATE.
An override mode known as DISRUPTIVE_UPDATE allows disruptive changes to be applied directly without going
through the DELAYED_DISRUPTIVE_UPDATE process. This is useful for test/development environments where
impact to the payment processing is not important (e.g. the number of rows is very small but we want to rebuild an
index) or can be used in production during a planned outage (i.e. at 0 TPS).
5.9 User Cartridge Rollback

In some cases, it may be necessary to revert a user cartridge activation. UPF only supports a single configuration
at any given time. This configuration cartridge contains a reference to each of its dependencies as discussed in
section 5.4 above. In practice, this means that the only the cartridges referenced by the configuration cartridge are
loaded in the system. To remove an active user cartridge, activate a different configuration cartridge which does
not reference the user cartridge.
There are multiple ways to rollback a user cartridge activation. The primary mechanisms include:
• Revert a change log entry.

• Activate a previous configuration.
• Remove a user cartridge.
To revert a change log entry, go to the change log, described in section 3.3.4 above. Select the change log entry
and select revert. To help determine which change log entry to revert, review the list of User Cartridges active in
the Configuration Cartridge in the Change (before) field. This field contains the details of the configuration which
will be active if the change log entry were to be reverted.
You can also use the mcascmd utility to activate a given configuration version. When determining which User
Cartridges are referenced by a configuration cartridge, you can review the Change (after) field in the change log.
The command to execute is:
/mcas/config activate name=”UPP” version=”<version-to-activate>”

schemaUpdateMode=”<schema-update-mode>”.

UPF 4.1
To remove a User Cartridge, see section 5.6.11 above. On deploy this will result in the construction of a new
Configuration Cartridge version which no longer references the user cartridge.
It is important to note that not all changes which are made in a user cartridge can be rolled back without manual
intervention. Some changes which are backwards compatible to activate, such as widening an RDBMS Entity
property, are not considered backwards compatible when activating a previous version.

UPF 4.1
© Copyright ACI Worldwide, Inc. 2018
ACI, ACI Payment Systems, the ACI logo, ACI Universal
Payments, UP, the UP logo, ReD, PAY.ON and all ACI product
names are trademarks or registered trademarks of ACI Worldwide,
Inc., or one of its subsidiaries, in the United States, other countries
or both. Other parties’ trademarks referenced are the property of
their respective owners.

UPF 4.1 - Configuration Builder Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

UPF 4.1 - Configuration Builder Guide

Uploaded by

Copyright:

Available Formats

CONFIGURATION

ACI WORLDWIDE, INC.

About this publication .......................................................................................................... 6

2 Installation and setup................................................................................................. 11

3 Navigate Configuration Builder ................................................................................ 20

Configuration Builder Guide 2

4 Prepare and deploy configurations .......................................................................... 30

Configuration Builder Guide 3

Configuration Builder Guide 4

Release number Revision date Description of changes

• Added User Preferences

Updated NetBeans version to 8.2

Configuration Builder is valid in

Updated Screenshots based on

4: Prepare and deploy

Configuration Builder Guide 5

Configuration Builder Guide 6

1.1 Configuration Builder features

• Importing configurations from an ACI UPF platform.

Configuration Builder Guide 7

1.2 Basic concepts

1.2.2 Configuration repository

1.2.5 Edit offline

1.2.7 Clone configurations

Features of the Clone and New from clone functions include:

• allow cloning of any complex component.

Configuration Builder Guide 9

1.2.9 Status bar

1.2.10 Expression list option

Configuration Builder Guide 10

2.1 Installation prerequisites

2.1.1 Minimum hardware requirements

2.1.2 Java™ Virtual Machine requirements

For more information, see Sun Java at: https://www.oracle.com/java/index.html.

2.1.3 Encryption requirements

2.2 Install the ACI UPF End-User Application

1. Copy AciEUAInstaller.jar to a temporary location on your computer.

To download the Zip file:

Configuration Builder Guide 11

Minimum Hardware Requirement Operating Systems Virtualization

Processor: Intel Pentium 4, 3.0 Windows 10 (64 bit)

Memory: At least 1.4 gigabyte of

2.3 Firewalls and port usage

Platform 1 - UPF Instance One:

Configuration Builder Guide 12

Platform 1 - UPF Instance One:

Platform 1 - UPF Instance One:

2.4 End User Application (EUA) diagnostics

2.4.1 Diagnostics control panel

• View available list of diagnostics and their current level

Configuration Builder Guide 14

2.4.3 Actions available in the diagnostic control panel

2.4.4 Sorting and filtering diagnostics list

ui.* Lists all the diagnostics with name starting with ui

*.debug.* Lists all the diagnostics whose name contains debug

2.4.5 Change current level of diagnostic

2.4.6 Disable all sensitive diags

2.4.7 Reset all diags to default level

Configuration Builder Guide 16

2.4.9 Filtered reset

2.4.10 Secure delete sensitive output files

Configuration Builder Guide 17

Configuration Builder Guide 18

For example, consider following scenario:

.debug. Lists all the diagnostics whose name contains debug