IBM App Connect Enterprise

12.0

IBM App Connect Enterprise 12.0; User

Guide

IBM
Note
Before using this information and the product it supports, read the information in “Notices” on page
3077.
Contents

Chapter 1. Planning your IBM App Connect Enterprise solution.............................. 1

Finding the latest information.................................................................................................................... 1
Understanding your data and message processing requirements............................................................ 1
Choosing your IBM App Connect Enterprise edition and operation mode............................................... 2
Operation modes....................................................................................................................................3
Restrictions that apply in each operation mode.................................................................................. 5
License requirements.................................................................................................................................. 5
Installing IBM License Service and adding annotations for IBM App Connect Enterprise
containers.......................................................................................................................................... 6
Planning an IBM App Connect Enterprise environment............................................................................ 8
Planning the high-level infrastructure...................................................................................................8
Business planning................................................................................................................................ 11
Cloud overview.....................................................................................................................................12
Performance planning..........................................................................................................................16
Planning for security............................................................................................................................17
Replicating your environment for multiple users............................................................................... 17

Chapter 2. Migrating............................................................................................ 19
Preparing for migration............................................................................................................................. 19
Supported migration paths..................................................................................................................20
Migration planning............................................................................................................................... 20
Behavioral changes in Version 12.0................................................................................................... 22
IBM MQ and migration........................................................................................................................ 28
IBM App Connect Enterprise migration options.................................................................................29
Example migration scenarios.............................................................................................................. 29
Performing pre-migration tasks................................................................................................................41
Backing up resources before migration..............................................................................................41
Updating ODBC definitions..................................................................................................................42
Running the Transformation Advisor tool...........................................................................................44
Migrating to IBM App Connect Enterprise 12.0.......................................................................................57
Performing extract migration of an integration node or integration server....................................... 57
Performing parallel migration for an integration node.......................................................................61
Migrating development resources.......................................................................................................62
Performing post-migration tasks.............................................................................................................. 64
Setting up a command environment...................................................................................................64
Reconfiguring administration security................................................................................................ 65
Setting up a global cache....................................................................................................................65
Migrating deployable resources.......................................................................................................... 66

Chapter 3. Installing and uninstalling IBM App Connect Enterprise.......................69

Installing IBM App Connect Enterprise....................................................................................................69
Coexistence of IBM App Connect Enterprise 12.0 with previous versions....................................... 70
Preparing the system...........................................................................................................................71
Installing the software.........................................................................................................................75
Setting up a command environment...................................................................................................83
Configuring your IBM App Connect Enterprise installation to conform to your license.................... 85
Configuring the web user interface.....................................................................................................87
Applying service to IBM App Connect Enterprise....................................................................................90
Applying service to an integration node that starts under the control of an IBM MQ queue
manager...........................................................................................................................................92

iii
 Uninstalling IBM App Connect Enterprise................................................................................................93
Uninstalling on Windows..................................................................................................................... 93
Uninstalling on Linux and UNIX systems............................................................................................94
Uninstalling language packs from the IBM App Connect Enterprise Toolkit..................................... 94
Installing and uninstalling complementary products.............................................................................. 96
Installing IBM MQ................................................................................................................................ 96
Installing IBM License Metric Tool................................................................................................... 100

Chapter 4. Configuring IBM App Connect Enterprise...........................................103

Configuring the IBM App Connect Enterprise Toolkit............................................................................103
Starting the App Connect Enterprise Toolkit....................................................................................104
Changing IBM App Connect Enterprise Toolkit preferences........................................................... 105
Changing workbench capabilities..................................................................................................... 106
Configuring CVS to run with the IBM App Connect Enterprise Toolkit............................................ 107
Configuring the IBM App Connect Enterprise Toolkit to run Rational ClearCase............................ 107
Creating a working set...................................................................................................................... 108
Integrating the Rational Team Concert client with the IBM App Connect Enterprise Toolkit......... 109
Configuring App Connect Enterprise to run on premises (on a physical or virtual machine)............... 110
Configuring App Connect Enterprise to run in a container....................................................................111
Configuring App Connect Enterprise to run in Docker.......................................................................... 111
Docker support on Linux systems.................................................................................................... 112
Stopping an IBM App Connect Enterprise Docker container...........................................................112
Building a sample IBM App Connect Enterprise image using Docker............................................. 113
Configuring integration nodes................................................................................................................ 113
Creating an integration node............................................................................................................ 114
Configuring an integration node by modifying the node.conf.yaml file........................................... 118
Verifying an integration node............................................................................................................ 120
Configuring integration nodes for high availability...........................................................................120
Deleting an integration node.............................................................................................................165
Configuring an integration node as an IBM MQ service........................................................................ 166
Starting and stopping an integration node as an IBM MQ service.................................................. 166
Configuring integration servers.............................................................................................................. 167
Creating an integration server.......................................................................................................... 168
Configuring an integration server by modifying the server.conf.yaml file........................................172
Deleting an integration server...........................................................................................................175
Configuring encrypted security credentials........................................................................................... 177
Configuring security credentials for an independent integration server in the server.conf.yaml file....178
Configuring a default application for an integration server...................................................................181
Configuring the environment to access external applications and resources...................................... 182
Configuring databases....................................................................................................................... 182
Configuring properties to connect to external resources................................................................ 208
Configuring internal resources required by message flows.................................................................. 229
Configuring the storage of events for aggregation nodes................................................................ 229
Configuring the storage of events for Collector nodes.................................................................... 231
Configuring the storage of events for Resequence nodes............................................................... 232
Configuring the storage of events for timeout nodes...................................................................... 234
Configuring the XPath cache.............................................................................................................235
Configuring monitoring event sources by using a monitoring profile.............................................. 236
Changing locales..................................................................................................................................... 237
Changing your locale on Linux and UNIX systems...........................................................................237
Changing your locale on Windows....................................................................................................239
Code page converters........................................................................................................................239

Chapter 5. Administering IBM App Connect Enterprise....................................... 243

Managing integration nodes................................................................................................................... 243
Connecting to an integration node by creating a .broker file....................................................... 244
Connecting to an integration node by using the Toolkit.................................................................. 245

iv
 Starting and stopping an integration node.......................................................................................247
Viewing integration node properties.................................................................................................249
Managing integration servers................................................................................................................. 249
Starting an integration server........................................................................................................... 250
Stopping an integration server..........................................................................................................254
Connecting to an integration server by using the Toolkit................................................................ 255
Connecting to an independent integration server from the Toolkit by specifying a userid and
password....................................................................................................................................... 256
Viewing integrations by using an IBM App Connect Dashboard........................................................... 258
Starting an IBM App Connect Dashboard by using the Dashboard command.............................. 258
Logging in and out of an IBM App Connect Dashboard................................................................... 260
Configuring an integration server to connect to an IBM App Connect Dashboard..........................261
Creating connections in an IBM App Connect Dashboard...............................................................264
Viewing integration servers that are connected to an IBM App Connect Dashboard..................... 266
Viewing the state of integration servers that are connected to an IBM App Connect Dashboard.. 268
Viewing information from deployed resources in an IBM App Connect Dashboard....................... 269
Sharing connection information with other users in an IBM App Connect Dashboard................... 270
Managing resources................................................................................................................................ 271
Managing data caching......................................................................................................................271
Listing database connections............................................................................................................314
Quiescing a database........................................................................................................................ 314
Using a JDBC connection pool to manage database resources used by an integration server.......315
Managing deployed resources................................................................................................................316
Setting the start mode of message flows and applications at run time.......................................... 316
Starting or stopping deployed resources......................................................................................... 317
Viewing version information and custom keyword values in your deployed solutions................... 319
Deleting deployed resources............................................................................................................ 319
Deleting deployed policies................................................................................................................ 322
Managing a deployed REST API........................................................................................................323
Overriding properties at run time with policies.....................................................................................324
Policies overview............................................................................................................................... 324
Creating policies with the IBM App Connect Enterprise Toolkit......................................................327
Overriding deployed policies at run time with the overrides directory........................................... 328
Configuring a default policy project..................................................................................................329
Viewing administration activity in the admin log...................................................................................330
Filtering admin log entries in the web user interface...................................................................... 331
Writing admin log entries to a file.................................................................................................... 332
Configuring administration logging................................................................................................... 333
Managing resources by using the administration REST API................................................................. 334
Administering integration servers by using the administration REST API...................................... 335
Using trace through the administration REST API........................................................................... 345
Monitoring by using the administration REST API........................................................................... 364
Administering applications, REST APIs, and integration services by using the administration
REST API....................................................................................................................................... 388
Administering message flows by using the administration REST API.............................................417
Using resources statistics through the administration REST API....................................................432
Setting message flow user-defined properties at run time by using the administration REST
API................................................................................................................................................. 436
Updating the HTTPS Connector resource manager by using the administration REST API............440
Managing resources by using the IBM Integration API.........................................................................444
Configuring an environment for developing and running custom integration applications.............444
Connecting to an integration node from a custom integration application..................................... 447
Navigating integration nodes and integration node resources........................................................ 449
Deploying resources to the integration node................................................................................... 452
Managing integration nodes by using JavaCompute nodes.............................................................454
Creating objects................................................................................................................................. 455
Developing applications using the IBM Integration API: Example code.........................................455
The IBM Integration API samples.................................................................................................... 467

v
 Managing resources by using the IBM App Connect Enterprise web user interface............................ 469
Applying a user-defined property override in the IBM App Connect Enterprise web user
interface........................................................................................................................................ 469
Removing a user-defined property override in the IBM App Connect Enterprise web user
interface........................................................................................................................................ 470
Update the message flow thread pool by using the IBM App Connect Enterprise web user
interface........................................................................................................................................ 472
Administering Java applications.............................................................................................................473
Tuning JVM parameters.....................................................................................................................473
Configuring class loaders for Java user-defined nodes................................................................... 473
Configuring class loaders for JavaCompute nodes.......................................................................... 473
Configuring class loaders for ESQL routines.................................................................................... 474
Changing the location of the IBM App Connect Enterprise working directory..................................... 474
Changing the location of the working directory on Windows systems............................................ 474
Changing the location of the working directory on Linux................................................................ 475
Backing up the IBM App Connect Enterprise Toolkit workspace..........................................................476
Backing up resources..............................................................................................................................477
Backing up the integration node.......................................................................................................477
Restoring the integration node......................................................................................................... 478

Chapter 6. Developing integration solutions....................................................... 481

Developing message flows..................................................................................................................... 482
Message flows overview....................................................................................................................483
Managing message flow resources...................................................................................................572
Designing a message flow.................................................................................................................583
Defining message flow content.........................................................................................................614
Testing and troubleshooting message flows.................................................................................... 647
Message flow behavior......................................................................................................................690
Connecting client applications.......................................................................................................... 737
Routing messages............................................................................................................................1233
Transforming and enriching messages...........................................................................................1249
Processing events............................................................................................................................1819
Handling errors in message flows.................................................................................................. 1883
Developing integration tests.................................................................................................................1891
Integration testing overview........................................................................................................... 1893
Developing integration tests by using the IBM App Connect Enterprise Toolkit...........................1894
Generating tests from recorded messages in a message flow......................................................1908
Testing a sequence of message flow nodes in a single test case................................................. 1912
Editing a message assembly...........................................................................................................1921
Running integration tests................................................................................................................ 1932
Example message flow node tests.................................................................................................1938
Developing integration solutions from scratch....................................................................................1941
Resource management overview....................................................................................................1942
Creating an application................................................................................................................... 1963
Creating resources in an application.............................................................................................. 1964
Creating a library............................................................................................................................. 1964
Creating resources in a library........................................................................................................1965
Creating a broker schema............................................................................................................... 1966
Creating a solution based on WSDL or XSD files........................................................................... 1967
Creating a solution based on an existing message set..................................................................1968
Creating an integration project....................................................................................................... 1969
Creating resources in an integration project..................................................................................1970
Converting existing projects to applications and libraries.............................................................1970
Converting between applications and libraries..............................................................................1974
Referencing resources from a container........................................................................................ 1975
Focusing on an application or library............................................................................................. 1981
Deleting an integration project....................................................................................................... 1982

vi
 Deleting a schema...........................................................................................................................1983
Exporting XSD schema files from an application or library........................................................... 1983
Developing integration solutions by using integration services..........................................................1984
Integration service editor................................................................................................................1985
Creating an integration service from scratch................................................................................. 1986
Creating an integration service based on a WSDL file................................................................... 1987
Creating an integration service from a Business Process Manager integration service................1988
Defining the operations in a service interface............................................................................... 1989
Implementing an integration service operation.............................................................................1993
Implementing an integration service error handler subflow.........................................................1994
Generating an integration service SOAP/HTTP binding................................................................. 1995
Integration service JavaScript client API.......................................................................................1995
Developing integration solutions by using REST APIs........................................................................ 2011
REST APIs........................................................................................................................................ 2013
Swagger............................................................................................................................................2015
Restrictions on Swagger documents.............................................................................................. 2018
OpenAPI 3.0.................................................................................................................................... 2018
Restrictions on OpenAPI 3.0 documents.......................................................................................2019
Creating a REST API........................................................................................................................2019
Defining resources, models, and operations in a REST API by using the REST API Editor........... 2025
Defining resources, models, and operations in a REST API by using the OpenAPI editor............ 2029
Implementing an operation in a REST API by using the REST API Editor for Swagger 2
documents.................................................................................................................................. 2030
Implementing an operation for REST APIs based on OpenAPI 3.0 documents........................... 2034
Implementing an error handler in a REST API............................................................................. 2038
Handling non-JSON data in a REST API........................................................................................ 2039
Securing a REST API by using HTTPS............................................................................................ 2041
Securing a REST API by using HTTP Basic Authentication........................................................... 2042
Permitting web browsers to access a REST API by using CORS................................................... 2043
Creating a new REST API that uses artifacts from an existing REST API......................................2044
Packaging and deploying a REST API............................................................................................ 2045
Pushing REST APIs to IBM API Connect........................................................................................2046
Developing integration solutions by using patterns............................................................................ 2056
Patterns............................................................................................................................................ 2057
Using patterns..................................................................................................................................2058
Getting patterns from the GitHub repository................................................................................. 2067
User-defined patterns..................................................................................................................... 2067
Constructing message models............................................................................................................. 2133
Message modeling overview........................................................................................................... 2134
Modeling different data formats..................................................................................................... 2207
How to model data with DFDL........................................................................................................2213
Working with DFDL schema files.................................................................................................... 2220
Working with XML schema files......................................................................................................2242
Working with JSON schema files....................................................................................................2245
Message Sets: Working with message sets................................................................................... 2247
Applying a Quick Fix to a task list error......................................................................................... 2318
Importing files from the file system into the IBM App Connect Enterprise Toolkit...................... 2319
Developing user-defined extensions....................................................................................................2321
User-defined extensions overview................................................................................................. 2321
Implementing the supplied user-defined extension samples.......................................................2350
Developing connectors.................................................................................................................... 2351
Developing user-defined nodes...................................................................................................... 2371
Developing user-defined parsers....................................................................................................2434
Developing user-defined exits........................................................................................................ 2443
Packaging and distributing user-defined extensions..................................................................... 2449

Chapter 7. Deploying integration solutions....................................................... 2463

vii
 Deploying integration solutions during development......................................................................... 2464
Deployment rules and guidelines................................................................................................... 2465
Packaging integration solutions........................................................................................................... 2465
Version and keyword information for deployable resources......................................................... 2466
Creating a BAR file.......................................................................................................................... 2469
Preparing packaged solutions for deployment....................................................................................2476
Editing configurable properties in a BAR file................................................................................. 2477
Configuring a message flow at deployment time with user-defined properties........................... 2478
Adding multiple instances of a message flow to a BAR file.......................................................... 2479
Deploying integration solutions to a production environment............................................................2480
Deploying a BAR file by using the web user interface...................................................................2480
Deploying a BAR file by using the IBM App Connect Enterprise Toolkit....................................... 2481
Precompiling and deploying a BAR file by using the mqsibar command.................................... 2481
Deploying a BAR file by using the mqsideploy command.......................................................... 2482
Deploying a BAR file by using the IBM Integration API................................................................ 2483
Deploying a BAR file to IBM App Connect on IBM Cloud..............................................................2484
Deploying a BAR file to IBM App Connect in containers............................................................... 2484
Checking the results of deployment...............................................................................................2485
Redeploying integration solutions to a production environment........................................................2487
Refreshing the contents of a BAR file............................................................................................ 2488

Chapter 8. Security.......................................................................................... 2491

Security overview.................................................................................................................................. 2491
Authorization for configuration tasks............................................................................................. 2492
Security exits................................................................................................................................... 2492
Public key cryptography..................................................................................................................2492
Digital certificates............................................................................................................................2493
Digital signatures............................................................................................................................. 2496
Administration security.........................................................................................................................2497
Administration security overview................................................................................................... 2497
Setting up administration security..................................................................................................2504
Message flow security.......................................................................................................................... 2550
Message flow security overview..................................................................................................... 2550
Setting up message flow security...................................................................................................2583
Security for runtime components........................................................................................................ 2632
Creating user IDs.............................................................................................................................2633
Controlling access to IBM App Connect Enterprise.......................................................................2633
Implementing SSL authentication.................................................................................................. 2635
Security for the IBM App Connect Enterprise Toolkit......................................................................... 2648
Routing requests through an HTTP proxy server that has authentication enabled............................2649
WS-Security........................................................................................................................................... 2650
WS-Security mechanisms............................................................................................................... 2651
Implementing WS-Security............................................................................................................. 2652
Kerberos-based WS-Security.......................................................................................................... 2655
Policy sets........................................................................................................................................ 2662
Message flow security and security profiles.................................................................................. 2673
WS-Security capabilities................................................................................................................. 2674

Chapter 9. Performance, monitoring, and workload management..................... 2687

Performance.......................................................................................................................................... 2688
Performance planning..................................................................................................................... 2688
Message flow design and performance..........................................................................................2689
Code design and performance........................................................................................................2690
Analyzing message flow performance............................................................................................2699
Analyzing resource performance.................................................................................................... 2739
Tuning the integration node............................................................................................................2762
Troubleshooting performance problems........................................................................................ 2766

viii
 Message flow monitoring......................................................................................................................2771
Message flow monitoring overview................................................................................................ 2772
Configuring monitoring for message flows.....................................................................................2788
Configuring and subscribing to performance and monitoring events.................................................2807
Configuring the publication of event messages............................................................................. 2807
Configuring the built-in MQTT pub/sub broker.............................................................................. 2811
Subscribing to event message topics.............................................................................................2813
IBM App Connect Enterprise event messages...............................................................................2816
Monitoring business transactions........................................................................................................ 2817
Business transaction monitoring overview.................................................................................... 2818
Configuring business transaction monitoring.................................................................................2820
Enabling security for business transaction monitoring..................................................................2824
Creating a business transaction definition.....................................................................................2826
Starting and stopping a business transaction definition............................................................... 2827
Updating a business transaction definition....................................................................................2828
Deleting a business transaction definition..................................................................................... 2830
Viewing the results of business transaction monitoring................................................................2830
Example business transaction policy............................................................................................. 2833
Recording, viewing, and replaying data............................................................................................... 2834
Record and replay........................................................................................................................... 2835
Enabling security for record and replay......................................................................................... 2835
Recording data.................................................................................................................................2837
Viewing recorded data.................................................................................................................... 2849
Replaying data................................................................................................................................. 2850
Using multiple integration nodes and multiple independent integration servers for record and
replay.......................................................................................................................................... 2851
Disabling and enabling Recording.................................................................................................. 2853
Activity Logs.......................................................................................................................................... 2854
Activity Log overview.......................................................................................................................2854
Viewing and setting runtime properties for Activity Logs..............................................................2855
Viewing Activity Logs for message flows in the web user interface..............................................2856
Writing Activity Logs to files or to Logstash in an ELK stack......................................................... 2857
Activity Logs structure and types................................................................................................... 2858
Reporting logs and monitoring events to a Logstash input in an ELK stack....................................... 2869
Configuring integration servers to send logs and events to Logstash in an ELK stack....................... 2870
Workload management.........................................................................................................................2873
Configure a message flow to cause notification threshold messages to be published.................2874
Setting the maximum rate for a message flow.............................................................................. 2877

Chapter 10. Troubleshooting and support.........................................................2879

Troubleshooting overview.....................................................................................................................2879
Recording the symptoms of the problem.......................................................................................2879
Re-creating the problem................................................................................................................. 2880
Eliminating possible causes............................................................................................................2880
Making initial checks.............................................................................................................................2880
Did you log off Windows while IBM App Connect Enterprise components were active?..............2881
Are the Linux and UNIX environment variables set correctly?......................................................2881
Are there any error messages or return codes that explain the problem?................................... 2882
Can you see all of your files and folders?...................................................................................... 2882
Can you reproduce the problem?................................................................................................... 2883
Has the message flow run successfully before?............................................................................2883
Have you made any changes since the last successful run?.........................................................2884
Is there a problem with descriptive text for a command?............................................................ 2885
Is there a problem with a database?............................................................................................. 2885
Is there a problem with the network?........................................................................................... 2885
Does the problem affect all users?................................................................................................ 2886
Have you recently changed a password?....................................................................................... 2886

ix
 Have you applied any service updates?......................................................................................... 2886
Do you have a component that is running slowly?........................................................................ 2887
Dealing with problems..........................................................................................................................2887
Resolving problems when you install IBM App Connect Enterprise............................................. 2888
Resolving problems when you uninstall IBM App Connect Enterprise......................................... 2890
Resolving problems when running commands.............................................................................. 2890
Resolving problems when creating resources............................................................................... 2893
Resolving problems when renaming resources............................................................................. 2895
Resolving problems when starting an integration node................................................................ 2895
Resolving problems when starting resources................................................................................ 2899
Resolving problems that occur when migrating or importing resources.......................................2905
Resolving problems when stopping resources.............................................................................. 2909
Resolving problems when deleting resources............................................................................... 2911
Resolving problems when developing message flows.................................................................. 2911
Resolving problems when deploying message flows or message sets......................................... 2953
Resolving problems that occur when debugging message flows..................................................2962
Resolving diagnostic data collection errors................................................................................... 2967
Resolving problems when developing message models............................................................... 2967
Resolving problems when using messages....................................................................................2974
Resolving problems when you are writing business rules.............................................................2987
Resolving problems when you use the IBM App Connect Enterprise Toolkit............................... 2987
Resolving problems when using Data Analysis..............................................................................2998
Resolving problems when using databases................................................................................... 2998
Resolving problems when using publish/subscribe.......................................................................3007
Resolving problems with performance...........................................................................................3010
Resolving problems when you monitor message flows.................................................................3013
Resolving problems when developing custom integration applications....................................... 3015
Resolving problems when using an MQ Service............................................................................ 3016
Resolving problems with user-defined extensions........................................................................ 3017
Using logs.............................................................................................................................................. 3023
Windows: Viewing the local error log.............................................................................................3023
Linux and UNIX systems: Configuring the syslog daemon............................................................ 3024
Viewing the Eclipse error log.......................................................................................................... 3025
Viewing the exception log............................................................................................................... 3026
Using trace.............................................................................................................................................3026
User trace.........................................................................................................................................3027
Service trace.................................................................................................................................... 3032
Interpreting trace............................................................................................................................ 3036
Clearing old information from trace files....................................................................................... 3037
ODBC trace...................................................................................................................................... 3037
IBM Integration API trace...............................................................................................................3038
Switching Trace nodes on and off.................................................................................................. 3038
Using dumps and abend files...............................................................................................................3039
Checking for dumps........................................................................................................................ 3039
Checking for abend files................................................................................................................. 3040
Contacting your IBM Support Center...................................................................................................3040
Collecting diagnostics........................................................................................................................... 3041
Searching knowledge bases................................................................................................................. 3042
Getting product fixes............................................................................................................................ 3042
Contacting IBM Software Support....................................................................................................... 3043
Determine the effect of the problem on your business.................................................................3043
Describe your problem and gather background information.........................................................3044
Submit your problem to IBM Software Support............................................................................ 3044

Chapter 11. IBM App Connect Enterprise on IBM z/OS Container Extensions
(zCX)........................................................................................................... 3045
Provisioning an IBM z/OS Container Extensions (zCX) instance.........................................................3046

x
 Installing and configuring IBM App Connect Enterprise on zCX.........................................................3046
Customizing the JCL............................................................................................................................. 3048
Creating an IBM App Connect Enterprise Integration Server Docker image on IBM z/OS Container
Extensions (zCX) by using the supplied JCL...................................................................................3049
Loading a Docker image from a .tar file on the z/OS UNIX System Services file system.............. 3051
Building your own Docker image.................................................................................................... 3052
Administering IBM App Connect Enterprise on IBM z/OS Container Extensions (zCX) by using JCL 3053
Starting an integration server on IBM z/OS Container Extensions (zCX) by using JCL................. 3054
Stopping an integration server on IBM z/OS Container Extensions (zCX) by using JCL................3054
Deleting an integration server on IBM z/OS Container Extensions (zCX) by using JCL.................3055
Running IBM App Connect Enterprise commands on IBM z/OS Container Extensions (zCX) by
using JCL.....................................................................................................................................3055
Administering IBM App Connect Enterprise on IBM z/OS Container Extensions (zCX) by using IBM
z/OS console commands................................................................................................................. 3056
Copying the started task to the procedures library....................................................................... 3057
Starting an integration server on IBM z/OS Container Extensions (zCX) by using IBM z/OS
console commands.................................................................................................................... 3058
Stopping an integration server on IBM z/OS Container Extensions (zCX) by using IBM z/OS
console commands.................................................................................................................... 3058
Deleting an integration server on IBM z/OS Container Extensions (zCX) by using IBM z/OS
console commands.................................................................................................................... 3059
Running IBM App Connect Enterprise commands on IBM z/OS Container Extensions (zCX) by
using IBM z/OS console commands..........................................................................................3059
Planning and customization tasks on z/OS......................................................................................... 3061
Environment variables in STDENV and BIPENVS................................................................................ 3062
Configuring access to Integration Servers running in IBM z/OS Container Extensions (zCX)............ 3071
Troubleshooting on IBM z/OS Container Extensions (zCX).................................................................3073
Applying maintenance to IBM App Connect Enterprise on IBM z/OS Container Extensions (zCX).... 3074

Notices............................................................................................................3077
Programming interface information..................................................................................................... 3078
Trademarks............................................................................................................................................3078

xi
xii
Chapter 1. Planning your IBM App Connect Enterprise
solution
Use the topics in this section to help you plan your implementation of IBM® App Connect Enterprise.

Finding the latest information

Access the latest information for IBM App Connect Enterprise, including system requirements and
product documentation.

About this task

The following information is provided:
System requirements web page
For the latest details of hardware requirements, operating systems, and software requirements on all
supported platforms, visit the IBM App Connect Enterprise system requirements web page.
readme.html file
The product readme.html file is frequently updated and includes information about last-minute
changes and known problems and work-arounds. You can find the current readme file at https://
www.ibm.com/support/pages/node/318359.
Supporting programs for web page
For a list of supporting program versions for IBM App Connect Enterprise 12.0, IBM App Connect
Enterprise for Developers 12.0, and IBM App Connect Standard 12.0, see Supporting programs for
IBM App Connect.
Online documentation
The main source of product documentation is online at https://www.ibm.com/docs/app-connect/12.0,
which is also accessible from the IBM App Connect Enterprise Toolkit with an internet connection.

Understanding your data and message processing requirements

It is important to be clear about your processing requirements, and to understand what you want IBM
App Connect Enterprise to do for your business.

About this task

In a typical IT environment there are many interacting components, each with a role to play, and it is
important that you are able to clearly define the role of IBM App Connect Enterprise in the broader
environment. A key design decision is how much business logic to implement within your message flows.
IBM App Connect Enterprise enables you to implement large amounts of processing within a message
flow, and implementations can vary significantly from the simple routing of messages to complex
validation and transformation. Some implementations also read data from a database and use that data
to populate messages. Regardless of the amount of function that you decide to implement in a message
flow, it is important to have clear boundaries between pieces of application processing.
Several different processing styles are commonly used with IBM App Connect Enterprise, and it is
important to understand the ones that are most relevant to you, such as:
Request Reply
This is the most common type of processing, and enables two applications to communicate, even if
they use different data formats. For example, a message flow transforms a request message from
Application 1 into a format that Application 2 can understand. The output of the first message flow is
then sent to Application 2, which processes the request and issues a reply. The reply is processed in
a second message flow, which converts the response message into a format that Application 1 can
understand.

© Copyright IBM Corp. 2016 1

 Aggregation
This type of processing is often used to invoke one or more back-end systems and coordinate replies.
It is a more complex form of a Request Reply case, in which all the replies from the intermediate
applications must be collected together before the reply message for the original request can be sent.
For example, this type of processing could be used to book a holiday, in which a flight, hotel, and a car
are required, and all must be successfully processed before the holiday confirmation can be sent.
Routing
Routing is used to redirect messages, and one or more copies of a message can be sent to one or
more destinations.
Transformation
This type of processing involves the use of one or more transformation technologies such as Compute,
JavaCompute, XMLT, or Mapping node. In this type of processing the input message is processed
according to some business rules, and there might also be a change of message format or protocol.
File processing
The use of files is one of the most common methods of storing data. You can create message flows
to process data in files, accepting data in files as input message data, and producing output message
data for file-based destinations.
Database handling
You can configure your message flows to access and manipulate business data in databases.
Web services
IBM App Connect Enterprise can be used as both a consumer and provider of web services.
Transport switching
You can use this type of processing to switch between transports such as HTTP and JMS.
For information about how to choose the appropriate edition of IBM App Connect Enterprise to suit your
requirements, see “Choosing your IBM App Connect Enterprise edition and operation mode” on page
2. For more information about the capabilities provided by IBM App Connect Enterprise, see features.

Choosing your IBM App Connect Enterprise edition and operation

mode
The capability and capacity provided by IBM App Connect Enterprise vary according to the operation
mode in which your integration servers are running, and your entitlement to run in a particular mode
depends on the edition of the product that you have purchased.

About this task

You can choose the mode of operation based on the functionality and capacity that you require. You
must ensure that your use and configuration of the product conforms to the license agreement that you
have purchased. Some features of IBM App Connect Enterprise have specific requirements, such as the
availability of an additional product, such as a database.
The following topics describe the features that are available, together with additional requirements and
restrictions:
• features
• “Operation modes” on page 3
• “Restrictions that apply in each operation mode” on page 5
For more information about the license requirements for each operation mode, see “License
requirements” on page 5.

2 IBM App Connect Enterprise 12.0: User Guide

Operation modes
The operation mode that you can use for your integration servers is determined by the license that you
purchase.
The following modes are supported:
• “Advanced mode” on page 3. All features are enabled and no restrictions or limits are imposed. This
mode is the default mode, unless you have the Developer Edition.
• “Nonproduction mode” on page 3. All features are enabled and no functional limits are imposed,
but you can use the product for evaluation, development, and test purposes only.
• “Nonproductionfree mode” on page 4. All features are enabled and no functional limits are
imposed, but you can use the product for development and functional testing purposes only (not for
performance, scalability, or security testing).
• “Developer mode” on page 4. All features are enabled, but you can use the product for evaluation,
development, and test purposes only. Developer Edition is limited to one message (transaction) per
second at the message flow level.
• “Standard mode” on page 4. All features are enabled. If you are using an integration node, you can
associate only one integration server with it, but the number of message flows that you can deploy to it
is unlimited.
Operation modes typically restrict the number of message flow nodes that are available, and integration
server capacity, but many features are available across all modes of operation. For an overview of the
main IBM App Connect Enterprise capabilities, see features.
You must ensure that your integration servers are running in the operation mode for which you have
purchased a license.
If you have purchased a license for the full package or the Standard Edition, your integration servers are
automatically created in advanced mode unless you specify the correct mode for your license.
Change the mode of your integration node to conform to your license if necessary; see “Changing the
operation mode” on page 86. You can also report the current mode of your integration node; see
“Checking the operation mode” on page 87.
The IBM App Connect Enterprise Toolkit remains the same in all modes. All the capabilities of the IBM
App Connect Enterprise Toolkit are available in all modes. If you try to deploy too many message flows
or integration servers for the mode, or try to use a message flow node that is not valid in the mode,
the operation is rejected, and an error message is displayed indicating the reason for the failure; see
“Restrictions that apply in each operation mode” on page 5. Restrictions for a given mode also apply
to the use of message flows generated by IBM App Connect Enterprise patterns.
If you intend to use the IBM App Connect Enterprise features that require MQ functionality, you can install
and use IBM MQ within the terms of your IBM App Connect Enterprise license. For more information
about using IBM MQ with IBM App Connect Enterprise, see “Installing IBM MQ” on page 96.

Advanced mode
In advanced mode, all features are enabled, and there are no operational limits on the creation of
integration servers or on the number of flows that are deployed to an individual integration server. If you
want to use all or most of the features available, your integration servers must operate in this mode, and
you therefore require the full license. If you do not specify another mode, your integration servers have
the mode set to the default value, which is advanced.

Nonproduction mode
In nonproduction mode, all features are enabled. You can use all available function, and no limits are
imposed on the number of resources that you can create or the rate at which messages can be processed.
The functions that are available in nonproduction mode are the same as in advanced mode, but
nonproduction mode can be used for evaluation, development, and test purposes only. When you are

Chapter 1. Planning your IBM App Connect Enterprise solution 3

 ready to move to a production environment, you will need to obtain the full IBM App Connect Enterprise
license and change your integration servers to advanced mode.

Nonproductionfree mode
In nonproductionfree mode, all features are enabled. You can use all available function, and no
limits are imposed on the number of resources that you can create or the rate at which messages can be
processed. The functions that are available in nonproductionfree mode are the same as in advanced
mode, but nonproductionfree mode can be used for development and functional testing purposes
only. For non-functional testing (including performance, scalability, and security testing), you must use
nonproduction mode and obtain a license for that mode. When you are ready to move to a production
environment, you will need to obtain the full IBM App Connect Enterprise license and change your
integration servers to advanced mode. For more information about license agreements, contact your IBM
representative.

Developer mode
In developer mode, all features are enabled. You can use all available function, and you are not limited
in the number of resources that you can create and maintain. IBM App Connect Enterprise for Developers
(Developer Edition) is provided for evaluation, development, and test purposes only.
Developer Edition is limited to one message (transaction) per second at the message flow level. Each
message flow is able to process one message per second, irrespective of the number of input nodes that
are attached to the message flow, or the number of additional instances. When using Developer Edition, if
a policy is deployed to increase the message rate throughput above one message per second, a message
is reported in the syslog and event log stating that the message rate cannot be changed in Developer
Edition. The policy that is deployed has no effect on the message rate.
You can download Developer Edition at no charge from https://www.ibm.com/marketing/iwm/iwm/web/
dispatcher.do?source=swg-wmbfd, and you are free to use it for as long as you require, within the terms
of the license. There is no expiry period for the Developer Edition license.
When you have installed Developer Edition, if you subsequently purchase a license and install the full
version of IBM App Connect Enterprise, any Developer mode integration servers that are started with
the full version are treated as Advanced mode integration servers. In this case, you must also modify the
operation mode of these integration servers by using the mqsimode command to reflect the license that
you have purchased. For more information, see “Changing the operation mode” on page 86.

Standard mode
In standard mode, all features are enabled. Use this edition if you expect to use all or most of the
features that are available, but intend to configure a limited environment because of low capacity
requirements.
You can use all the available functions, but are limited in the number of resources that you can create and
maintain. You can associate only one integration server with an integration node; for more information,
see “Restrictions that apply in each operation mode” on page 5. If you attempt to exceed the limits of
this mode, the deployment is rejected.

Development and unit test

Your license also covers use of the product for development and unit test purposes, but check the license
to ensure that you conform to any restrictions for development and unit test. You can view the license for
IBM App Connect Enterprise by visiting the Software license agreements search website. Search for "IBM
App Connect Enterprise" and choose the license that applies to the version you are using.
Contact your IBM representative if you want further details about license agreements, or if you want to
purchase additional licenses or change the type of license that you have purchased.

4 IBM App Connect Enterprise 12.0: User Guide

 Integration with Tivoli License Manager
If you use IBM Tivoli® License Manager to control and manage your licensed software products, you must
ensure that you choose the correct license for the IBM App Connect Enterprise edition that you have
purchased. For more information, see “Installing IBM License Metric Tool” on page 100.

Restrictions that apply in each operation mode

The operation mode in which you are running your installation of IBM App Connect Enterprise determines
how many integration servers you can use, and the purposes for which you can use the product.

Advanced mode
All features are enabled, and there is no limit to the number of integration servers or the number of
message flows that can be deployed to each integration server.
For more information about the features that are available in IBM App Connect Enterprise, see features.

Nonproduction mode
All features are enabled, and no limits are imposed on the number of resources that you can create or the
rate at which messages can be processed. The functions that are available in nonproduction mode are
the same as in advanced mode, but nonproduction mode can be used for evaluation, development,
and test purposes only.

Nonproductionfree mode
All features are enabled, and no limits are imposed on the number of resources that you can create or
the rate at which messages can be processed. The functions that are available in nonproductionfree
mode are the same as in advanced mode, but nonproductionfree mode can be used for development
and functional testing purposes only. For non-functional testing (including performance, scalability, and
security testing), you must use nonproduction mode and obtain a license for that mode.

Developer mode
All features are enabled for an unlimited time, but you can use the product for evaluation purposes
only (within the terms of the license). IBM App Connect Enterprise for Developers, which is also known
as Developer Edition, is restricted to processing one message (transaction) per second. For more
information, see “Operation modes” on page 3.

Standard mode
All features are enabled. If you are using an integration node, you can associate only one integration
server with it, but the number of message flows that you can deploy to it is unlimited.

License requirements
You must ensure that your use and configuration of the product conforms to the license agreement that
you have purchased.
The following list shows the IBM App Connect Enterprise operation modes that can be used with each of
the IBM App Connect Enterprise license agreements:
IBM App Connect Enterprise for Developers (Developer Edition)
developer mode
IBM App Connect Enterprise Standard Edition
standard mode
IBM App Connect Enterprise (unrestricted license)
advanced mode

Chapter 1. Planning your IBM App Connect Enterprise solution 5

 developer mode
standard mode
For more information, see “Operation modes” on page 3.
If you choose to change your license agreement from a full license to one of the specialized licenses, you
might find that your current configuration is no longer supported. For further details about what features
are available for each license, and how to configure your environment, see technical overview.
You can upgrade to the full license from another edition, if appropriate, by purchasing another license.
When you purchase a license for IBM App Connect Enterprise, your license entitles you to install and use
IBM MQ, which enables you to use the IBM App Connect Enterprise features that require MQ functionality.
For more information about using IBM MQ with IBM App Connect Enterprise, see “Installing IBM MQ” on
page 96.
You can view the full license for IBM App Connect Enterprise by visiting the Software license agreements
search website. Search for "IBM App Connect Enterprise" and choose the license that applies to the
version you are using.
You can view licenses after installation in your chosen language in directory install_dir/server/
license/. Terms and conditions are also supplied for third-party products that are used by IBM App
Connect Enterprise. The file containing these details is stored in the same license subdirectory when you
install one or more runtime components.
Contact your IBM representative if you want further details about license agreements, or if you want to
purchase additional licenses or change the type of license that you have purchased.

Installing IBM License Service and adding annotations for IBM App Connect
Enterprise containers
If you create your own container with IBM App Connect Enterprise, you must install an IBM License
Service operator and add annotations to your container to ensure that you comply with the IBM licensing
requirements.
License Service is required for monitoring and measuring license usage of IBM App Connect Enterprise in
accordance with the pricing rule for containerized environments. You must deploy License Service on all
clusters where IBM App Connect Enterprise is installed. Manual license measurements are not allowed.
License annotations let you track usage based on the limits defined on the container, rather than on the
underlying machine. You configure your clients to deploy the container with specific annotations that the
IBM License Service then uses to track usage.
The integrated licensing solution collects and stores the license usage information, which can be used
for audit purposes and for tracking license consumption in cloud environments. The solution works in the
background and does not require any configuration. Only one instance of the License Service is deployed
per cluster regardless of the number of Cloud Paks and containerized products that you have installed on
the cluster.
You must deploy License Service on each cluster where IBM App Connect Enterprise is installed. License
Service can be deployed on any Kubernetes cluster. For more information about License Service, including
how to install and use it, see the License Service documentation.
To ensure license reporting continuity for license compliance purposes, ensure that License Service
is successfully deployed and periodically verify whether it is active. For example, to validate whether
License Service is deployed and running on the cluster, you can log in to the cluster and run the following
command:

`kubectl get pods --all-namespaces | grep ibm-licensing | grep -v operator`

The following response is a confirmation of successful deployment:

1/1 Running

6 IBM App Connect Enterprise 12.0: User Guide

For more information about the supported environments and installation instructions, see the ibm-
licensing-operator page on GitHub. For further information about IBM container licenses, see the IBM
Container Licenses page on Passport Advantage.
IBM License Service is installed on the Kubernetes cluster where the IBM App Connect Enterprise
container is deployed, and pod annotations are used to track usage. Clients must be configured to deploy
the pod with specific annotations that the IBM License Service uses. Based on your entitlement and
capabilities deployed within the container, use one or more of the following annotations:
• “IBM App Connect Enterprise” on page 7
• “IBM App Connect Enterprise for non-production” on page 7
• “IBM App Connect Enterprise for Developers” on page 8
Each of your annotations must contain a single product metric.

IBM App Connect Enterprise

Use one of the following annotations for IBM App Connect Enterprise to specify your chosen product
metric, which can be either VIRTUAL_PROCESSOR_CORE or PROCESSOR_VALUE_UNIT, but not both:
VPC:

productName: "IBM App Connect Enterprise"

productID: "b8b6252aa88b4cd996c4b7aca350d2fe"
productMetric: "VIRTUAL_PROCESSOR_CORE"
productChargedContainers : "All"

PVU:

productName: "IBM App Connect Enterprise"

productID: "b8b6252aa88b4cd996c4b7aca350d2fe"
productMetric: "PROCESSOR_VALUE_UNIT"
productChargedContainers : "All"

IBM App Connect Enterprise for non-production

Use one of the following annotations for IBM App Connect Enterprise for non-production to specify your
chosen product metric, which can be VIRTUAL_PROCESSOR_CORE, PROCESSOR_VALUE_UNIT, or FREE:
VPC:

productName: "IBM App Connect Enterprise for non-production"

productID: "eb5b5e73f62b4dcf8c434c6274a158a7"
productMetric: "VIRTUAL_PROCESSOR_CORE"
productChargedContainers : "All"

PVU:

productName: "IBM App Connect Enterprise for non-production"

productID: "eb5b5e73f62b4dcf8c434c6274a158a7"
productMetric: "PROCESSOR_VALUE_UNIT"
productChargedContainers : "All"

FREE:

productName: "IBM App Connect Enterprise for non-production"

productID: "eb5b5e73f62b4dcf8c434c6274a158a7"
productMetric: "FREE"

You cannot specify multiple product metrics in the same annotation.

Chapter 1. Planning your IBM App Connect Enterprise solution 7

 IBM App Connect Enterprise for Developers
Use the following annotation for IBM App Connect Enterprise for Developers:

productName: "IBM App Connect Enterprise for Developers - FREE"

productID: "53ec37b661cb40e693639822785f02f2"
productMetric: "FREE"

Planning an IBM App Connect Enterprise environment

When you start to plan your IBM App Connect Enterprise environment, you must first consider the design
of your system infrastructure. A major consideration when you are planning to use IBM App Connect
Enterprise is how it will fit into your overall system architecture, and it is important to understand the
movement of data around your whole system.

About this task

It is also important to understand the high-level goals of the system that you are building, and to be clear
about the functional requirements. For example, IBM App Connect Enterprise has extremely powerful
routing and transformation capabilities, but it is not designed to function as an application server whose
primary function is data processing that involves a high number of complex calculations.
Another important consideration is whether you require a highly available (HA) system that can withstand
the failure of an individual integration server or integration node. For more information about high
availability, see “Configuring integration nodes for high availability” on page 120.
The capability and capacity of your integration nodes is partly determined by the operation mode in which
the integration nodes are running, and this is determined by the IBM App Connect Enterprise license that
you have purchased. For more information, see features and “Operation modes” on page 3.
The following topics describe these factors.

Planning the high-level infrastructure

When you are planning to use IBM App Connect Enterprise, consider your complete system of products as
a whole and ensure that the flow of data throughout the system is carefully planned.

About this task

It is important to understand how IBM App Connect Enterprise will fit into the overall system of products
in your business, and to be clear about the movement of data around the whole system. It is also
important to understand the high-level goals of the system and your functional requirements, so that you
can ensure that you are planning to use IBM App Connect Enterprise in a way that will gain the maximum
benefit. For example, IBM App Connect Enterprise has powerful routing and transformation capabilities,
but it is not designed to function as an application server whose primary function is data processing with a
high number of complex calculations. Therefore, it is important to fully understand the role of the product
within your overall IT system, in order to use it to its full advantage.
Some common considerations are listed here to assist with your planning.
• Consider whether you need to install IBM MQ to access more IBM App Connect Enterprise functions.
For example, if you want global transaction management in your solution. For more information
about what functions require access to IBM MQ, see “IBM App Connect Enterprise features requiring
supplementary products” on page 9.
• If you are planning to use databases, check the database documentation for information about
connections, and the limits or restrictions that might apply. For example, there might be a limit to the
maximum number of connections that are allowed at any one time.
The following topics describe some additional factors to consider when you plan your implementation of
IBM App Connect Enterprise:

8 IBM App Connect Enterprise 12.0: User Guide

• “IBM App Connect Enterprise features requiring supplementary products” on page 9
• “Naming conventions for integration nodes and associated resources” on page 10

IBM App Connect Enterprise features requiring supplementary products

IBM App Connect Enterprise has no mandatory prerequisites; however, a subset of capabilities require
access to other products.
These features affect the main IBM App Connect Enterprise product operations, not your applications.
For information about how these products integrate with IBM App Connect Enterprise, see technical
overview. For more information about IBM App Connect Enterprise features that have specific
requirements, such as a particular mode of operation, product licenses, or access to additional products,
see features.
The following table shows the products and systems that are required for specific capabilities in IBM App
Connect Enterprise:

Capabilities Required system

IBM MQ capabilities: IBM MQ
• MQ nodes
• MQ FTE nodes
• CD nodes
• Sequence nodes
• Timeout nodes
• Aggregate nodes
• Collector nodes
• SAP nodes (if transactional support is required in
the flow)
• Record-Replay capability
• Global transaction support
• HTTP proxy servlet
• Multi-instance integration nodes

Database capabilities: For a full list of compatible databases, review the

Detailed System Requirements in the IBM App
Database nodes
Connect Enterprise system requirements for your
operating system.
Security profiles Any of the following systems or protocols:
Lightweight Directory Access Protocol (LDAP)
Tivoli Federated Identity Manager (TFIM)
Microsoft Active Directory (MSAD)

Review the following sections to learn what is required to use these capabilities.

IBM MQ
On distributed systems, IBM MQ is not provided as part of the IBM App Connect Enterprise installation
package; however, when you purchase a license for IBM App Connect Enterprise, your license entitles you
to install and use IBM MQ. If you choose to use the IBM App Connect Enterprise features that require MQ
functionality, you can install and use IBM MQ within the terms of the license. You can install IBM MQ at
any time.

Chapter 1. Planning your IBM App Connect Enterprise solution 9

 The following functions require access to system queues on a queue manager that is specified on the
integration node:
• Sequence nodes
• Timeout nodes
• Aggregate nodes
• Collector nodes
• Record-Replay capability
• CD nodes
• HTTP proxy
If you want to use these functions, you must specify a queue manager for the integration node, and then
explicitly define a set of MQ objects for that queue manager. For more information, see command.
For information about the supported versions of IBM MQ, see the Detailed System Requirements in the
IBM App Connect Enterprise system requirements for your operating system.

Database capabilities
You can connect a number of databases with IBM App Connect Enterprise. To learn more about
databases, see “Databases overview” on page 1131.

Security profiles
Security profiles form part of optional message flow security. To learn more about security profiles, see
“Security profiles” on page 2552.

Naming conventions for integration nodes and associated resources

Establish a naming convention for all the IBM App Connect Enterprise resources in your integration node
environment to ensure that names are unique, and that users that create new resources can be confident
of not introducing duplication or confusion.
Consider the names that you use for your integration nodes and resources:
Integration nodes
When you create an integration node, give it a name that is unique within your integration node
environment. You must use the same name for that integration node when you create it on the system
in which it is installed, by using the command mqsicreatebroker. Integration node names are
case-sensitive, except on Windows platforms.
Databases
Ensure that the databases that you use for application data, which are accessed through your
deployed message flows, are uniquely named throughout your network, so that confusion and errors
are avoided by all your users.
Integration servers
Each integration server name must be unique within an integration node.
Message flows and message processing nodes
Each message processing node must be unique within the message flow it is assigned to. Nodes
within the same message flow must not share the same name, even if they are of different types. For
example, if you include two MQOutput nodes in a single message flow, provide a unique name for
each one.
Message flow names must be unique within the integration node. All references to that name are
always to the same message flow. If you assign the same message flow to more than one integration
node, you must ensure that you maintain unique message flow names across those integration nodes.

10 IBM App Connect Enterprise 12.0: User Guide

 Message sets and messages
Each message name must be unique within the message set to which it belongs.
Message set names must be unique within the integration node. All references to that name are
always to the same message set. If you assign the same message set to more than one integration
node, you must ensure that you maintain unique message set names across those integration nodes.
IBM MQ objects
If you are using IBM MQ services and objects with your IBM App Connect Enterprise resources, you
must consider what conventions to adopt for IBM MQ object names. If you already have an IBM MQ
naming convention, use a compatible extension of this convention for IBM App Connect Enterprise
resources.
Ensure that every queue manager name is unique within your network of interconnected queue
managers, even if some queue managers are not in your IBM App Connect Enterprise network. Unique
naming ensures that each queue manager can unambiguously identify the target queue manager that
a message must be sent to, and that IBM App Connect Enterprise applications can also interact with
IBM MQ applications.
IBM MQ supports a number of objects that are defined to queue managers. These objects (queues,
channels, and processes) also have naming conventions and restrictions. For more information
about IBM MQ naming conventions, see the topic Naming IBM MQ objects in the IBM MQ product
documentation.

Business planning
Consider the role of IBM App Connect Enterprise in your overall business solution, and understand the
potential benefits and limitations based on your functional and business requirements.

About this task

It is important to understand the capability and capacity that you require from your system. The capability
and capacity of your integration nodes are partly determined by the operation mode in which they are
running, and this is determined by the IBM App Connect Enterprise license that you have purchased. For
information about the features and modes of operation provided in each edition, see “Choosing your IBM
App Connect Enterprise edition and operation mode” on page 2.
It is also important to consider the most suitable technology for your business; this varies between
projects and organizations, and there are various factors to consider when assessing your requirements:
• The pool of development skills available. For example, if your developers are already skilled in the use
of ESQL, you might want to continue using this transformation technology. However, if you have strong
Java™ skills, the JavaCompute node might be the better choice, rather than having to teach your Java
developers ESQL.
• The ease with which you can teach developers a new development language. For example, if you have
many developers it might be not be viable to teach all of them ESQL, and you might choose instead to
educate only a few people who can then develop common functions or procedures.
• The skills of individual people. If your developers have relatively little experience with IBM App Connect
Enterprise, you might find that the graphical interface provided by the Mapping node is more suitable
than other transformation technologies.
• Asset reuse. If you are an existing user of IBM App Connect Enterprise, you might already have large
amounts of ESQL code that you would like to reuse. You might also have other resources that you want
to reuse, such as Java classes for key business processing, style sheets, or mappings. You might want
to use these as the core of message flow processing and extend the processing with one of the other
technologies.
• Performance. If message throughput is a prime consideration, you might choose to use ESQL or Java.
For more information about designing your system for optimum performance, see “Message flow design
and performance” on page 2689 and “Code design and performance” on page 2690.

Chapter 1. Planning your IBM App Connect Enterprise solution 11

 • Solution scalability, cost and flexibility. You might have an existing network infrastructure that you want
to use, or you might want to take advantage of IBM App Connect Enterprise cloud capabilities. For more
information on choosing a solution for your installation, see “Cloud overview” on page 12.
For more information about factors to consider when planning your IBM App Connect Enterprise solution,
see the following topics:
• “Planning an IBM App Connect Enterprise environment” on page 8
• “Planning the high-level infrastructure” on page 8
• “Understanding your data and message processing requirements” on page 1
• “Performance planning” on page 16
• “Planning for security” on page 17

Cloud overview
When you are deciding on your environment for IBM App Connect Enterprise, consider your requirements
and how you might want to implement a cloud solution.
Depending on your requirements, you might benefit from reduced operating costs and deployment
flexibility for IBM App Connect Enterprise when compared to a static installation.
Using a cloud vendor usually has a higher operating cost than using a static network-based solution, but
less upfront capital is required and parts of the infrastructure are automated. Review the following graph
as an example of how this can reduce costs overall:

While the cost equivalent in computing power is slightly higher than using your own server, you pay for
as much resource as you use, thereby reducing the average cost over a period of time. There are many
different financial models for cloud vendors that offer different services.
You can use your own cloud solution, if you have the appropriate skills within your organization to ensure
maximum cost-efficiency of your resource use.

Types of cloud
You can choose how much control you retain over your cloud installation by deciding whether you want
your solution to be on premises or off premises, and whether that cloud is public or private.
• An on-premises (or private) cloud is accessed and used by solely one organization. If you use a private
cloud, you maintain absolute control of the maintenance and configuration, but setting up a private
cloud requires significant technical skills, scrutiny of security implementation, time, and resources.

12 IBM App Connect Enterprise 12.0: User Guide

• An off premises (or public) cloud is a cloud that is available to multiple organizations, who each use
parts of the cloud privately or publicly. There is little to no architectural difference to public or private
clouds, except for extra and different security considerations for your services. The maintenance,
configuration, and security of the hosting servers are controlled by the hosting vendor.
• A hybrid cloud service contains both on premises and off premises elements. For example, you might
host client-sensitive data on premises in a private cloud, but connect to an application that is hosted in
a public cloud that processes some of that data.
See the following diagram for a visual representation of the relationship between these concepts:

You can use IBM App Connect Enterprise in any of these configurations. For example, you might have a
traditional installation of IBM App Connect Enterprise privately on premises, but deploy some of your
integration servers in the cloud.

Cloud technologies
By using cloud technologies, you can choose to abstract parts of your network setup so that the physical
components are instead virtual. You can then manipulate the non-physical components to meet the
needs of your solution without the associated cost overheads of a physical change, such as changing
physical servers or operating system.
This abstraction is collectively known as XaaS or Everything as a Service, and you can create any part of
XaaS at different levels of system architecture.
For a cloud installation of IBM App Connect Enterprise, you can benefit from:
• Infrastructure as a Service (IaaS). IaaS is used and maintained by system architects, or the equivalent in
your organization.
• Platform as a Service (PaaS). PaaS is used and maintained by application developers, or the equivalent
in your organization.

Chapter 1. Planning your IBM App Connect Enterprise solution 13

 Review these topics to learn about each level of XaaS and the advantages of using each layer with IBM
App Connect Enterprise.
Note: Each level of XaaS is independent. You do not have to use any of these concepts together in an
installation.
You can still install IBM App Connect Enterprise by using the provided installation images to a private file
system. You might want to do this if you have a small-scale solution that is unlikely to change in size. To
review what is required for a standard installation, see “Installing IBM App Connect Enterprise” on page
69.

Infrastructure as a Service
Learn what Infrastructure as a Service (IaaS) is, and how you might benefit from using IaaS with IBM
Integration Bus.
Infrastructure as a Service acts as the equivalent to computing hardware by using virtual machines. An
IaaS configuration reduces the cost overhead of managing many servers, whether on premises or off
premises, as you do not need to manually configure each system. For example, you can apply security
patches to all virtual machines simultaneously by using a script.
The advantage of using IaaS with IBM App Connect Enterprise is to create a scalable solution that does
not require increasing configuration as it grows in size. By configuring scripts, you can scale and change
attributes as required, instead of manually recoding the system infrastructure.
You can use IaaS on premises or off premises, but the primary benefit of IaaS is the ability to use a
vendor to reduce the costs of maintaining and configuring the physical machines. If you want to use IaaS
on premises, consider the skill availability of system architects in your organization to configure your
architecture, and the associated costs.
The benefits of using an IaaS configuration are:
• Flexible (or elastic) hosting. An IaaS provider can provision new virtual machines for you quickly.
• If you use an IaaS provider, remove the responsibility and associated effort of applying fixes, security
patches, and other upgrades.
• Removes or reduces capital expenditure on hardware and human resources.
Considerations for using IaaS are:
• If you use IaaS without PaaS, the lack of dynamic scalability: you must predict your peak usage in
advance.
• Choosing an IaaS vendor with the right cost model for your usage.
• The capability of the vendor to meet your ongoing business requirements.
• Security and data compliance, if you have restrictions for data use and sharing.
• Dependency on the IaaS vendor for uptime and potentially recovery.
• Requires new and different security measures.
For an example of an IaaS-based IBM App Connect Enterprise solution, review the following business
context:
A retail company uses an IBM App Connect Enterprise solution that uses the IBM Retail Pack for its
transaction system. The company knows that its peak message processing period is December. Their
previous solution used their own on-premises servers, which met the peak demand. However, during
the rest of the year, the full capacity of the servers was not used, but the company still had to pay the
associating operating and maintenance costs for the entire year.
The retail company changes its infrastructure to an IaaS solution. The retail company now pays an IaaS
provider for public cloud servers. The retail company pays the IaaS vendor monthly, by capacity required.
The company pays for more IaaS capacity for December only to meet its peak demands. As the company
now use less resources across most of the year, this solution is a cheaper option.

14 IBM App Connect Enterprise 12.0: User Guide

The graph shows how a static solution remains the same cost throughout one year, but the IaaS solution
cost is consistently lower, except during peak usage. The result is that the retail company has capacity
that it requires during its peak period, but does not continue to pay for that extra capacity for the rest of
the year.

Chef
Chef software is an open source configuration management tool that you can use to create parts of an
Infrastructure as a Service (IaaS). You can use Chef scripts to provision an IBM App Connect Enterprise
installation.
Chef scripts, which are called recipes, are made of reusable definitions that are written in the Ruby
programming language. Chef recipes that perform related functions are grouped in a single container,
called a cookbook. Cookbooks and recipes automate common infrastructure tasks. The recipe
definitions describe what your infrastructure consists of, and how each part of your infrastructure is
deployed, configured, and managed. Chef applies these definitions to servers, to produce an automated
infrastructure.
By using Chef, you can create scalable infrastructure with minimal configuration to maintain. Chef scripts
form part of a recipe for your infrastructure configuration that is understood by multiple systems, services,
and languages. By using Chef to configure your infrastructure deployment, you do not have to rewrite
code if you change part of the underlying infrastructure, such as changing data service provider.
To learn more about Chef concepts, see the online Chef documentation About Cookbooks - Chef Docs.

Platform as a Service
Learn what Platform as a Service (PaaS) is, and how you might benefit from using PaaS with IBM App
Connect Enterprise.
A PaaS cloud configuration automates the execution environment and solution deployment. For example,
acting as an operating system that supports IBM App Connect Enterprise. A typical PaaS provider consists
of many servers that each provide customized environments, and can dynamically allocate resources to
that environment where and when they are required.

Chapter 1. Planning your IBM App Connect Enterprise solution 15

 Applications are deployed into this environment, and are often charged by usage or capacity, which
means that you pay only for as much as you use or specify, which can greatly reduce operating costs.
The benefits of using a PaaS configuration are:
• Reconfiguring and maintenance of the environment is faster and requires significantly less effort.
• If you use a PaaS provider, maintenance and optimization are provided, requiring less developer time.
• Dynamically scalable. PaaS automatically increases or decreases resources, which are based on
demand. You usually pay only for the resources that are used.
Considerations for using PaaS are:
• Choosing a PaaS vendor with the right cost model for your usage.
• Whether the PaaS provider has any restrictions on what type of content and applications are allowed.
• What frameworks, languages and databases are supported.
• Vendor lock-in, and choosing standard or proprietary technologies. If your provider uses proprietary
technologies, you might find it harder to switch vendors.
• Security and data compliance, if you have restrictions for data use and sharing.
• Dependency on the PaaS vendor for aspects of security and uptime.
• Requires new and different security measures.

Performance planning
When you design your IBM App Connect Enterprise environment and the associated resources, the
decisions that you make can affect the performance of your applications.

About this task

If you are planning to create and maintain a small, stand-alone system with limited requirements for
availability and performance, it is possible to achieve this relatively quickly. However, if you are planning
a large or complex system, or if you have specific requirements for high availability or performance, it is
worth taking time to understand the factors that can influence your design and the techniques that you
can use to optimize it. As a starting point, consider the following aspects of your system and understand
how these factors can influence performance:
Message flows
A message flow includes an input node that receives a message from an application over a particular
protocol; for example, IBM MQ. The message must be parsed by the input node, and the performance
impact of this parsing varies according to the parser that is used and the number of parses required.
You can reduce the impact of parsing by using some optimization techniques such as parsing
avoidance or partial parsing. For more information about parsing, see “Parsing and message flow
performance” on page 2697.
The number and length of message flows have implications for performance, and it is important to
keep the number of nodes to a minimum. See “Message flow design and performance” on page 2689
for more information about optimizing message flow performance. Other aspects of processing in
a message flow that might affect performance are the amount, efficiency, and complexity of ESQL,
access to databases, and how many message tree copies are made. For more guidance about these
factors, see “Code design and performance” on page 2690.
It is also important to consider how you split your business logic; how much work should the
application do, and how much should the message flow do? Every interaction between an application
and a message flow involves I/O and message parsing, and therefore adds to processing time. Design
your message flows, and design or restructure you applications, to minimize these interactions.
Messages and message models
The type, format, and size of the messages that are processed can have a significant effect on the
performance of a message flow. For example, if you process persistent messages, they must be stored
for safekeeping.

16 IBM App Connect Enterprise 12.0: User Guide

 If you do not plan to interrogate the structure, you can use the BLOB domain.
If you are working with general text or binary messages, then you need to create a DFDL (or MRM)
model to describe the message. The organization of the model can have a significant effect on
performance. For fields that are choices, are optional, or are in arrays, the model must identify the
field as efficiently as possible. Use tags (named initiators in DFDL) if they are available. To resolve a
choice, DFDL provides a direct dispatch mechanism, which avoids parsing each branch in turn if there
is a field that indicates which branch to take. If you are using a DFDL discriminator, ensure that the
discriminator is placed so that it is evaluated as early as possible. While regular expressions can be
used to identify and extract fields, they are generally slower than other techniques.
If you are working in XML, be aware that it can be verbose, and therefore produce large messages.
However, XML message content is easier to understand than other formats, such as binary fixed-
length format.
For more information about these factors, see Performance considerations for regular expressions in
TDS messages.
Integration node configuration
You can create and configure one or more integration nodes, on one or more computers, and for
each integration node you can create multiple integration servers, and multiple message flows. Your
configuration decisions can influence message flow performance, and how efficiently messages can
be processed.
For more information about these factors, see “Tuning the integration node” on page 2762, and
“Optimizing message flow throughput” on page 2763.

Planning for security

It is important to be aware of security issues when you are planning to install and use IBM App Connect
Enterprise.

About this task

On Linux® and UNIX systems, you must complete security tasks before you install IBM App Connect
Enterprise. On Windows systems, security tasks are completed during and after installation.
After installation, refer to one of the following documents for further security considerations:
• For Windows, Linux and UNIX systems, see “Creating user IDs” on page 2633.
For an introduction to various aspects of security, see “Security overview” on page 2491.

Replicating your environment for multiple users

You can ensure that your environment is more easily reproducible by using scripting and virtualization, in
addition to documentation.

About this task

You can create environment instances by using Chef scripts to automate installation. For more
information about Chef, see “Chef” on page 15.

Procedure
1. Download the IBM App Connect Enterprise installation images.
2. Download the Chef Cookbook for IBM App Connect Enterprise from GitHub.
3. Add the IBM App Connect Enterprise cookbook to the Chef server.
Alternatively, if you are using Chef solo, add the cookbook to your file system.
4. Set the recipe attributes to point to the FTP or HTTP server.

Chapter 1. Planning your IBM App Connect Enterprise solution 17

 5. Run the Chef scripts.

18 IBM App Connect Enterprise 12.0: User Guide

Chapter 2. Migrating
To migrate an integration server or integration node from IBM App Connect Enterprise 11.0 or IBM
Integration Bus 10.0 to IBM App Connect Enterprise 12.0, plan your migration strategy, perform pre-
migration tasks, migrate your domain components, or server configuration and resources, then complete
post-migration tasks.

Before you begin

Tip: Check for migration information updates on the IBM App Connect Enterprise support web page.

About this task

Video: IBM App Connect Enterprise - Migration and Extraction
In this demo, Ben Thompson gives an overview of migrating from IBM Integration Bus V10 to IBM App
Connect Enterprise V11.
Note:
This video was created for App Connect Enterprise 11.0, but also applies to App Connect Enterprise 12.0.

Preparing for migration

Plan the order and extent of the migration of components and resources to IBM App Connect Enterprise
12.0.

About this task

To prepare for migration, complete the following steps.

Procedure
1. Check that your current installation of IBM App Connect Enterprise Version 11.0 or IBM Integration
Bus 10.0 is at a supported level for migration (see “Supported migration paths” on page 20).
For the latest details of all supported levels of hardware and software, see the IBM App Connect
Enterprise system requirements website.
2. Some function that was available in IBM Integration Bus is not currently available in IBM App Connect
Enterprise 12.0; elements of this function are to be made available in fix pack updates. For details of
which commands, policy types, and other resources are unavailable in IBM App Connect Enterprise at
this fix pack release, see the Frequently asked questions about website.
3. Determine your migration priorities by following the steps in “Migration planning” on page 20.
4. Review the options that are available to install IBM App Connect Enterprise 12.0 components on the
same computer as components from IBM App Connect Enterprise Version 11.0 or IBM Integration Bus
10.0 (see “Coexistence of IBM App Connect Enterprise 12.0 with previous versions” on page 70).
5. Learn about new and changed function in Version 12.0 by reading What's new in ?.
These changes might affect how you want to use your migrated components in the future.
6. Review the IBM MQ configuration options that you can include in your migration plan in “IBM MQ and
migration to IBM App Connect Enterprise 12.0” on page 28.
These changes might affect your choice of integration node migration option.
7. Review the options for migrating your integration nodes and integration servers, and decide whether
to use extract migration or parallel migration (see “IBM App Connect Enterprise migration options” on
page 29).

© Copyright IBM Corp. 2016 19

 8. Review the technical changes in behavior in Version 12.0 in “Behavioral changes in Version 12.0” on
page 22.
These changes might affect your post-migration development tasks.
9. Check the requirements for other products on which Version 12.0 components might depend.
If you configured your message flows to use external resources, such as databases or event
monitoring applications, you might have to modify your configuration. You can find details of supported
versions of complementary products on the IBM App Connect Enterprise system requirements web
page.

What to do next
After you plan your migration, complete the pre-migration tasks by following the instructions in
“Performing pre-migration tasks” on page 41.

Supported migration paths

You can migrate to IBM App Connect Enterprise 12.0 from IBM App Connect Enterprise Version 11.0 and
IBM Integration Bus 10.0.
Note: For the latest details of all supported levels of hardware and software, see the IBM App Connect
Enterprise system requirements website.
You can migrate from IBM App Connect Enterprise 11.0 or IBM Integration Bus 10.0 to either the
Advanced Edition or Standard Edition of IBM App Connect Enterprise 12.0; do not migrate integration
nodes or servers to the Developer Edition.
You can use either parallel or extract migration to migrate integration nodes and managed integration
servers to IBM App Connect Enterprise 12.0, as described in “Performing parallel migration for an
integration node ” on page 61 and “Performing extract migration of an integration node or integration
server” on page 57.
Independent integration servers that were created in IBM App Connect Enterprise 11.0 can be started
in IBM App Connect Enterprise 12.0 without the need to migrate them or their resources. However,
integration server work directories are typically created as transient rather than long-term artifacts, and
many users prefer to rebuild them when moving from one version to another.
You can use the IBM Integration Explorer view of the IBM App Connect Enterprise Toolkit to add
connections for integration servers and integration nodes. IBM App Connect Enterprise Toolkit Version
12.0 supports Version 12.0 integration servers and integration nodes only. Connections to integration
servers and integration nodes that are running on previous releases are not supported.

Migration planning
The order in which you migrate your IBM App Connect Enterprise 11.0 or IBM Integration Bus 10.0
environment depends on whether your priority is to include new development features, take advantage of
new operational features, or simply implement a fully supported version of IBM App Connect Enterprise
12.0.
If you are migrating from IBM Integration Bus 10.0, your existing environment might consist of any of the
following components:
• Integration nodes that support production applications
• Build systems that create deployable resources from the development source files
• Integration nodes that are used for testing applications
• Integration nodes that are used for developing applications
• Instances of the IBM Integration Toolkit
The order in which you migrate your environment to IBM App Connect Enterprise 12.0 is likely to depend
on which of the following factors is most important to you:

20 IBM App Connect Enterprise 12.0: User Guide

• “Supported version or new operational features” on page 21
• “New application features” on page 21
In both circumstances, you can use parallel migration. If you are migrating an integration server, you can
use the mqsiextractcomponents command to migrate the configuration and resources that exist for
your integration server to IBM App Connect Enterprise 12.0.

Supported version or new operational features

If your priority in migrating to IBM App Connect Enterprise 12.0 is simply to have an environment that is
at a fully-supported version of IBM App Connect Enterprise 12.0, and you do not need to use any of the
new Version 12.0 features immediately, there is a minimum number of steps you must complete.
If your priority in migrating to IBM App Connect Enterprise 12.0 is to use the new Version 12.0
operational features, you can update your integration nodes first. You can use existing development
environments and application build processes, and deploy your existing BAR files until you are ready to
migrate your development resources.
In either scenario, you migrate the components of your environment in the following order:
1. Migrate the integration nodes that support your test environment.
2. Implement new Version 12.0 operational functionality on your test environment or, at a minimum,
update existing operational functionality:
• If you are using IBM Integration Explorer in your existing IBM Integration Bus environment, define
new operational procedures that use the web user interface. You cannot use previous versions of
IBM Integration Explorer to administer IBM App Connect Enterprise 12.0.
• If you are using scripts to administer your existing environment, update any scripts that use
commands that connect to integration nodes. The parameters in IBM Integration Bus 10.0 that are
used by commands that connect to integration nodes have changed in Version 12.0.
3. Migrate the integration nodes that support your production environment.
4. Implement new Version 12.0 operational functionality on your production environment or, at a
minimum, update existing operational functionality.
5. If you have any integration nodes that support your development environment, migrate these
integration nodes to Version 12.0.
6. Update your build system to create Version 12.0 deployable resources. If required, update build
scripts to take advantage of new Version 12.0 operational functionality but, at a minimum, update any
scripts that use commands that connect to integration nodes.
7. Install IBM App Connect Enterprise 12.0 on your developer workstations. If you cannot migrate all
developer workstations at the same time, you must create separate development streams. You cannot
use Version 12.0 development tools to build applications for an environment that is running a previous
version of IBM App Connect Enterprise or IBM Integration Bus.
8. Import development resources from your previous Toolkit.
To migrate integration nodes, use parallel migration (see “IBM App Connect Enterprise migration options”
on page 29).
When you have imported all the development resources, you can uninstall the previous versions of IBM
Integration Toolkit, and any integration nodes that you do not want to migrate.

New application features

If your priority in migrating to IBM App Connect Enterprise 12.0 is to develop applications that take
advantage of new functions and features in Version 12.0, you can install a new development environment
alongside your existing development environment, and create new build, test, and production
environments to support your Version 12.0 development.
In this scenario, you migrate the components of your environment in the following order:

Chapter 2. Migrating 21
 1. Install IBM App Connect Enterprise 12.0 on your developer workstations. To maintain existing
applications in your existing environment while you are building new applications for Version 12.0,
you must run two development streams. You cannot use Version 12.0 development tools to build
applications for an environment that is running a previous version of IBM App Connect Enterprise or
IBM Integration Bus.
2. If you are updating an existing application, import development resources from your previous Toolkit.
3. Develop applications that take advantage of the Version 12.0 features.
4. Create a new build system that creates Version 12.0 deployable resources. You can use build scripts
from your previous version but you must update any scripts that use commands that connect to
integration nodes. The parameters in IBM Integration Bus 10.0 that are used by commands that
connect to integration nodes have changed in Version 12.0.
5. Create one or more IBM App Connect Enterprise 12.0 integration nodes to support the testing of the
Version 12.0 applications.
6. Update existing operational functionality:
• If you are using IBM Integration Explorer in your existing IBM Integration Bus environment, define
new operational procedures that use the web user interface. You cannot use previous versions of
IBM Integration Explorer to administer IBM App Connect Enterprise 12.0.
• If you are using scripts to administer your existing environment, update any scripts that use
commands that connect to integration nodes.
7. Deploy Version 12.0 applications to the Version 12.0 testing environment as required.
8. Create one or more IBM App Connect Enterprise 12.0 integration nodes to support production use of
the Version 12.0 applications.
9. Deploy Version 12.0 applications to the Version 12.0 production environment as required.
10. Migrate or deprecate applications from the original environment as required.
This type of migration is known as parallel migration (see “IBM App Connect Enterprise migration
options” on page 29).
When all applications are migrated to Version 12.0, you can uninstall the original environment.

Behavioral changes in Version 12.0

Depending on your current version of IBM Integration Bus or App Connect Enterprise, IBM App Connect
Enterprise 12.0 might introduce technical changes in behavior. These changes might affect your post-
migration development tasks.
Review the following changes to see how your post-migration development tasks might be affected:
• “Platform support” on page 23
• “Policies control and update message flow and message flow node properties” on page 23
• “Nodes that are no longer available” on page 23
• “IBM App Connect Enterprise 12.0 REST administration API (REST API) Version 2 is available to issue
administration commands” on page 23
• “Keystore format for administration security” on page 24
• “Additional options for administration security” on page 24
• “Administration scripts might need to be updated” on page 24
• “Publication of statistics to the web user interface is enabled by default” on page 25
• “UUIDs are not assigned to the integration node, integration server, application, or message flow
components” on page 25
• “Message flow monitoring” on page 25
• “LDAP authentication and local passwords” on page 25.
• “HTTPConnector and HTTPSConnector policies” on page 26

22 IBM App Connect Enterprise 12.0: User Guide

Platform support
IBM App Connect Enterprise 12.0 is available on:
• Windows
• Linux
• AIX®
For more information about the operating systems that are supported, see IBM App Connect Enterprise
12.0 system requirements.

Policies control and update message flow and message flow node properties
In IBM Integration Bus 10.0, configurable services were used to control and update connection
properties and other operational properties of message flows and message flow nodes at run time. In IBM
App Connect Enterprise 12.0, you can use policies for these tasks.
You can migrate your existing configurable policies by using the mqsiextractcomponents command. If
you are performing parallel migration, you need to create policies to replace your configurable services.
For more information, see “Overriding properties at run time with policies” on page 324.

Nodes that are no longer available

Your message flows from earlier versions work in IBM App Connect Enterprise 12.0. However, a number
of message flow nodes are not available in Version 12.0; if your earlier message flows include them,
consider reworking them.
The following nodes are not available in IBM App Connect Enterprise 12.0:
• DataDelete node
• DataInsert node
• DataUpdate node
• Extract node.
• Mapping node from WebSphere® Message Broker Version 7.0 and earlier versions
• MQOptimizedFlow node
• Real-timeOptimizedFlow node
• Warehouse node
If you try to use a message flow that contains any of these nodes, the message flow does not start and
message BIP2355 is written to the syslog. The message mapping (.msgmap) on these nodes can be
viewed but they cannot be deployed to the run time environment in IBM App Connect Enterprise 12.0.
For more information, see Built-in nodes.

IBM App Connect Enterprise 12.0 REST administration API (REST API) Version 2 is
available to issue administration commands
IBM App Connect Enterprise 12.0 does not include the IBM Integration API. Instead, you can use
the REST API (Version 2) that is provided in IBM App Connect Enterprise 12.0 to issue administration
commands.
For more information, see “Managing resources by using the administration REST API” on page 334.

Web user interface extended to support administration tasks

IBM App Connect Enterprise 12.0 does not include IBM Integration Explorer. Instead, the web user
interface is extended to support integration node administration tasks such as creating and managing
integration servers, and deploying and managing resources.

Chapter 2. Migrating 23
 For more information, see web user interface.

Keystore format for administration security

The certificate store for use in securing the REST Administration port, which is used by the Web User
Interface and IBM App Connect Enterprise Toolkit must be a .pem .p12 or .pfx format. This certificate
store cannot be in JKS format, and hence must be a separate certificate store from the certificate store
that used by the integration server for things such as HTTPS message flow nodes.
For more information, see “Authorizing users for administration” on page 2516.

Additional options for administration security

In IBM App Connect Enterprise 12.0, you have two options for configuring administration security. As in
previous versions, you can configure queue-based permissions by using IBM MQ queues on the queue
manager that is specified on the integration node. Alternatively, you can configure file-based permissions
on your integration node, which you set by using the mqsichangefileauth command.
If you configure administration security, then you perform parallel migration to integration nodes that are
not configured with queue managers, you must reconfigure your administration security to use file-based
permissions. Any security permissions that are set before migration are not retained after migration.
For more information, see “Authorizing users for administration” on page 2516.

Administration scripts might need to be updated

A number of commands are not available in this release. In addition, some parameters for administration
commands that connect to integration nodes and integration servers were changed. For more
information, see commands. The MQBrokerConnectionParameters IBM Integration API class is also
deprecated (see the Javadoc for the IBM Integration API).

IBM App Connect Enterprise Toolkit help topics might include details of function
that is not available to you
By default, the IBM App Connect Enterprise Toolkit is now configured to use online product
documentation to provide context-sensitive help from the latest information that is available. In previous
versions, the Toolkit contained local help documentation, which was not automatically updated when new
information became available. The way that help is displayed in the IBM App Connect Enterprise Toolkit
is not changed. However, the content of the IBM App Connect Enterprise section of the online product
documentation is updated when fix packs are made available. If you do not deploy the latest fix pack, the
help information might include details of function that is not available to you.
If you do not want to access the online product documentation, you can download and install a local
source of product documentation. For more information about local documentation options, see Adding
documentation to the IBM App Connect Enterprise Toolkit.

Message maps: change in behavior

In IBM App Connect Enterprise 12.0, the behavior of the Assign transform in the Graphical Data Mapping
editor has been corrected when you assign an empty string to an element.
• In previous versions of IBM Integration Bus, when you perform an Assign transform on a target element
that is defined as xsd:string, the Graphical Data Mapping editor sets the internal NULL value in the
message tree for that element.
• In IBM App Connect Enterprise 12.0, when you perform an Assign transform on a target element that is
defined as xsd:string, the Graphical Data Mapping editor sets the element value to the empty string ''
value.
For message formats such as XML, this change in behavior has no impact on the message flow. However,
if your message flow has logic that tests that the value of an element is the internal NULL value, you must

24 IBM App Connect Enterprise 12.0: User Guide

modify the test to look for the empty string value. Alternatively, you must modify the map to use the new
iib:nullvalue() function. To call the new function, you use a Custom XPath transform.

Message maps are validated at deployment time

In IBM App Connect Enterprise 12.0, message maps are prepared for execution on deployment instead
of when the first message flows through the Mapping node. For more information, see Deploying message
maps.

Java isolation is active and cannot be disabled

Previous versions of IBM Integration Bus did not support Java isolation in applications. All Java that
was deployed to the execution group was loaded into a single class loader, which was used by all
JavaCompute nodes in all applications. This behavior precluded the use of duplicate classes.
When you create an application in IBM Integration Bus 10.0, Java isolation is enabled by default. For each
application, a Java class loader is built that contains only the Java that is deployed in that application and
any included static libraries.
When you create an application in IBM App Connect Enterprise 11.0 or later, Java isolation is active and
you cannot disable it.

Publication of statistics to the web user interface is enabled by default

When an integration node or integration server is created in IBM App Connect Enterprise Version 11.0.0.8
or later, the publication of resource statistics and message flow snapshot statistics is activated by
default. The publication of archive statistics is turned off by default. The publicationOn property in
the server.conf.yaml or node.conf.yaml file is explicitly set to active and the outputFormat
property is set to json, which enables the publication of snapshot data to the web user interface. The
reportingOn property is explicitly set to true, which enables resource statistics for the integration
node or server to be published automatically to the web user interface.
For integration nodes and servers that were created before IBM App Connect Enterprise Version 11.0.0.8,
the publication of all statistics was turned off by default. To enable the publication of statistics for
integration nodes or servers that were created before V11.0.0.8, edit the relevant .conf.yaml file and
activate the publicationOn and reportingOn properties, as required.
For more information, see “Managing resource statistics collection” on page 2741 and “Configuring the
collection of message flow statistics by using a .yaml configuration file” on page 2729.

UUIDs are not assigned to the integration node, integration server, application, or
message flow components
In IBM App Connect Enterprise 11.0 and later, UUIDs are not assigned to the integration node, integration
server, application, or message flow components. When these fields are displayed (in monitoring events,
for example), they are set to all zeros.
For more information, see “The monitoring event” on page 2778.

Message flow monitoring

Monitoring events are issued in a new format that provides additional information. However, the format
that was used in IBM Integration Bus 10.0 can also be used in IBM App Connect Enterprise 12.0 by
editing the eventFormat property in the Monitoring.MessageFlow section of the .conf.yaml file.
For more information, see “Activating monitoring” on page 2804.

LDAP authentication and local passwords

If a web user account has a local password, and LDAP authentication is enabled, the local password is
ignored. When LDAP authentication is enabled, all web user logins must be authenticated by using LDAP.

Chapter 2. Migrating 25
 Any local passwords are ignored. For more information, see “Enabling LDAP authentication” on page
2511 and command - , , and systems.

HTTPConnector and HTTPSConnector policies

HTTPConnector and HTTPSConnector policies were deprecated in IBM App Connect Enterprise 11.0
Fix Pack 5 and are not supported in IBM App Connect Enterprise 12.0. If you try to deploy one of these
policy types in IBM App Connect Enterprise 12.0, you see an error and the policies are not loaded or
used. Instead, configure the HTTPConnector or HTTPSConnector Resource Manager section of the
server.conf.yaml file.

Enhanced flexibility in interactions with IBM MQ

Greater flexibility was introduced in IBM Integration Bus 10.0 in its interactions with IBM MQ. IBM App
Connect Enterprise 12.0 maintains this enhanced flexibility.
You can configure local or client connections to IBM MQ, enabling your integration nodes to get messages
from, or put messages to, queues on a local or remote queue manager. You can configure either a
local or client connection between your integration node and your queue manager, depending on the
configuration of your existing architecture. If your IBM MQ queue manager is running on the same
machine as your integration node, you can specify a local connection to the queue manager. Alternatively,
if the IBM MQ queue manager that you want to connect to is hosted on a separate machine from IBM App
Connect Enterprise, you can configure a client connection from your integration node so that it can access
the messages on the remote queue manager.
When you configure a connection from an MQ node to an IBM MQ queue manager, you can optionally
configure the connection to use a security identity for authentication, SSL for confidentiality, or both. The
security identity, which passes user name and password security credentials to the queue manager, can
be used on connections to local or remote queue managers. For connections to remote queue managers,
you can choose whether to use the SSL protocol to provide confidentiality on the client connection. IBM
App Connect Enterprise supports a subset of the SSL functionality that is supported by IBM MQ. For more
information, see “Connecting to a secured IBM MQ queue manager” on page 747.
Note: You cannot use a secured queue manager as the local default queue manager for an integration
node or an integration server.
You can get messages from, or put messages to, IBM MQ queues on local or remote queue managers, by
configuring the connection properties of the following MQ nodes:
• node
• node
• node
• node
Alternatively, you can specify a queue manager to be associated with the integration node by using the
-q parameter on the mqsicreatebroker command. This queue manager is used by default for MQ
processing in the message flow if no queue manager is specified explicitly on the MQ node. This queue
manager is also used by some message flow nodes that require a queue manager to be specified on the
integration node, such as the event-driven processing nodes used for aggregation, timeout, message
collection, and message sequencing. The -q parameter specifies the name of a queue manager, but
it does not create the queue manager automatically. You must define and start the queue manager as
separate tasks, in addition to specifying it with the mqsicreatebroker command.
Message flows can contain multiple MQInput and MQOutput nodes, each of which can access different
queue managers specified in the MQ node. For more information, see node and node.
IBM MQ is not a prerequisite for using IBM App Connect Enterprise, which means that you can develop
and deploy applications with IBM App Connect Enterprise independently of IBM MQ. However, some IBM
App Connect Enterprise features require access to IBM MQ, including the MQ nodes and the event-driven
processing nodes that are used for aggregation and timeout flows, message collections, and message
sequences. IBM MQ is not provided as part of the IBM App Connect Enterprise installation package;

26 IBM App Connect Enterprise 12.0: User Guide

however, when you purchase a license for IBM App Connect Enterprise, your license entitles you to install
IBM MQ for use by App Connect Enterprise, within the terms of the license.
The following IBM App Connect Enterprise features require IBM MQ Server to be installed on the same
machine as the integration node, and they are available for use only if you specify a queue manager on the
integration node:
• Queue-based administration security (MQ is not required for file-based security)
• Global transactionality
• FTEInput and FTEOutput nodes
• CDInput and CDOutput nodes
• Integration nodes with HTTP listeners
• HTTP proxy servlet
• High availability configurations
The integration node listener requires access to IBM MQ Server, so you must install it if you want to use
an integration node listener to manage HTTP messages in your HTTP or SOAP flows. However, if you use
HTTP nodes or SOAP nodes with the integration server embedded listener, they do not require access to
IBM MQ.
The following IBM App Connect Enterprise features require access to system queues on a local queue
manager (running on the same machine as the integration node) for the storage and retrieval of state
information:
• Queue-based administration security (system queues are not required for file-based security).
• Integration node HTTP listener.
• HTTP proxy servlet.
The following IBM App Connect Enterprise features require access to system queues on a either a local or
remote queue manager for the storage and retrieval of state information:
• Record and replay.
• Event-driven processing nodes (aggregate, collector, sequence, resequence, and timeout nodes).
For information about creating the system queues, see “Creating the default system queues on an IBM
MQ queue manager” on page 99.
On Linux and AIX systems only, you must also configure the IBM MQ environment that you want the
integration node to use before you start it. If you do not set the environment, your integration node might
not run in the expected location. For more information, see “Setting the IBM MQ environment on Linux
and AIX” on page 84.
The MQInput, MQOutput, MQGet, and MQReply nodes require that IBM MQ is installed either locally
or remotely, but they do not require a queue manager to be specified on the integration node unless
you want to use this queue manager by default for your local MQ connection. For more information, see
“Configuring a local connection to IBM MQ” on page 744 and “Configuring a client connection to IBM
MQ” on page 745.
The SAPInput, SAPReply, and SAPRequest nodes require that either IBM MQ Client or Server is installed
on the same machine as the integration node, and they require a queue manager to be specified on the
integration node.
For a list of the main IBM App Connect Enterprise features, including information about the features that
require the installation of IBM MQ Client or Server, see features.
For a summary of the features that are new to IBM App Connect Enterprise 12.0, see What's new in ?.

Chapter 2. Migrating 27
IBM MQ and migration to IBM App Connect Enterprise 12.0
During migration, you might want to configure IBM App Connect Enterprise 12.0 to take advantage of the
increased flexibility that was introduced in IBM Integration Bus 10.0 for its interactions with IBM MQ.
Greater flexibility was introduced in IBM Integration Bus 10.0 in its interactions with IBM MQ; IBM App
Connect Enterprise 12.0 maintains this enhanced flexibility. See “Enhanced flexibility in interactions with
IBM MQ ” on page 26 and “IBM MQ topologies” on page 739.
In IBM Integration Bus 10.0, the integration layer of your architecture must contain IBM MQ (or IBM MQ)
queue managers. If you have queues that you use in integration applications, you must have an existing
IBM MQ (or IBM MQ) topology in which application messages are routed to the queue manager that is
specified on the integration node by using IBM MQ (or IBM MQ) channels, remote queue definitions, and
distributed messaging. It might be possible to simplify your system so that your message flows interact
directly with remote queue managers, which might simplify the topology that you need to manage. This
simplification requires that you redesign your message flows and your topology, and is more than just a
migration of your existing solution. However, you might want to include these activities as part of your
migration plans.
To determine which components of your existing deployment are using capabilities that require IBM MQ
or (IBM MQ) queue managers to be a part of the integration layer of your IBM App Connect Enterprise
12.0 architecture, and which components are using capabilities that can integrate with IBM MQ
application queues on a remote queue manager, see “Installing IBM MQ” on page 96.
Depending on whether you can change your IBM MQ topology during the migration process, you have the
following options for migrating integration nodes:
• Create a new Version 12.0 integration node and associate the integration node with a new queue
manager. Add the new queue manager into your IBM MQ network, migrate the applications from the
original integration node, and redirect application queues as required (parallel migration).
• Create a new Version 12.0 integration node and associate the integration node with the same queue
manager as the original integration node. Migrate the applications from the original integration node,
and keep the IBM MQ application endpoints and IBM MQ topology the same (parallel migration).
Note: This option cannot be used if your integration node has message flows that contain the following
message flow nodes:
– AggregateControl
– AggregateReply
– AggregateRequest
– Collector
– Sequence
– Resequence
– TimeoutControl
– TimeoutNotification
These nodes use MQ queues to save state, which cannot be shared between integration nodes.
• Create a new Version 12.0 integration node and do not associate the integration node with a queue
manager. Migrate the applications from the original integration node, and configure message flows
that require IBM MQ queues to connect to specified queue managers, either by directly configuring the
message flow or by using a policy (parallel migration).
For more information, see “IBM App Connect Enterprise migration options” on page 29.

28 IBM App Connect Enterprise 12.0: User Guide

IBM App Connect Enterprise migration options
IBM App Connect Enterprise 12.0 supports parallel migration and extract migration to migrate your
application logic to Version 12.0 systems.
If you want to reproduce the integration node function on another computer, you can use parallel
migration to associate the application logic on your existing integration node with a separate Version 12.0
integration node. For more information, see “Performing parallel migration for an integration node ” on
page 61.
By using extract migration, you can migrate the configuration and resources of existing integration nodes
and servers to IBM App Connect Enterprise 12.0, as described in “Performing extract migration of an
integration node or integration server” on page 57.
Independent integration servers that were created in IBM App Connect Enterprise 11.0 can be started
in IBM App Connect Enterprise 12.0, without the need to migrate them or their resources. However,
integration server work directories are typically created as transient rather than long-term artifacts, and
many users prefer to rebuild them when moving from one version to another.

Restrictions
Consider the following restrictions before you decide whether to use parallel migration for your
integration nodes.
IBM MQ enhancements
Greater flexibility was introduced in IBM Integration Bus 10.0 in its interactions with IBM MQ;
IBM App Connect Enterprise 12.0 maintains this enhanced flexibility. Ensure that you are using a
supported version of IBM MQ to take advantage of the greater flexibility.
If you use parallel migration, you can install and configure an IBM App Connect Enterprise 12.0
deployment that takes advantage of the IBM MQ flexibility, and then move your applications into the
Version 12.0 deployment.
For more information, see “IBM MQ and migration to IBM App Connect Enterprise 12.0” on page
28.
Maintaining administration security
If you have administration security configured in your current environment by using IBM MQ queues,
and you perform parallel migration, you must re-create the equivalent administration security
settings by using file-based permissions on your new integration nodes (see “Authorizing users for
administration” on page 2516).

Example migration scenarios

Example migration scenarios demonstrate how to migrate message flows and applications from IBM
Integration Bus 10.0 to IBM App Connect Enterprise 12.0.
• “Migrating an integration node with configurable services ” on page 30
This scenario shows how to migrate an IBM Integration Bus 10.0 integration node that has configurable
services for external resources. The Version 10.0 node also has a specific user ID and password that is
associated with one or more resources by using the mqsisetdbparms command.
• “Migrating an integration node with multiple integration servers” on page 31
This scenario uses the mqsiextractcomponents command to migrate an IBM Integration Bus 10.0
integration node with multiple integration servers to IBM App Connect Enterprise 12.0 independent
integration servers.
• “Migrating an integration server that contains applications and a shared library” on page 33
This scenario shows how to migrate an IBM Integration Bus 10.0 integration server with applications
and a shared library to IBM App Connect Enterprise 12.0.

Chapter 2. Migrating 29
 • “Migrating an SAP integration flow” on page 34
This scenario shows how to migrate an SAP integration flow that runs on IBM Integration Bus 10.0.

Migrating an integration node with configurable services

Migrate an IBM Integration Bus 10.0 integration node that has configurable services for external
resources, and a specific user ID and password that is associated with one or more resources by using the
mqsisetdbparms command.

About this task

In this scenario, a simple flow that contains a FileInput node and a FileOutput node is deployed to an IBM
Integration Bus 10.0 integration server, then to an integration node. An FtpServer configurable server has
been created by using the following command:

mqsicreateconfigurableservice MigrationNode -c FtpServer -o FtpServer01

-n serverName,scanDelay,transferMode,connectionType,securityIdentity
-v one.hursley.abc.com:123,20,Binary,ACTIVE,myftp

The following steps describe how to migrate the flow to IBM App Connect Enterprise 12.0.

Procedure
1. Back up the IBM Integration Bus 10.0 integration node by using the mqsibackupbroker command.

mqsibackupbroker IntegrationNode -d directory

A file with a name in the format intNodeName_yyMMdd_HHmmss.zip is created in the specified

directory.
2. In IBM App Connect Enterprise 12.0, use the mqsicreatebroker command to create a new
integration node.
mqsicreatebroker IntegrationNode
3. Start the integration node by running the command mqsistart IntegrationNode.

30 IBM App Connect Enterprise 12.0: User Guide

4. Create the directory structure servers\IntegrationServer under the integration node work path
($MQSI_WORKPATH).
For example, on Windows: C:\ProgramData\IBM\MQSI\components\IntegrationNode
\servers\IntegrationServer.
5. Stop the integration node by running the command mqsistop IntegrationNode.
6. Use the mqsiextractcomponents command to migrate the IBM Integration Bus 10.0 integration
server and resources to IBM App Connect Enterprise 12.0.
All deployed resources are migrated under the /run directory: C:\ProgramData\IBM\MQSI
\components\IntegrationNode\servers\IntegrationServer\run.
During migration, the IBM Integration Bus 10.0 configurable services are converted to policies in
IBM App Connect Enterprise 12.0. The policy project resides in the /run subfolder in the work
directory. No value was specified for the policy_project_name; therefore, policies are created
in a policy project called DefaultPolicies. For example, if the FTPServer configurable service
name is ftpbroker, a policy file with name ftpbroker.policyxml is created under the run
\DefaultPolicies folder in the work path.
7. Start the integration node by running the command mqsistart V12BRK.
You might see the following error message in the event viewer:

File node "File Output" in message flow "FileInOutFlow". The remote user identifier supplied
as "myftp" is invalid.
The user identifier supplied by a securityIdentity is not valid. Either the user identifier
is missing, or no securityIdentity definition exists, or the securityIdentity registry
information could not be read due to a permissions problem. FTP processing for this node has
been disabled.
Ensure that the securityIdentity is correctly defined using the mqsisetdbparms command.

Currently, the mqsiextractcomponents command does not migrate the credentials that are set by
using the mqsisetdbparms command in IBM Integration Bus 10.0. Therefore, you need to set the
security identity and other credentials by running the mqsisetdbparms again in IBM App Connect
Enterprise 12.0:

mqsisetdbparms V12BRK -n ftp::myftp -u user -p password

8. Restart the IBM App Connect Enterprise 12.0 integration node by running the mqsistop command,
followed by the mqsistart command.

Migrating an integration node with multiple integration servers

Use the mqsiextractcomponents command to migrate an IBM Integration Bus 10.0 integration node
with multiple integration servers to IBM App Connect Enterprise 12.0 independent integration servers.

Procedure
1. Create an application with a few message flows in the IBM Integration Bus 10.0 Toolkit.
2. Create an integration node called Migration Node.
3. Create three integration servers called MigrationServer1, Migrationserver2, and
MigrationServer3.
4. Deploy the application to all of the three integration servers.
5. Back up the integration node by using the mqsibackupbroker command:

mqsibackupbroker MigrationNode -d C:\temp\

6. Copy the broker backup file to the IBM App Connect Enterprise 12.0 server for migration.
7. In IBM App Connect Enterprise 12.0, use the mqsiextractcomponents command to create three
independent integration servers:

mqsiextractcomponents --source-integration-node MigrationNode --source-integration-server

MigrationServer1 --backup-file C:\temp\MigrationNode_181114_120112.zip --target-work-
directory C:\temp\MigrationServer1 --default-application DefApp

Chapter 2. Migrating 31
 mqsiextractcomponents --source-integration-node MigrationNode --source-integration-server
MigrationServer2 --backup-file C:\temp\MigrationNode_181114_120112.zip --target-work-
directory C:\temp\MigrationServer2 --default-application DefApp
mqsiextractcomponents --source-integration-node MigrationNode --source-integration-server
MigrationServer3 --backup-file C:\temp\MigrationNode_181114_120112.zip --target-work-
directory C:\temp\MigrationServer3 --default-application DefApp

Note: We specify the –default-application DefApp option to ensure that any message flows
that are deployed as independent projects are moved into the default application DefApp. In IBM App
Connect Enterprise 12.0, all resources must be part of an application.
8. Start the independent integration server by using the IntegrationServer command:

IntegrationServer --name MigrationServer1 --work-dir C:\temp\MigrationServer1

9. To demonstrate that the configurable services that were defined for the IBM Integration Bus 10.0
integration nodes are copied with the migrated integration server, complete the following steps.
a) Create a configurable service.
mqsicreateconfigurableservice MigrationNode -c FtpServer -o FtpServer01
-n serverName,scanDelay,transferMode,connectionType,securityIdentity -v
one.hursley.abc.com:123,20,Binary,ACTIVE,secId
b) Modify your message flow to use the FTP configurable service.

c) Save the message flow and redeploy the application to the integration server MigrationServer1.
d) Create a new backup by using the mqsibackupbroker command in IBM Integration Bus 10.0.

mqsibackupbroker MigrationNode -d C:\temp\

e) In IBM App Connect Enterprise 12.0, run the mqsiextractcomponents command:

mqsiextractcomponents --source-integration-node MigrationNode --source-integration-server

MigrationServer1 --backup-file C:\temp\MigrationNode_181114_125348.zip --target-work-
directory C:\temp\MigrationServer4 --default-application DefApp
BIP8071I: Successful command completion.

The folder C:\temp\MigrationServer4\run\DefaultPolicies contains the FTP

configurable service policy under the IBM App Connect Enterprise 12.0 independent
integration server. The FtpServer01 configurable service is available as a new policy. The
FtpServer01.policyxml file contains configurations that match your FTP Server configurations.
f) Start the independent integration server by using the IntegrationServer command and verify
the flow execution.

32 IBM App Connect Enterprise 12.0: User Guide

Migrating an integration server that contains applications and a shared
library
Migrate an IBM Integration Bus 10.0 integration server that contains applications and a shared library to
IBM App Connect Enterprise 12.0.

Procedure
1. In IBM Integration Bus 10.0, create a shared library to contain a simple subflow. Create an
application with a simple message flow that uses the subflow from the shared library.

2. Deploy the shared library to the IBM Integration Bus 10.0 integration node IIBV10.
3. Back up the IBM Integration Bus 10.0 integration node IIBV10 by using the mqsibackupbroker
command.

mqsibackupbroker IIBV10 -d c:\temp

4. Create a new IBM App Connect Enterprise 12.0 integration node called ACEV12 by using the
command mqsicreatebroker ACEV12.
5. Start the IBM App Connect Enterprise 12.0 node ACEV12 to set up the work directory.
6. Stop the IBM App Connect Enterprise 12.0 node.
7. Create a blank work directory for the integration server IS1 to be migrated to IBM App Connect
Enterprise 12.0.

Chapter 2. Migrating 33
 8. Use the mqsiextractcomponents command to migrate the IBM Integration Bus 10.0 integration
server IS1 to IBM App Connect Enterprise 12.0, then start the integration node ACEV12.

mqsiextractcomponents --source-integration-node IIBV10 --source-integration-server IS1 --

backup-file c:\temp\IIBV10_181118_220025.zip
--target-work-directory c:\ProgramData\IBM\MQSI\components\ACEV12\servers\IS1

mqsistart ACEV12

9. After you start the node, connect to the integration node from the IBM App Connect Enterprise
Toolkit.
The application and shared library resources that were migrated from the IBM Integration Bus 10.0
node appear under the integration node ACEV12.
10. Test the migrated flow.
For example:

C:\user\curl_7_53_1_openssl_nghttp2_x64>curl -d "<in>Test</in>" http://localhost:7800/hello

<out>Hello Test</out>

Migrating an SAP integration flow

Migrate an SAP integration flow that runs on IBM Integration Bus 10.0 to IBM App Connect Enterprise
12.0.

About this task

The following steps describe how to create an SAP integration flow in IBM Integration Bus 10.0, then
how to migrate it to IBM App Connect Enterprise 12.0. The steps describe two different migration
options: migrating to an integration node or an independent integration server. This scenario uses an SAP
outbound adapter as an example; the same steps apply to an inbound adapter.

Procedure
• “Creating an SAP integration flow in IBM Integration Bus 10.0” on page 35
• “Migrating an IBM Integration Bus 10.0 integration node to an IBM App Connect Enterprise 12.0
integration node” on page 39
• “Migrating an integration flow from an IBM Integration Bus 10.0 integration node to an IBM App
Connect Enterprise 12.0 independent integration server” on page 40

34 IBM App Connect Enterprise 12.0: User Guide

Creating an SAP integration flow in IBM Integration Bus 10.0

Procedure
1. In IBM Integration Bus 10.0, create an SAP outbound adapter to fetch BAPI_BANK_GETDETAILS.
a) In the IBM Integration Toolkit, click File > New > Adapter connection, then follow the instructions
in the wizard.
b) For service discovery, select RFC and set a filter to find objects for BAPI_BANK_*.

c) For the the BAPI_BANK_GETDETAIL configuration parameters , select the objects to import.

Chapter 2. Migrating 35
 d) Configure the objects.

36 IBM App Connect Enterprise 12.0: User Guide

2. Create a simple SAP application to fetch BAPI BANK GETDETAILS.
3. Configure the integration node with SAP JCo libraries by using the mqsichangeproperties
command.

mqsichangeproperties IIBNODE -c EISProviders -o SAP -n jarsURL -v C:\SAP_JARS

mqsichangeproperties IIBNODE -c EISProviders -o SAP -n nativeLibs -v C:\SAP_JARS

You can verify that the properties are set up correctly by running the command:
mqsireportproperties IIBNODE -c EISProviders -o SAP -r

Chapter 2. Migrating 37
 4. Deploy the resources to the integration server.

38 IBM App Connect Enterprise 12.0: User Guide

5. Create a configurable service for the SAP adapters connection.
By using a configurable service, you can change the host name that is set in the adapter file without
needing to redeploy the resources.
a) Use the SAPConnection configurable service to change connection details for an SAP adapter.

mqsicreateconfigurableservice IIBNODE -c SAPConnection -o

SAP_BAPI_BANK_GETDETAILS_OUT.outadapter -n applicationServerHost,client -v
wmbsap.hursley.ibm.com,001

b) To display all SAPConnection configurable services, use the mqsireportproperties command:

mqsireportproperties IIBNODE -c SAPConnection -o AllReportableEntityNames -r

Migrating an IBM Integration Bus 10.0 integration node to an IBM App Connect
Enterprise 12.0 integration node

Procedure
1. Back up the IBM Integration Bus 10.0 integration node by using the mqsibackupbroker command.

mqsibackupbroker IIBNODE -d C:\SAP_JARS

2. Migrate the IBM Integration Bus 10.0 integration node and resources to IBM App Connect Enterprise
12.0 by using the mqsiextractcomponents command.

mqsiextractcomponents --source-integration-node IIBNODE --target-integration-node ACENODE --

backup-file "C:\SAP_JARS\IIBNODE_190712_083247"

This mqsiextractcomponents command creates a new integration node and integration server.
If the integration node already exists, the mqsiextractcomponents command fails unless you

Chapter 2. Migrating 39
 specify –delete-existing-node. In this case, the existing integration node is deleted and a new
integration node is created with the same name.
All deployed resources are migrated under the /run directory of the created integration server. For
example, on Windows: C:\ProgramData\IBM\MQSI\components\IntegrationNode\servers
\IntegrationServer.
During migration, the IBM Integration Bus 10.0 configurable services are converted to policies
in IBM App Connect Enterprise 12.0. You can find the policy project in the integration node work
directory. If you do not specify a policy project name, policies are created in a policy project called
DefaultPolicies. The policy file that is created has the same name as the adapter.
3. Start the IBM App Connect Enterprise 12.0 integration node by running the command mqsistart
ACENODE.
The application and policy files are listed under the IBM App Connect Enterprise 12.0
node in the Toolkit. You can confirm the location of the migrated JAR files by running the
mqsireportproperties command on the IBM App Connect Enterprise 12.0 node.

mqsireportproperties ACENODE -c EISProviders -o SAP -r

4. Test the integration flow by sending a message to fetch the record for BAPI BANK GETDETAILS.
The following example shows the expected output message.

Migrating an integration flow from an IBM Integration Bus 10.0 integration node to an
IBM App Connect Enterprise 12.0 independent integration server

Procedure
1. Migrate an IBM Integration Bus 10.0 integration server to an IBM App Connect Enterprise 12.0
independent integration server by running the mqsiextractcomponents command.

mqsiextractcomponents --source-integration-node IIBNODE --source-integration-

server default --target-work-directory "C:\temp\ACESIS" --backup-file "C:\SAP_JARS
\IIBNODE_190712_083247.zip"

If the work directory already exists, the mqsiextractcomponents command fails unless you specify
–clear-work-directory. In this case, the configuration and resources are written to the work
directory, and overwrite any data that might be present in the directory.

40 IBM App Connect Enterprise 12.0: User Guide

 2. Start the IBM App Connect Enterprise 12.0 integration server by running the IntegrationServer
command.

IntegrationServer --name default --work-dir C:\temp\ACESIS

All deployed resources are migrated to the /run subfolder in the work directory of the independent
integration server.
During migration, the values that are set by using the mqsichangeproperties command in IBM
Integration Bus 10.0 are added to the server.conf.yaml file in the /overrides subfolder in the
work directory of the IBM App Connect Enterprise 12.0 integration server.
Also during migration, the IBM Integration Bus 10.0 configurable services are converted to policies in
IBM App Connect Enterprise 12.0. You can find the policy project in the /run subfolder of the work
directory for the integration server. If you do not specify the policy project name, policies are created
in a policy project called DefaultPolicies. The name of the policy file that is created is the same as
the adapter.
The application and policy files are listed under the IBM App Connect Enterprise 12.0 integration
server in the Toolkit.

Performing pre-migration tasks

Perform the prerequisite tasks for migration to IBM App Connect Enterprise 12.0.

Procedure
Complete the following steps before you migrate your integration nodes or integration servers.
• Back up your resources by following the instructions in “Backing up resources before migration” on
page 41.
• If your environment includes access to databases, create ODBC definitions for the databases and
specify appropriate database drivers; see “Updating ODBC definitions when you migrate to IBM App
Connect Enterprise 12.0” on page 42.
• Optional: If you plan to move your architecture to adopt containers, run the Transformation Advisor
tool, as described in “Running the Transformation Advisor tool” on page 44.

What to do next
After you complete your pre-migration tasks, complete migration by following the instructions in
“Migrating to IBM App Connect Enterprise 12.0” on page 57.

Backing up resources before migration

Back up your resources before you start to migrate to IBM App Connect Enterprise 12.0.

Before you begin

To plan your migration strategy, read “Preparing for migration” on page 19.

Procedure
Before you complete migration tasks, back up your current resources by completing the following steps.
1. Optional: If your message flows access user databases through an ODBC connection, back up the
ODBC files that you use for these connections.
Take a copy of these files and store them safely in a different location.

Chapter 2. Migrating 41
 2. Back up your Toolkit workspace and resources, such as message flow files, message set definition
files, Java files, ESQL files, mapping files, XML Schema files, and BAR files.
• Export all the projects from your current Toolkit.
• Archive your workspace resources.
If you manage your workspace resources in a shared repository (for example, CVS), follow standard
backup procedures for safeguarding versions. Create a version for storing Version 12.0 resources.
If you maintain your workspace resources on a local or shared disk, copy your workspace directory
to a different location.

Updating ODBC definitions when you migrate to IBM App Connect Enterprise
12.0
Before you migrate an integration server or integration node, create ODBC definitions for databases and
specify appropriate database drivers for IBM App Connect Enterprise 12.0.

About this task

The database drivers that are supported by IBM App Connect Enterprise 12.0 might be at a later version
than the drivers that are used by previous versions.
Follow the instructions that are provided for your operating system:
• “Updating ODBC definitions on Windows systems” on page 42
• “Updating ODBC definitions on Linux systems” on page 43

Updating ODBC definitions on Windows systems

Procedure
1. To change the ODBC connection definitions, open the ODBC Data Source Administrator window, then
open the System DSN page.
2. For each Oracle and Sybase database that is accessed by the integration node, compare the ODBC
driver against the entries that are listed in the following table, where n is the level of the installed fix
pack (if appropriate).

DBMS IBM App Connect Enterprise 12.0 ODBC driver name

Sybase IBM App Connect Enterprise 12.0.1.n - DataDirect Technologies 64-BIT Sybase
Wire Protocol
Oracle IBM App Connect Enterprise 12.0.1.n - DataDirect Technologies 64-BIT Oracle
Wire Protocol

If the ODBC driver does not match, associate the data source name with the new ODBC driver by
completing the following steps.
a) Delete the data source by clicking Remove.
b) Re-create the data source with the new ODBC driver by clicking Add.

42 IBM App Connect Enterprise 12.0: User Guide

 3. To change the XA resource manager definitions, complete the following steps.
a) Open the Properties window of the integration node queue manager by using the IBM MQ Services
snap-in.
b) Open the Resources page.
c) For each Oracle and Sybase database that participates in a global unit of work that is coordinated
by the integration node queue manager, change the contents of the SwitchFile field.
The following table specifies the entries that you must change for each database management
system (DBMS). install_dir represents the fully qualified path name of the directory in which you
installed IBM App Connect Enterprise.

DBMS Original entry New entry

Oracle install_dir\server\bin\ukor8dtc22.dll WBIMB\bin\ukora95.dll
or
install_dir\server\bin\ukor8dtc23.dll
or
install_dir\server\bin\ukora24.dll
or
install_dir\server\bin\ukora26.dll
Sybase install_dir\server\bin\ukase22.dll WBIMB\bin\ukase95.dll
or
install_dir\server\bin\ukase23.dll
or
install_dir\server\bin\ukase24.dll
or
install_dir\server\bin\ukase26.dll
d) For changes to the switch file configuration to take effect, restart the integration node queue
manager.

Updating ODBC definitions on Linux systems

Procedure
1. To change the ODBC connection definition, create an ODBC definitions file by following the instructions
in “Connecting to a database from Linux and UNIX systems by using the IBM Integration ODBC
Database Extender” on page 189.
Before you run the commands at the new service level, check that your ODBCINI environment variable
points to the new file and not to the existing file. Check that the ODBCSYSINI environment variable is
set to point to the directory that contains your odbcinst.ini file.

Chapter 2. Migrating 43
 2. To change the XA resource manager definitions, edit the queue manager configuration file (qm.ini) of
the queue manager that is associated with the integration node.
The qm.ini file is in the directory /var/mqm/qmgrs/queue_manager_name, where
queue_manager_name is the name of the queue manager that is associated with the integration node.
In the XAResourceManager stanza for each Oracle and Sybase database that participates in a global
unit of work that is coordinated by the integration node queue manager, change the entry for the
switch file.
The following table specifies the entries that you must change for each operating system and database
management system (DBMS).

DBMS Original entry New entry

Oracle SwitchFile=UKor8dtc22.so SwitchFile=UKoradtc95.so
or
SwitchFile=UKoradtc22.so
or
SwitchFile=UKor8dtc23.so
or
SwitchFile=UKoradtc23.so
or
SwitchFile=UKoradtc24.so
or
SwitchFile=UKoradtc26.so
Sybase (not supported on SwitchFile=UKasedtc22.so SwitchFile=UKasedtc95.so
Linux on Z)
or
SwitchFile=UKasedtc23.so
or
SwitchFile=UKasedtc24.so
or
SwitchFile=UKasedtc26.so
3. For changes to the switch file configuration to take effect, restart the integration node queue manager.

Running the Transformation Advisor tool

If you plan to move your architecture to adopt containers, run the Transformation Advisor tool before
you migrate to IBM App Connect Enterprise 12.0. Use the tool to collect data about what is deployed to
your IBM Integration Bus 10.0 or IBM App Connect Enterprise 11.0 integration node, then analyze the
collected data for potential issues.

About this task

If you are planning to move to a containerized environment, the Transformation Advisor tool helps
you to analyze your on-premises workloads for modernization. You can collect and assess data for
a specific integration server in an integration node backup in App Connect Enterprise by using the
TADataCollector command. You can also upload the results that are produced by the Transformation
Advisor tool to IBM Cloud® Transformation Advisor. For more information, see IBM Cloud Transformation
Advisor.

44 IBM App Connect Enterprise 12.0: User Guide

 Procedure
To collect and analyze data about your IBM Integration Bus 10.0 or IBM App Connect Enterprise 11.0
integration node, complete the following steps.
1. Back up the resources that you want to migrate by using one of the following methods.
• Create a backup file of your IBM Integration Bus 10.0 or IBM App Connect Enterprise 11.0
integration node by running the mqsibackupbroker command:

mqsibackupbroker node10 -d C:\temp -a node10.zip

• Add the resources that you want to migrate to a deployable BAR file by running the
mqsipackagebar command:

mqsipackagebar -w C:\Workspace -a myapp.bar -c -i -k Application1 -y Shlib1 -v tracefile

2. Optional: In IBM App Connect Enterprise 12.0, create an output directory to write the logs from the
TADataCollector command, and set the value of the environment variable TADataCollectorDirectory
to the name of the output directory. If you do not create an output directory, the logs are written to a
temporary folder in the home directory of the user who runs the command.
a) Create an output directory by running the command mkdir C:\TADemo.
b) Set the environment variable TADataCollectorDirectory to the path of the output directory by
running the command set TADataCollectorDirectory=C:\TADemo.
3. In IBM App Connect Enterprise 12.0, run the TADataCollector command with one of the following
options:
• To collect data, run the command:

TADataCollector ace collect C:\temp\node10.zip

• To collect and assess data, run the command:

TADataCollector ace assess C:\temp\node10.zip

• To generate reports on data that is collected and assessed by the previous two options, run the
command:

TADataCollector ace report

• To collect and assess data, and generate reports, run the command:

TADataCollector ace run C:\temp\node10.zip

For more information about the TADataCollector command, see command.

When you run the TADataCollector command, output is written to an output directory. If you
created the output directory and set the TADataCollectorDirectory environment variable, the output is
written to that directory. Otherwise, the output is written to a temporary folder in the home directory
of the user who runs the command. For example, C:\Users\username\AppData\Local\Temp
\TADataCollector.
The following subdirectories are created in the output directory:
• logs: This folder contains the log ta_util.log that you can use to check for errors in the process.
• output: This folder contains a file environment.json, which shows the details of the
environment where the integration node was created. The folder also contains a subfolder for each
integration server (for example, node10/server10), which contains a .json file. The .json file
contains details of what is deployed to the integration server. It also contains configuration details
that were generated when you ran the TADataCollector command.

Chapter 2. Migrating 45
 4. Review the contents of the output folder in the output directory.
If you ran the TADataCollector command with the run parameter, a static HTML report is
produced; for example, C:\TADemo\output\node10\recommendations.html. The report lists
any issues that are found for each integration server under the integration node.
To view more detailed information about the issues, follow the links in the summary table or scroll
down the page. Each issue has an Overall Complexity Score that denotes the type of action that is
needed:
• Simple: An administrative change is needed.
• Moderate: A development change is needed.
• Complex: A difficult development task is involved or an alternative strategy is needed.
The Transformation Advisor tool also provides a severity classification for each issue it uncovers:
• Green (info): No immediate action is necessary, but you might want to be aware.
• Yellow (warning): Immediate action is probably needed or advised before you proceed.
• Red (error): You must take remedial action before you can proceed.
The following example shows a complex issue with a severity classification of red that was identified
when the tool was run against the IBM Integration Bus 10.0 integration node, node10 with one
integration server, server10.

Table 1. Recommendation report for assessment: node10

Assessment unit Overall complexity Issues Total effort (days)
score
server10 COMPLEX 1 10

Table 2. Recommendation report for assessment unit: server10

Product name Product version Runtime Platform Location
ACE 11.0 ACE Docker Private

Table 3. Overall complexity score: COMPLEX

RED issues: 1 Yellow issues: 0 Green issues: 0

Table 4. Issues with a COMPLEX complexity rating can be resolved by making significant development
changes or by choosing an alternative technology:
ID Title Cost Severity Solution
IIB01 Consider 10 RED The message flow contains an instance of
a different a.NETInput or .NETCompute message flow node.
transformation
mechanism in While IBM App Connect Enterprise 12.0 software
place of .NET. continues to support .NET, it does not support
running the .NET CLR during deployment to Linux
Docker containers on App Connect Enterprise
Certified Containers.
Other message flow nodes are available for
transformation such as Compute, JavaCompute,
and Mapping nodes.

For more information about the rules that apply to the Transformation Advisor tool, see “Rules for the
Transformation Advisor tool” on page 47.

46 IBM App Connect Enterprise 12.0: User Guide

5. Complete any actions that are advised by the report, then run the Transformation Advisor tool again to
confirm that all issues are resolved.

Rules for the Transformation Advisor tool

When you use the Transformation Advisor tool to analyze your deployed resources, different rules apply
depending on whether you back up your resources to a backup file or a BAR file.
If you plan to move your architecture to adopt containers, you can run the Transformation Advisor tool
to collect data about what is deployed to your IBM Integration Bus 10.0 or IBM App Connect Enterprise
11.0 integration node. You can then analyze the collected data for potential issues before you migrate. For
more information, see “Running the Transformation Advisor tool” on page 44.
The following table shows the rules that apply to the Transformation Advisor tool and whether they apply
to a backup file, a BAR file, or both.

Table 5. Rules for the Transformation Advisor tool:

ID Title Can Can Solution
be be
found found
in a in a
backup BAR
file file
IIB01
Consider a different transformation True True The message flow contains an instance
mechanism in place of .NET. of a .NETInput or .NETCompute
message flow node.
While IBM App Connect Enterprise 12.0
software continues to support .NET,
it does not support running the .NET
CLR when it is deployed to Linux Docker
containers on App Connect Enterprise
Certified Containers.
Other message flow nodes are available
for transformation such as Compute,
JavaCompute, and Mapping nodes.

IIB02
Consider a different transformation True True The message flow contains an instance
mechanism in place of PHP. of a PHPCompute message flow node.
The PHPCompute node was deprecated
in IBM Integration Bus 10.0 and it
was removed from IBM App Connect
Enterprise 11.0. Other message flow
nodes are available for transformation,
such as Compute, JavaCompute, and
Mapping nodes.

Chapter 2. Migrating 47
 Table 5. Rules for the Transformation Advisor tool: (continued)
ID Title Can Can Solution
be be
found found
in a in a
backup BAR
file file
IIB03
Consider an alternative mechanism to True True The message flow contains an
SCA to communicate with WebSphere instance of an SCA message
Process Server. flow node (SCAInput, SCAReply,
SCARequest, SCAAsyncRequest,
SCAAsyncResponse). IBM App Connect
Enterprise 12.0 does not support
the SCA message flow nodes that
were available in IBM Integration Bus
10.0. HTTP, IBM MQ, or JMS transport
options are available for communication
between message flows and SCA
components in WebSphere Process
Server.
IIB04
Consider a different mechanism to run True True The message flow contains an instance
IBM Operational Decision Management of a DecisionService message flow node.
Business Rules. App Connect Enterprise v11.0.0.8 and
later provides a replacement message
flow node, the ODMRules node. The
purpose of this node is to run ODM rules
in the integration server. Alternatively,
you can use the ODM SOAP or REST API
to run business rules in the ODM engine.
IIB05
Consider a different protocol instead of True True The message flow contains an instance
relying on local file integration. of a FileInput message flow node that
relies on local file interaction, and is not
configured to use FTP. Although IBM
App Connect Enterprise 12.0 continues
to support local files with the FileInput
node, if you want to use a container-
based architecture, this choice has
architectural drawbacks. Consider
changing your configuration to use FTP
or a more suitable messaging-based
transport.
IIB06
Consider your use of WebSphere Service True True The message flow contains an
Registry and Repository. instance of a RegistryLookup or
EndpointLookup message flow node,
which communicates with WebSphere
Service Registry and Repository.
Releases before App Connect Enterprise
11.0.0.7 do not support these message
flow nodes. If you have an urgent
need, or a simple use case, you can
use the SOAP nodes to communicate
with WebSphere Service Registry and
Repository. Alternatively, contact IBM to
learn more about plans in this area.

48 IBM App Connect Enterprise 12.0: User Guide

Table 5. Rules for the Transformation Advisor tool: (continued)
ID Title Can Can Solution
be be
found found
in a in a
backup BAR
file file
IIB07
A Publication message flow node was True True The message flow contains an instance
found. You might want to consider of a Publication message flow node.
altering your IBM MQ topology. In IBM Integration Bus 10.0 and in
versions of IBM App Connect Enterprise
11.0 before Fix Pack 6, this message
flow node requires a local server
binding connection to an IBM MQ queue
manager. IBM App Connect Enterprise
11.0 Fix Pack 6 and later supports the
Publication node by using a remote
client connection to an IBM MQ queue
manager. Consider altering your IBM
MQ topology as part of your move to a
container-based architecture.
IIB08
A Sequence or Resequence message True True The message flow contains an instance
flow node was found. Consider altering of a Sequence or Resequence message
your IBM MQ topology. flow node. In versions of IBM App
Connect Enterprise 11.0 before Fix
Pack 7, this message flow node requires
a local server binding connection to
an IBM MQ queue manager. Consider
altering your IBM MQ topology as part
of your move to a container-based
architecture.
IIB09
A Collector message flow node was True True The message flow contains an instance
found. Consider altering your IBM MQ of a Collector message flow node. In
topology. versions of IBM App Connect Enterprise
11.0 before Fix Pack 7, this message
flow node requires a local server
binding connection to an IBM MQ queue
manager. Consider altering your IBM
MQ topology as part of your move to a
container-based architecture.
IIB10
A TimeoutControl or TimeoutNotification True True The message flow contains an
message flow node was found. You instance of a TimeoutControl or
might want to consider altering your IBM TimeoutNotification message flow
MQ topology. node. In versions of IBM App Connect
Enterprise 11.0 before Fix Pack 7, these
message flow nodes require a local
server binding connection to an IBM MQ
Queue Manager. Consider altering your
IBM MQ topology as part of your move
to a container-based architecture.

Chapter 2. Migrating 49
 Table 5. Rules for the Transformation Advisor tool: (continued)
ID Title Can Can Solution
be be
found found
in a in a
backup BAR
file file
IIB11
An AggregateControl, True True The message flow contains an
AggregateRequest, or AggregateReply instance of an AggregateControl,
message flow node was found. You AggregateRequest, or AggregateReply
might want to consider altering your IBM message flow node. In versions of IBM
MQ topology. App Connect Enterprise 11.0 before
Fix Pack 7, these message flow nodes
require a local server binding connection
to an IBM MQ queue manager. Consider
altering your IBM MQ topology as part
of your move to a container-based
architecture. In IBM App Connect
Enterprise 12.0 the Group nodes are
suitable for similar aggregation use-
cases but they use in-memory queuing
and have no IBM MQ dependency.
IIB12
A KafkaConsumer or KafkaProducer True True The message flow contains an instance
message flow node was found. You of a KafkaConsumer or KafkaProducer
might want to consider changing the message flow node. In App Connect
version of your Kafka broker. Enterprise v11.0.0.4 (and earlier fix
packs), the product uses a Kafka client
at version 0.10.0.1. In App Connect
Enterprise v11.0.0.5 (and later fix
packs), the product uses a Kafka client
at version 2.20. You might want to
change to a different client version when
you consider the compatibility of your
Kafka broker.
IIB13
A JDEdwardsInput, JDEdwardsRequest, True True The message flow contains an
PeopleSoftInput, PeopleSoftRequest, instance of a JDEdwardsInput,
SiebelInput, or SiebelRequest message JDEdwardsRequest, PeopleSoftInput,
flow node was found. You might want PeopleSoftRequest, SiebelInput,
to consider the version of your App or SiebelRequest message flow
Connect Enterprise installation. node. These message flow nodes
are also supported in IBM App
Connect Enterprise 12.0. If you used
configurable service definitions with
these message flow nodes in IBM
Integration Bus 10.0, you might want to
consider the introduction of JDEdwards,
PeopleSoft, and Siebel policy types in
IBM App Connect Enterprise 12.0.

50 IBM App Connect Enterprise 12.0: User Guide

Table 5. Rules for the Transformation Advisor tool: (continued)
ID Title Can Can Solution
be be
found found
in a in a
backup BAR
file file
IIB14
An SAPInput or SAPRequest message True True The message flow contains an instance
flow node was found. You might want of an SAPInput or SAPRequest message
to consider changing the configuration flow node. These message flow nodes
of your App Connect Enterprise are also supported in IBM App Connect
installation. Enterprise 12.0, but IBM Integration
Bus configurable services are replaced
with policies. When you move to a
container-based architecture, consider
how to make the SAP JCo libraries
available to your containers and the
settings in server.conf.yaml.
IIB15
A deprecated graphical mapping True True The message flow contains an instance
message flow node was found. Convert of the old graphical mapping message
this node to the newer Mapping node. flow node. This type of message flow
node is no longer supported. You must
convert message maps to graphical data
maps. The Toolkit provides a conversion
tool for this purpose.
IIB16
A TCPIPServer message flow node True True The message flow contains an instance
was found. Consider altering the of a TCPIPServer message flow node.
configuration of your containers to open If you intend to use a non-default
the TCPIP port. TCPIP port in your containers, consider
changing your values.yaml file.
IIB17
A LoopBackRequest message flow True True The message flow contains an instance
node was found. Consider altering the of a LoopBackRequest message flow
configuration of your containers to node. Your IBM App Connect Enterprise
support this node. 12.0 installation provides Node Package
Manager (NPM) to configure the
Loopback Java™ script modules to
support this node. When you move to a
container-based architecture, consider
your build pipeline and its abilities to
configure these supporting files in your
container.
IIB18
A WebSphere Transformation Extender True True The message flow contains an instance
or IBM Transformation Extender of a WebSphere Transformation
message flow node was found. Consider Extender or IBM Transformation
changing the configuration of your Extender message flow node. IBM App
containers to support this node. Connect Enterprise 11.0 Fix Pack 4
(and later) supports the use of this type
of message flow node, which is used
with IBM Transformation Extender
v10. When you move to a container-
based architecture, consider this version
information.

Chapter 2. Migrating 51
 Table 5. Rules for the Transformation Advisor tool: (continued)
ID Title Can Can Solution
be be
found found
in a in a
backup BAR
file file
IIB19
An MQInput, MQOutput, or MQGet True True You might want to consider changing
message flow node that uses server to use IBM MQ client bindings when
bindings to a queue manager was found. you move to containers so that you can
You might want to consider changing use smaller containers. Independently
the node to use IBM MQ Client bindings scaling the integration servers in your
when you move to containers. architecture from your queue managers
is easier to achieve if you use client
bindings rather than server bindings.
IIB20
A Healthcare Pack artifact is deployed to True True A Healthcare Pack artifact is deployed
this server. to this server. The IBM Integration
Bus Healthcare Pack is not supported
in IBM App Connect Enterprise 12.0.
In App Connect Enterprise v11.0.0.8
(and later), support is provided for
applications in healthcare environments
through IBM App Connect for Healthcare
v5.0.0.0. Consider upgrading to App
Connect Enterprise v11.0.0.8 or later
and investigate the features that are
provided by App Connect for Healthcare
V5.0.0.0.
IIB21
A top-level message flow was found True True A top-level message flow was found
that originates in an integration project. that originates in an integration project.
These artifacts must be moved to the When top-level resources are migrated
default application in IBM App Connect by using the mqsiextractcomponents
Enterprise 12.0. command, they are moved to the
default application in IBM App Connect
Enterprise 12.0. Ensure that you
consider the groupings that you
require for all top-level resources.
The groupings are likely to involve the
adoption of application projects instead
of integration projects. Applications and
libraries (which were first introduced in
WebSphere Message Broker Version 8.0)
provide a more efficient way to isolate
and group message flows and their
associated artifacts. While BAR files that
contain top-level message flows can
still be deployed to IBM App Connect
Enterprise 12.0, these artifacts replace
previously deployed default application
content on each deployment. Consider
the groupings of message flows in light
of this change in iterative deployment
behavior.

52 IBM App Connect Enterprise 12.0: User Guide

Table 5. Rules for the Transformation Advisor tool: (continued)
ID Title Can Can Solution
be be
found found
in a in a
backup BAR
file file
IIB22
A top-level resource was found that True True A top-level resource was found. Top-
originates in an integration project. level resources are moved to the default
These artifacts are moved to the application when they are migrated to
default application in IBM App Connect IBM App Connect Enterprise 12.0 by
Enterprise 12.0. using the mqsiextractcomponents
command. When you migrate to
IBM App Connect Enterprise 12.0,
consider your groupings for all top-
level resources. The top-level resource
that this rule detected is likely to be
a dependency of a top-level message
flow. Consider which message flows
depend on this resource. Group the
resource so that it continues to be
available to the message flow when
the flow is moved from its integration
project to an application project. You
can look for instances of rule IIB21,
which detects top-level message flows
that might have a dependency on the
top-level resource that is highlighted by
this rule.
IIB23
A SOAPInput or HTTPInput message True False The message flow contains an instance
flow node was found that is using the of a SOAPInput or HTTPInput message
integration node-wide listener. flow node that is using the integration
node-wide listener. When you run
App Connect Enterprise in a container
architecture, you do not use an
integration node or the integration
node-wide listener. Instead, you use an
independent integration server with its
own embedded HTTP listener.
IIB24
Configuration indicates the use of the True False Record and Replay is available in IBM
Record and Replay feature. App Connect Enterprise 12.0. While you
can run this capability in a container-
based architecture, it depends on
a relational database and IBM MQ
publications.
IIB25
A SOAPInput or HTTPInput message True True The message flow contains an instance
flow node that uses HTTPS was found. of a SOAPInput or HTTPInput message
flow node that is using HTTPS. IBM App
Connect Enterprise 12.0 uses TLSv1.2,
and can also use TLSv1.3 for inbound
HTTPS communications. Ensure that
TLSv1.2, or TLSv1.3, are acceptable to
your Business Partner applications.

Chapter 2. Migrating 53
 Table 5. Rules for the Transformation Advisor tool: (continued)
ID Title Can Can Solution
be be
found found
in a in a
backup BAR
file file
IIB26
A globally coordinated message flow True True A globally coordinated message flow
was found. was detected. When you adopt a
container-based architecture, you
are unlikely to want to use globally
coordinated message flows in
your containers. You might want to
reconsider your architecture to avoid
global coordination, or to enable
these flows to keep running outside
containers.
IIB27
Configuration indicates the use of the True False The embedded global cache feature is
embedded global cache feature. available in IBM App Connect Enterprise
12.0. It is not advisable to use this
capability to share information between
integration servers in a container-
based architecture. If you do use this
capability, consider the placement and
persistence of your catalog servers.
IIB28
Configuration indicates the use of the True False The multi-instance high availability
multi-instance high availability feature. feature for integration nodes is available
in IBM App Connect Enterprise 12.0.
You are unlikely to use this model to
achieve high availability if you move to a
container-based architecture. If you do
use this model, consider the persistence
and disk requirements.
IIB29
An MRM message set dictionary was True True An MRM message set dictionary was
detected. detected. These artifacts are supported
for use in IBM App Connect Enterprise
12.0, but consider using DFDL message
modeling technology instead.

54 IBM App Connect Enterprise 12.0: User Guide

Table 5. Rules for the Transformation Advisor tool: (continued)
ID Title Can Can Solution
be be
found found
in a in a
backup BAR
file file
IIB30
A message flow with user-defined True True A message flow with user-defined
properties was found. properties was detected. Message
flows can continue to use user-defined
properties when deployed to IBM App
Connect Enterprise 12.0. If you are
moving to a container architecture, you
will probably not want to dynamically
change the value of user-defined
properties after deployment. Instead,
when you change configuration data,
you are likely to stop your container and
restart it with the new configuration
applied. In the unlikely event that you
want to dynamically update message
flow user-defined properties after
deployment, an administrative API
function is available in IBM App Connect
Enterprise 12.0. In general, when you
use container-based architectures, other
methods for providing configuration to
an independent integration server might
be preferable, such as a user-defined
policy.
IIB31
An IBM Integration Bus Activity Log True False When you migrate to IBM App Connect
configurable service was detected, Enterprise 12.0, IBM Integration Bus
which wrote to local files. Activity Log configurable services
are converted into Activity Log policy
documents. When you move to a
container-based architecture, you might
want to reconsider your chosen output
format for Activity Logging.
IIB32
An integration server was associated True False While artifacts can be carried forward,
with an integration node that specified due to changes in licensing, not all IBM
a product edition (that uses the Integration Bus software editions have
mqsimode command) that is no longer direct IBM App Connect Enterprise
available. 12.0 equivalents. Check with your
IBM representative to ensure that you
move to the appropriate App Connect
Enterprise edition and remain licensed
correctly in future.

Chapter 2. Migrating 55
 Table 5. Rules for the Transformation Advisor tool: (continued)
ID Title Can Can Solution
be be
found found
in a in a
backup BAR
file file
IIB33
An IBM Integration Bus configurable True False When you migrate to IBM App Connect
service was detected that cannot Enterprise 12.0, IBM Integration Bus
be updated dynamically when it is configurable services are converted into
converted to a policy in IBM App policy documents. Policy documents
Connect Enterprise 12.0. have several advantages, such as
they can be created by using Toolkit
templates and deployed in a BAR file.
Some policies cannot be updated
dynamically without the need to
restart an integration server. This
requirement does not typically apply in
container-based architectures. However,
depending on your use cases, you might
want to consider this requirement
when you migrate to IBM App Connect
Enterprise 12.0.
IIB34
A message flow that uses an MQTT True True A message flow uses an MQTT
Server was found. Server because it contains either
an MQTTPublish or MQTTSubscribe
message flow node. The built-in MQTT
Server that is provided by IBM App
Connect Enterprise 12.0 is not turned on
by default in a container.
IIB35
A message flow that uses an True True A message flow contains an
MQTTSubscribe node to monitor IBM MQTTSubscribe message flow node with
Integration Bus events was found. a topic root of IBM/IntegrationBus.
The presence of this node might mean
that you have a message flow that is
designed to monitor the product itself,
and to take further action when data
is received. You might want to review
this design pattern when you move
to a container-based architecture.
IBM Integration Bus 10.0 can be
configured to publish the following types
of information to MQTT: operational
events, admin events, business events,
flow statistics, and resource statistics.
IBM App Connect Enterprise 12.0
can be configured to publish the
following types of information to MQTT:
business events, flow statistics, and
resource statistics. The App Connect
Enterprise REST Administration API
provides methods that can be called to
provide operational and administration
information.

56 IBM App Connect Enterprise 12.0: User Guide

Migrating to IBM App Connect Enterprise 12.0
Complete the tasks to migrate to IBM App Connect Enterprise 12.0.

Before you begin

• Plan your migration by reading the topics in “Preparing for migration” on page 19.
• Complete pre-migration tasks by following the instructions in “Performing pre-migration tasks” on page
41.

About this task

Note: IBM App Connect Enterprise 12.0 does not include IBM Integration Explorer; therefore, you
cannot migrate IBM Integration Explorer. In IBM App Connect Enterprise 12.0, all integration node
administration is done by using the web user interface, the IBM Integration API, or commands. For more
information, see the following topics:
• web user interface
• #unique_95
• commands

Procedure
To migrate to IBM App Connect Enterprise 12.0, use one of the following methods.
• Use extract migration to migrate your integration servers and integration nodes by completing the
steps in “Performing extract migration of an integration node or integration server” on page 57.
You can use extract migration to migrate individual integration servers. Extract migration involves the
extraction of configuration and resources from your source system to IBM App Connect Enterprise
12.0.
• Alternatively, you can migrate your integration nodes by using parallel migration, as described in
“Performing parallel migration for an integration node ” on page 61.
• Migrate your development resources to IBM App Connect Enterprise 12.0 by following the instructions
in “Migrating development resources to IBM App Connect Enterprise 12.0” on page 62.

Performing extract migration of an integration node or integration server

You can use the mqsiextractcomponents command to migrate from IBM Integration Bus 10.0 or IBM
App Connect Enterprise 11.0 to IBM App Connect Enterprise 12.0. Use this command to migrate the
configuration and resources of an integration node and of integration servers that are managed by an
integration node.

Before you begin

• Plan your migration by reading the topics in “Preparing for migration” on page 19.
• Perform any pre-migration tasks by following the instructions in “Performing pre-migration tasks” on
page 41.
• Find out about extract migration and the folder structure that it creates, by reading “Extract migration
overview” on page 59.

About this task

Use the mqsiextractcomponents command to migrate integration nodes and managed integration
servers. Independent integration servers that were created in IBM App Connect Enterprise 11.0 can
be started in IBM App Connect Enterprise 12.0 without the need to migrate them or their resources.

Chapter 2. Migrating 57
 However, integration server work directories are typically created as transient rather than long-term
artifacts, and many users prefer to rebuild them when moving from one version to another.

Procedure
To complete extract migration for an integration node or a managed integration server, follow the
appropriate set of steps:
• “Performing extract migration of an integration node” on page 58
• “Performing extract migration of a managed integration server” on page 58

Performing extract migration of an integration node

Procedure
1. On your source system, run the mqsibackupbroker command, specifying the name of the integration
node that you intend to migrate to IBM App Connect Enterprise 12.0.
The following example backs up integration node INODE on Windows, and saves it in the archive file
C:\MQSI\BACKUP\INODE.zip:

mqsibackupbroker INODE -d C:\MQSI\BACKUP -a C:\MQSI\BACKUP\INODE.zip

For more information, see command.

2. Transfer the backup file that is created by the mqsibackupbroker command to an appropriate
location.
You can transfer the backup file to a location on the same system as the existing integration node, or to
a location on a different system.
3. Run the mqsiextractcomponents command on the system to which you transferred the backup file.
On the mqsiextractcomponents command, you must specify the following values:
• The name of the backup file that is created when you run the mqsibackupbroker command on the
source system
• The name in the backup file of the integration node from which you are migrating
• The name of the integration node to which to write the extracted configuration and resources
You can also specify one or more optional parameters on the mqsiextractcomponents command.
For more information, see command.
4. Optional: If you plan to run the migrated integration node on the same system as the existing
integration node, stop the existing integration node by running the mqsistop command before you
start the migrated integration node. For more information, see command.
5. Optional: If you plan to run the migrated integration node on the same system as the existing
integration node, and with the same name as the existing integration node, delete the existing
integration node by running the mqsideletebroker command before you start the migrated
integration node. For more information, see command.
6. Start the migrated integration node by using the mqsistart command. For more information, see
command.
7. After the mqsistart command completes, check the syslog, or the Windows Event log to confirm that
the integration node has started successfully with no errors.

Performing extract migration of a managed integration server

Procedure
1. On your source system, run the mqsibackupbroker command, specifying the name of the integration
node that is associated with the integration server that you intend to migrate to IBM App Connect
Enterprise 12.0.

58 IBM App Connect Enterprise 12.0: User Guide

2. Transfer the backup file that is created by the mqsibackupbroker command to an appropriate
location on your Version 12.0 system.
3. Run the mqsiextractcomponents command on your Version 12.0 system.
On the mqsiextractcomponents, you must specify the following values:
• The name of the backup file that is created when you run the mqsibackupbroker command on the
source system
• The name of the integration node with which the integration server that you are migrating is
associated
• The name of the integration server that you are migrating
• The work directory to which the integration server components are to be extracted
You can also specify one or more optional parameters on the mqsiextractcomponents command.
For more information, see command.
4. When the mqsiextractcomponents command completes successfully, start the integration server
on your Version 12.0 system by using the IntegrationServer command.

What to do next
When you complete migration, see the tasks in “Performing post-migration tasks” on page 64 for
information about tasks that you might want to complete after migration.

Extract migration overview

You can use the mqsiextractcomponents command to migrate the configuration and resources of
integration servers and integration nodes from your source system to your IBM App Connect Enterprise
12.0 system. The command extracts the configuration and resources from your source system and
re-creates them in a directory structure on your target system. You can extract the configuration and
resources from an integration node, including the configuration and resources from all of the integration
servers that are associated with the integration node, or from individual integration servers on your source
system.
The following information describes the folder structure that is created when you use extract migration on
an integration node or an integration server.

Extract migration of an integration node

The extract migration of the configuration of an integration server or integration node from an earlier
version results in the re-creation of the integration server or integration node on your IBM App Connect
Enterprise 12.0 system. A node folder is created in the installation directory, or in the directory in which
you have your registry. The resources that comprise the integration node configuration on your source
system are put into the node folder. The configuration of all the integration servers that are associated
with the integration node is also extracted, resulting in the re-creation of these integration servers on
your Version 12.0 system. A server sub-folder is created in the node folder for each integration server.
The resources that comprise each integration server configuration on your source system are put into the
corresponding server sub-folder.
The following table summarizes the folder structure that is created when you perform extract migration of
an integration node.

Table 6.
Folder Sub-folder Sub-folder Sub-folder Contents/description
<node node.conf.yaml file. This file contains
name> the settings for your migrated integration
node. You can override the settings in
the node.conf.yaml file by using the
mqsichangeproperties command.

Chapter 2. Migrating 59
 Table 6. (continued)
Folder Sub-folder Sub-folder Sub-folder Contents/description
servers Sub-folders for every integration server that
is server associated with the integration node.
One sub-folder exists for each integration
server.
<server Sub-folders containing the integration server
name> configuration and resources. The name of the
sub-folder is the same as the name of the
integration server.
run Deployed resources.
overrides server.conf.yaml file. This file contains
the settings for the integration server.
You can override the settings in the
server.conf.yaml file by using the
mqsichangeproperties command.
policies Sub-folders for every policy that is created
from a configurable service on the integration
node on the source system.
NodePolicies
policy_name.policy.xml
One policy file per migrated configurable
service. The file contains the policy
information.

Extraction of configuration and resources of an integration server

The extract migration of the configuration of an integration server from an earlier version results
in the re-creation of an independent integration server on your IBM App Connect Enterprise 12.0
system. You might want to migrate an integration server in this way if you are operating in a container-
based environment. The resources that comprise the integration server configuration are put into
a work directory on your Version 12.0 system. You specify the work directory when you use the
mqsiextractcomponents command.
The following table summarizes the directory structure that is created when you perform extract
migration of an integration server.

Table 7.
Folder Sub-folder Contents/description
<work_directory_name> server.conf.yaml file. This file contains the settings
for your migrated integration server. You can override
the settings in the server.conf.yaml file by using the
mqsichangeproperties command.
run Deployed resources, including policy projects, libraries, and
applications.
overrides server.conf.yaml file. This file exists if you dynamically
override settings in the integration server server.conf.yaml
by using the mqsichangeproperties command.

60 IBM App Connect Enterprise 12.0: User Guide

 Table 7. (continued)
Folder Sub-folder Contents/description
log Files containing event log and syslog entries.
By default, file names are of the format
integration_server.integration_server_name.entries.txt.n
where n is an integer in the range 1 through 9. When the
integration server generates log entries, the most recent log
data is held in a file that does not have the n suffix. As the
data ages, it is held in files with the n suffix where the value
of n increments with the age of the log data: the oldest data is
held in the file that is suffixed 9. The files fill in an incremental
fashion; when one file becomes full, entries are written to the
next consecutive file.
config Files containing other configuration information such as
security configuration.

To complete extract migration, follow the instructions in “Performing extract migration of an integration
node or integration server” on page 57.

Performing parallel migration for an integration node

You can use parallel migration to do a staged migration process by creating a new Version 12.0 integration
node to run in parallel with your existing integration node. You can then migrate your application logic
from your existing integration node to your new integration node.

Before you begin

• Plan your migration by reading the topics in “Preparing for migration” on page 19.
• Complete pre-migration tasks by following the instructions in “Performing pre-migration tasks” on page
41.
• If your deployment uses functions that integrate with IBM MQ, or requires that the integration node
has a specified queue manager, make sure that you have a supported version of IBM MQ. For more
information, see “Installing IBM MQ” on page 96.
– If you are reusing an existing IBM MQ deployment, migrate your queue managers and other
resources to a supported version of IBM MQ by following the instructions in the IBM MQ product
documentation.
Note: If you are reusing an existing IBM MQ deployment, you can configure the new IBM App
Connect Enterprise 12.0 integration nodes to use the same queue managers as the existing
integration nodes. You do not have to create new queue managers for the new integration nodes.
– If you are installing a new IBM MQ deployment, create one or more queue managers to support the
necessary configuration for your IBM App Connect Enterprise 12.0 integration nodes.
• Check that you have no aggregations in progress on this integration node. When you migrate an
integration node to Version 12.0, all live data that is being stored for aggregations in progress is lost.

Procedure
1. Install IBM App Connect Enterprise 12.0 on the same computer as your existing version, or on a
different computer.
If you are installing on the same computer, you must specify a different location.
2. Migrate your development resources to the IBM App Connect Enterprise Toolkit Version 12.0 (see
“Migrating development resources to IBM App Connect Enterprise 12.0” on page 62).

Chapter 2. Migrating 61
 3. Set up the correct Version 12.0 command environment for your operating system.
•
On Linux systems, open a new shell and run the environment profile mqsiprofile for
this Version 12.0 installation.
•
On Windows, click Start, and open the Command Console that is associated with this
Version 12.0 installation.
4. Create a Version 12.0 integration node by using the mqsicreatebroker command or the IBM App
Connect Enterprise Toolkit. Give the integration node a name that is different from the name of the
existing integration node.
If any of the resources on the existing integration node require IBM MQ, specify a suitable queue
manager for the new integration node (see “Installing IBM MQ” on page 96).
5. Start the Version 12.0 integration node by using the mqsistart command.
You can also start a local integration node by using the IBM App Connect Enterprise Toolkit.
6. Make a list of the integration servers that you have on the existing integration node, and create these
same integration servers on the Version 12.0 integration node.
Use the web user interface, the IBM App Connect Enterprise Toolkit Version 12.0, or the
mqsicreateexecutiongroup command to complete this step.
7. Deploy the message flows, applications, and libraries that are in use by the existing integration node to
the Version 12.0 integration node from the Version 12.0 IBM App Connect Enterprise Toolkit.
8. Configure all other relevant properties of the existing integration node on the Version 12.0 integration
node.
9. To delete your existing integration node, complete the following steps:
a) In a command environment for your previous version, stop the original integration node by using
the mqsistop command.
b) Remove the original integration node from the IBM App Connect Enterprise Toolkit.
c) In a command environment for your previous version, delete the original integration node by using
the mqsideletebroker command.

What to do next
When you complete migration, check whether you need to complete any post-migration tasks in
“Performing post-migration tasks” on page 64.

Migrating development resources to IBM App Connect Enterprise 12.0

You cannot migrate the IBM Integration Toolkit from previous versions, but you can install IBM App
Connect Enterprise 12.0 to coexist with a previous version. You can then migrate the development
resources to the IBM Integration Toolkit Version 12.0 by using a project interchange file.

Before you begin

Be aware of the following restrictions that apply after you migrate resources to IBM App Connect
Enterprise Toolkit Version 12.0.
• You cannot share the development resources with previous versions of the IBM Integration Toolkit.
When you create a new project in IBM App Connect Enterprise Toolkit Version 12.0, it is created in

62 IBM App Connect Enterprise 12.0: User Guide

 a format that cannot be used in previous versions of the IBM Integration Toolkit. You can take the
following steps to manage development with different versions of the IBM Integration Toolkit.
– If you are using a version control system, create a new stream for use with the new version of your
project.
– If you expect to continue development of a project for an integration node at a version before Version
12.0, you must retain an IBM Integration Toolkit at the previous version.
– If you need to continue development of the same project for integration nodes on both Version 12.0
and a previous version, ensure that you use the IBM Integration Toolkit from the previous version for
development.
• You cannot deploy resources from IBM App Connect Enterprise Toolkit Version 12.0 to integration
nodes at a previous version to Version 12.0.
• You can use the IBM Integration Explorer view of the IBM App Connect Enterprise Toolkit to add
connections for integration servers and integration nodes. IBM App Connect Enterprise Toolkit Version
12.0 supports Version 12.0 integration servers and integration nodes only. Connections to integration
servers and integration nodes that are running on previous releases are not supported.
• If any of the following actions cause an error in the project, the IBM App Connect Enterprise Toolkit
marks the error, and you can use a Quick Fix to rectify the error.
– Creating the metadata information for the user-defined node project
– Correcting the plug-in identifier if it does not match the project name
– Ensuring all the user-defined nodes are in the same category
For more information, see “Applying a Quick Fix to a task list error” on page 2318. However, if you have
different user-defined nodes that depend on different resources that have identical names, the BAR file
compiler produces an error that indicates a naming conflict in the dependent resources.

About this task

You can continue to use resources from a previous version of IBM Integration Bus by importing them into
an IBM App Connect Enterprise Toolkit Version 12.0 workspace. After you import resources, you can no
longer use them in a previous version of the IBM Integration Toolkit.

Procedure
1. In the previous version of the Toolkit, export the resources that you want to use in IBM App Connect
Enterprise Toolkit Version 12.0.
a) Click File > Export.
The Export wizard opens.
b) Expand Other, click Project Interchange, then click Next.
c) Select the projects that you want to export, and specify the location for the compressed file that is
created. You can save the file to a folder on your file system, or to a disk drive.
d) Click Finish.
The project interchange file is created in the specified location.
2. Create an IBM App Connect Enterprise Toolkit Version 12.0 workspace, or open an existing one.
3. Import the project interchange file into the Version 12.0 workspace.
a) Click File > Import.
The Import wizard opens.
b) Expand IBM Integration, click Project Interchange, then click Next.
c) Specify the location of the project interchange file that you created in step 1.
d) Specify the location of the open Version 12.0 workspace.
e) Select the projects that you want to import into your Version 12.0 workspace, then click Finish.

Chapter 2. Migrating 63
Performing post-migration tasks
After you migrate to IBM App Connect Enterprise 12.0, finish setting up your environment.

About this task

Test the IBM App Connect Enterprise 12.0 integration node and integration server resources and
components to verify that they are all present and working correctly. Some changes in behavior might be
caused by defects that were fixed between versions.
The following topics describe tasks that you can complete after migration.

Procedure
• “Setting up a command environment” on page 64
• “Reconfiguring administration security after migration” on page 65
• “Setting up a global cache” on page 65
• “Migrating deployable resources” on page 66

What to do next
After you complete migration, use the product documentation for the previous version to complete the
following tasks.
• Delete the components from the previous version.
• Remove the installed code for the previous version.

Setting up a command environment

Runtime components and commands that administer runtime components must be run from a command
environment. You must initialize this environment by running the mqsiprofile command.

About this task

The mqsiprofile command places the Version 12.0 commands and libraries at the front of your search
path, and can override any combination of PATH, CLASSPATH, or library PATH.
ODBC settings on Linux systems are found in a text file that is defined by the ODBCINI environment
variable. If you are using Linux, set ODBCINI to point to a copy of the sample file install_dir/
server/ODBC/unixodbc/odbc.ini, where install_dir is the IBM App Connect Enterprise installation
directory.
On Linux, if you want to use IBM MQ features, you must set the IBM MQ environment where you want the
integration server to run; for more information, see “Setting the IBM MQ environment on Linux and AIX”
on page 84.
Ensure that you use this environment each time you run an administrative command, or start an
integration server.
The mqsiprofile command also runs extra scripts that are copied to the common\profiles directory
(on Windows) or the common/profiles directory (on Linux systems). These scripts can be used to
initialize the environment for runtime components and other resources, such as databases.
The following steps explain how to initialize your command environment, either by explicitly running the
mqsiprofile command (on Linux) or by starting the command console (on Windows).

Procedure
• On Windows, open a command console by searching for IBM App Connect Enterprise Console. If you
have multiple installations of IBM App Connect Enterprise, make sure that you are running the IBM

64 IBM App Connect Enterprise 12.0: User Guide

 App Connect Enterprise Console from the build of the IBM App Connect Enterprise installation that you
want to administer.
• On Linux systems, locate and run the mqsiprofile.sh script in the directory in which you installed
the appropriate product.

. install_dir/server/bin/mqsiprofile

You must include the period and space for this command to work correctly. If you want to run this
command at the start of every session, add it to your login profile.
If you use the zsh shell, running the mqsiprofile might cause the terminal session to exit.
To resolve this issue, run the unsetopt function_argzero command before you run the
mqsiprofile command.

What to do next
From the command line in the initialized environment, you can run commands to administer IBM App
Connect Enterprise. For example, you can configure and start an integration server, as described in
“Configuring an integration server by modifying the server.conf.yaml file” on page 172 and “Starting an
integration server” on page 250.

Reconfiguring administration security after migration

After migration, you can reconfigure your administration security to use file-based permissions that are
set on your integration nodes.

About this task

In IBM Integration Bus 10.0, you can configure administration security by using queue-based permissions
or file-based permissions on your integration nodes. In IBM App Connect Enterprise 12.0, you must use
file-based permissions. For more information, see “Configuring administration security to use file-based,
queue-based, or LDAP authorization” on page 2523.

Setting up a global cache

After migration of an integration node that is configured with a global cache, extra steps might be needed
to complete the global cache configuration.

About this task

In IBM App Connect Enterprise 12.0, the global cache configuration involves setting the
cacheServerName parameter, which must be unique in your global cache system.
If the name of the target integration node is the same as the name of the source integration node, no
further configuration is needed. However, if the name of the target integration node is different from the
name of the source integration node, make the following changes to complete the configuration of the
global cache.

Procedure
• Define a unique cacheServerName in the server.conf.yaml files for the integration servers, and
update the cacheServerName value in the catalogClusterEndPoints property.
Consider this example: if the node IB10NODE is migrated from IBM Integration Bus 10.0 to IBM App
Connect Enterprise 12.0 with the name ACE12NODE, the value of catalogClusterEndPoints
is IB10NODE_localhost_2800:localhost:2803:2801. After migration, specify a value
of, for example, ACE12CatalogServer in cacheServerName and update the value in

Chapter 2. Migrating 65
 catalogClusterEndPoints to be ACE12CatalogServer:localhost:2803:2801, as shown in
the following sample global cache stanza for a catalog server.

GlobalCache:
cacheOn: true
cacheServerName: 'ACE12CatalogServer'
catalogClusterEndPoints: 'ACE12CatalogServer:localhost:2803:2801'
catalogDomainName: 'WMB_IB10NODE_localhost_2800'
catalogServiceEndPoints: 'localhost:2800'
enableCatalogService: true
enableContainerService: true
enableJMX: true
haManagerPort: 2801
jmxServicePort: 2802
listenerHost: 'localhost'
listenerPort: 2800

Similarly, define a unique cacheServerName for the container server too. The value of
catalogClusterEndPoints is the same for all the integration servers that participate in the
global cache configuration. The global stanza for a container server, with a cacheServerName of
ACE12ContainerServer2 looks like the following example:

GlobalCache:
cacheOn: true
cacheServerName: 'ACE12ContainerServer2'
catalogClusterEndPoints: 'ACE12CatalogServer:localhost:2803:2801'
catalogDomainName: 'WMB_IB10NODE_localhost_2800'
catalogServiceEndPoints: 'localhost:2800'
enableCatalogService: false
enableContainerService: true
enableJMX: true
haManagerPort: 2805
jmxServicePort: 2806
listenerHost: 'localhost'
listenerPort: 2804

Migrating deployable resources

You can continue to use existing resources in IBM App Connect Enterprise. However, if you want to
continue developing resources created in previous versions, you must migrate them.

About this task

The following table summarizes the type of resource that you must migrate into IBM App Connect
Enterprise 12.0 if you want to continue developing them.

Table 8. Existing resources that require extra migration tasks

Resource to continue
developing in Version
12.0 Resource that is created in Version 10.0
Message sets You must enable the menus for message set development (see “Migrating
message sets” on page 67).
Message maps You must complete the migration of message maps to graphical data maps
for those existing message maps that you did not convert when you migrated
to Version 10.0. New maps that are created in Version 10.0 are graphical data
maps. See “Migrating message maps” on page 67.
Message flows If your message flows include message flow nodes that are no longer
available, rework your message flows to use available message flow nodes.
See “Migrating message flows” on page 68.

66 IBM App Connect Enterprise 12.0: User Guide

Table 8. Existing resources that require extra migration tasks (continued)
Resource to continue
developing in Version
12.0 Resource that is created in Version 10.0
Subflows You must complete the migration of the existing subflows that you did not
convert when you migrated to Version 10.0. New subflows that are created
in Version 10.0 are created as .subflow files. See “Migrating subflows” on
page 68.
Custom integration If you have applications that use the IBM Integration API, check that they
applications access the correct resources. See “Migrating custom integration applications”
on page 68.

Migrating message sets

About this task

In IBM App Connect Enterprise, message model schema files contained in applications, integration
services, and libraries are the preferred way to model messages for most data formats. Message sets
are required if you use the MRM or IDOC domains. For more information about message modeling, see
“Message modeling concepts” on page 2134.
You can import message flows that contain message sets from previous versions into IBM App Connect
Enterprise 12.0. Your existing message sets can be viewed, modified, and deployed in the usual way.
However, by default, the menu options for creating new message sets or message definition files are
hidden. To complete these tasks, you must first enable message set development in the IBM App Connect
Enterprise Toolkit Preferences. For more information, see “Enabling message set development” on page
2248.

Migrating message maps

About this task

IBM App Connect Enterprise 12.0 includes a graphical data mapping capability, which is used when you
add a Mapping node to a message flow.
You can import message flows containing the following nodes, which use message mapping into IBM App
Connect Enterprise 12.0:
• DataDelete
• DataInsert
• DataUpdate
• Extract
• Mapping
• Warehouse
The message map (.msgmap) on these nodes can be viewed but they cannot be deployed to the runtime
environment because they are not available in IBM App Connect Enterprise 12.0. The message-mapping
operations from previous versions are accessible only in read-only mode and cannot be modified or
deployed.
To deploy a message flow that uses an existing message map (.msgmap file), you must first replace the
existing node with a new Mapping node. You must also convert the existing message map to a graphical
data map that can be used by the new Mapping node (.map file). For more information, see Converting a
message map from a .msgmap file a .map file.

Chapter 2. Migrating 67
 Migrating message flows

About this task

The message flow nodes that are available in IBM App Connect Enterprise 12.0 might be different from
the nodes that are available in the version from which you are migrating. If your message flows contain
message flow nodes that are no longer available, you must rework them to use only those message flow
nodes that are available at IBM App Connect Enterprise 12.0.

Migrating subflows

About this task

Since WebSphere Message Broker Version 8, you create subflows as .subflow files.
Subflows from earlier versions of the product were created as .msgflow files. You must convert them
into .subflow files if you want to continue developing them in IBM App Connect Enterprise 12.0. You
convert these subflows by using the function Convert to subflow. For more information, see “Converting
between message flows and subflows” on page 576.

Migrating custom integration applications

About this task

Your existing Version 10.0 custom integration applications can be migrated to work with
Version 12.0 integration nodes. However, if you are writing new applications, ensure that
you use the com.ibm.integration.admin.proxy.* classes rather than the deprecated
com.ibm.broker.proxy.*.
The IBM Integration API is no longer asynchronous because it is backed by synchronous REST
calls. As a result, the AdministeredObjectListener framework is no longer available, and
no processModify(), processDelete() callbacks exist. You must call refresh on the proxy
objects to get the latest property values, such as for the deprecated Execution Group Proxy
myExecutionGroupProxy.refresh().

Procedure
1. For custom integration applications that connect to an integration node, update the connection details
that are used by your custom integration applications to connect to the appropriate integration node.
In IBM App Connect Enterprise 12.0, the IBM Integration API connections are no longer dependent on
IBM MQ, and so connections are no longer made by using IBM MQ queues.
2. If you are connecting to a remote integration node, update your connection details to use the web
administration port. For more information, see “Configuring the IBM App Connect Enterprise web user
interface” on page 87.
For information about using SSL on these connections, see “Connecting to an integration node by using
the Toolkit” on page 245. If you are connecting to a local integration node, you can use a direct local
connection.
3. If administration security is enabled, in IBM App Connect Enterprise 12.0, user credentials are needed
by integration applications that use a remote connection. If the connection is local, you must run the
application under a user ID that is part of the mqbkrs group. For new integration applications, you can
provide user details during application development. For existing compiled applications, you must
supply the security credentials by using one of the methods that is described in “Connecting to an
integration node from a custom integration application” on page 447.

68 IBM App Connect Enterprise 12.0: User Guide

Chapter 3. Installing and uninstalling IBM App
Connect Enterprise
Install and uninstall IBM App Connect Enterprise and complementary products.

About this task

Use the following topics to learn how to install and uninstall IBM App Connect Enterprise and optional
complementary products on all supported platforms.

Installing IBM App Connect Enterprise

Review the tasks that are involved in the installation of IBM App Connect Enterprise.

About this task

The tasks that you perform to complete the installation are listed in the following steps; each task
indicates whether it is required or optional. A summary of each task is provided, along with pointers to
topics or sections that describe the task in more detail.
Service updates and other fixes are delivered occasionally in the form of fix packs. You can find
information about available fix packs on the IBM App Connect Enterprise support web page. IBM App
Connect Enterprise fix packs are complete App Connect Enterprise installations and are installed in the
same way as the initial product release. You can install a fix pack on the same computer as a previous
release, or on a different computer; for information about installing more than one fix pack (at the same
or different levels) on a single computer, see “Coexistence of IBM App Connect Enterprise 12.0 with
previous versions” on page 70. For more information about applying service updates, see “Applying
service to IBM App Connect Enterprise” on page 90.

Procedure
1. Required: Make sure that you have acquired the product packages that you need for installation.
Electronic images of IBM App Connect Enterprise are available from the IBM Passport Advantage®
website.
2. Required: Make sure that you have access to the product documentation that you need for installation;
see “Finding the latest information” on page 1.
3. Required: Determine the platforms on which to install IBM App Connect Enterprise.
On Windows and Linux, the IBM App Connect Enterprise installation includes IBM App Connect
Enterprise Toolkit. For more information, see #unique_127.
4. Required: Prepare each computer on which you are installing IBM App Connect Enterprise.
a) Required: Check that your target computers meet the initial hardware, storage, and software
requirements.
For more information, see the IBM App Connect Enterprise system requirements web page.
b) Required: Understand the security requirements for running IBM App Connect Enterprise; see
“Security requirements” on page 72.
c) Optional: Configure temporary directory space to enable IBM App Connect Enterprise Java
components to operate correctly; see “Configuring temporary space on distributed systems” on
page 74.
d) Optional: If you are installing IBM App Connect Enterprise on Linux or AIX, check your kernel
configuration; see “Checking the kernel configuration on Linux and AIX” on page 75.

© Copyright IBM Corp. 2016 69

 5. Required: Install IBM App Connect Enterprise; see “Installing IBM App Connect Enterprise software”
on page 75.
6. Optional: If required, install one or more language packs for IBM App Connect Enterprise Toolkit; see
Installing language packs for the IBM App Connect Enterprise Toolkit.
7. Optional: Set up a command environment so that you can run administrative commands; see “Setting
up a command environment” on page 64.
8. Optional: If required, install any complementary products; see “Installing and uninstalling
complementary products” on page 96.

Results
You have reviewed the installation steps.

Coexistence of IBM App Connect Enterprise 12.0 with previous versions

IBM App Connect Enterprise 12.0 can coexist with IBM App Connect Enterprise 11.0 and IBM Integration
Bus 10.0, so that you can test and compare functional differences between the versions.
You can control your migration to IBM App Connect Enterprise 12.0 by migrating individual integration
nodes and integration servers; you do not have to migrate all integration nodes or servers at the same
time. For more information, see Chapter 2, “Migrating,” on page 19.
The following sections describe how to achieve coexistence, and explain the restrictions that apply for
each platform:
• “Coexistence on Windows” on page 70
• “Coexistence on Linux and AIX” on page 71
When you have an environment that contains different versions of IBM App Connect Enterprise and IBM
Integration Bus, the following tasks have limitations:
Editing source artifacts in the IBM App Connect Enterprise Toolkit
Artifacts cannot be shared between different versions of the IBM App Connect Enterprise Toolkit and
IBM Integration Toolkit. Changes made to an artifact by using the IBM App Connect Enterprise Toolkit
make the artifact incompatible with earlier versions of the IBM Integration Toolkit. Consider branching
your version control system when you migrate to a new version.
Building BAR files from artifacts
Your build system must use the same or later version as the IBM App Connect Enterprise Toolkit or
IBM Integration Toolkit system that was used to create the artifact. A build system cannot build a BAR
file from an artifact that was created or edited in a later version of the IBM App Connect Enterprise
Toolkit or IBM Integration Toolkit.
Deploying BAR files to an integration node
You can deploy BAR files that are built with one version of IBM Integration Bus (by using the IBM
Integration Toolkit, mqsicreatebar, or mqsipackagebar) to an integration node at a later version.
You do not have to rebuild your BAR files. However it is not supported to deploy BAR files to an
integration node at an earlier version. The BAR files are likely to contain new properties that cause
deployment errors.

Coexistence on Windows
The following restrictions apply to coexistence on Windows.
• You can install multiple instances of IBM App Connect Enterprise on the same computer, but you cannot
install multiple instances of a product version at the same modification or fix pack level. For example,
you can install Version 12.0.2.0 on the same computer as Version 12.0.1.0, but you cannot install two
instances of Version 12.0.1.0 on the same computer.
• All integration nodes from all versions are accessible by all users of the Windows system, and must have
unique names.

70 IBM App Connect Enterprise 12.0: User Guide

 • Each integration node is associated with the product code from a specific installation location and uses
that product code when the integration node is started.
• If you have more than one installation on a single computer, ensure that the commands that you issue
to integration nodes on that computer are using the correct version of installed code. On Windows, an
IBM App Connect Enterprise Console is available for each installation. You must run commands in the
correct instance of the IBM App Connect Enterprise Console for a particular installation.
If you prefer, you can run the mqsiprofile command. By default, this command is stored in C:
\Program Files\IBM\ACE\12.0.n.0\server\bin.

Coexistence on Linux and AIX

The following restrictions apply to coexistence on Linux and AIX:
• You can install multiple instances of IBM App Connect Enterprise and IBM Integration Bus on the same
computer, including multiple instances of a product version at the same modification or fix pack level.
• Each integration node can be either part of a shared installation or part of a single-user installation.
Integration nodes that are part of a shared installation are accessible by all users of the IBM App
Connect Enterprise installation. Integration nodes that are part of a single-user installation are only
accessible by a specific user.
• Integration nodes are not automatically associated with product code from specific installation
locations. Before you start the integration node, you must run the mqsiprofile command that is
associated with the product code that the integration node should use. The command is stored in
install_dir/ace-12.0.n.0/server/bin, where install_dir is the directory where you unpacked
the IBM App Connect Enterprise software. If you add the mqsiprofile command to your system login
profile, it is run automatically whenever you log on.
• If you have more than one installation on a single computer, you must ensure that the commands that
you issue to integration nodes on that computer are using the correct version of installed code. You
must run the mqsiprofile command to set up the correct environment before you run other IBM App
Connect Enterprise commands, such as mqsicreatebroker.
If you installed an earlier version of this product on the same computer, check that the earlier
mqsiprofile command is not included in the system profile for the current user ID. The environment
that is set up by the mqsiprofile command of a previous version of IBM Integration Bus is not
compatible with a later version of IBM App Connect Enterprise. To avoid potential problems, consider
using a different user ID for each version and add the correct command for each version to the system
profile of each user ID. For more information about the mqsiprofile command, see “Setting up a
command environment” on page 64

Preparing the system

Complete the prerequisite tasks for your operating system before you install IBM App Connect Enterprise.

About this task

Before you install IBM App Connect Enterprise, read the topics that are relevant to your operating system:
• For Windows:
1. “Security requirements” on page 72
2. “Configuring temporary space on distributed systems” on page 74
• For Linux or UNIX systems:
1. “Security requirements” on page 72
2. “Configuring temporary space on distributed systems” on page 74
3. “Checking the kernel configuration on Linux and AIX” on page 75
If you are using IBM MQ, configure the default settings for the log; see Default IBM MQ log settings.

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 71

 For performance reasons, set the log size to the largest that the IBM MQ version that are using can
support. If you are using a production system, consider using linear logging. By default, queue manager
logs default to circular logging and use 3 x 1 MB log files.

What to do next
• On distributed systems, install IBM App Connect Enterprise; see “Installing IBM App Connect
Enterprise software” on page 75.

Security requirements
Understand the security requirements before you install IBM App Connect Enterprise.
The security of IBM App Connect Enterprise components, resources, and tasks depends on the definition
of users and groups configured in the operating system.
Some operating systems and other products impose restrictions on the structure and composition of user
IDs:
• On Windows systems, user IDs can be up to 12 characters long, but on Linux and UNIX systems they
are restricted to 8 characters. Database products, for example DB2®, might also restrict user IDs
to 8 characters. If you have a mixed environment, ensure that the user IDs in the IBM App Connect
Enterprise environment are limited to a maximum of 8 characters.
• Ensure that the case (upper, lower, or mixed) of user IDs in your IBM App Connect Enterprise
environment is consistent. In some environments, uppercase and lowercase user IDs are considered
the same, but in other environments, user IDs of different case are considered unique. For example,
on Windows the user IDs 'tester' and 'TESTER' are identical, but on Linux and UNIX systems they are
recognized as different user IDs.
• Check the validity of spaces and special characters in user IDs to ensure that, if used, these characters
are accepted by all relevant systems and products in your IBM App Connect Enterprise environment.
If your user ID does not conform to these restrictions, you might have problems with installation or
verification. If so, use an alternative user ID, or create a new one, to complete installation and verification.
Understand the security requirements that are associated with the operating systems that you are using:
• If you are installing on Linux or UNIX systems, see “Security on Linux and UNIX systems” on page 72.
• If you are installing on Windows, see “Security on Windows” on page 73.
•
When you have installed IBM App Connect Enterprise, check the Security topics in the IBM App
Connect Enterprise product documentation to review and implement the security requirements for the
performance of other tasks; see Chapter 8, “Security,” on page 2491.

Security on Linux and UNIX systems

Understand the security requirements on Linux and UNIX systems before you install IBM App Connect
Enterprise.
To deploy a single-user installation of IBM App Connect Enterprise on Linux or UNIX systems, you must
have a user account on the system where you install IBM App Connect Enterprise. The user account
does not need super user access to the system. After the deployment, the IBM App Connect Enterprise
installation can be used by only you.
To deploy a shared installation of IBM App Connect Enterprise on Linux or UNIX systems, you must log
in as root or as a super user who has write access to the /var directory. After the deployment, a security
group that is called mqbrkrs is created (if this group does not already exist). To enable users to use the
shared installation of IBM App Connect Enterprise, add the users to the mqbrkrs group by using the
security facilities that are provided by your operating system; for example, the Systems Management
Interface Tool (SMIT) on AIX, or the System Administration Manager on HP-Itanium.

72 IBM App Connect Enterprise 12.0: User Guide

Security on Windows
Understand the security requirements on Windows before you install IBM App Connect Enterprise.
To install IBM App Connect Enterprise on Windows, you must have the authority to install software on the
system.
When you install IBM App Connect Enterprise, the installation wizard calls the mqsisetsecurity
command, which completes the following tasks:
• Creates a security group called mqbrkrs.
• Adds your current user ID to the group mqbrkrs.
If you want to use IBM App Connect Enterprise with a different user ID from the ID that you use to install
the product, you must add that user ID to the mqbrkrs group. Use either the Windows security facilities or
the mqsisetsecurity command to complete this task; see command.
For an example that uses a Windows domain group topology to run IBM App Connect Enterprise in a
Windows domain environment, see “Security in a Windows domain environment” on page 73.

Windows Terminal Services

If you are installing IBM App Connect Enterprise on a computer that runs Terminal Services, change
the user mode to install before you start the installation, to ensure that actions taken during the
installation are completed correctly; for example, that .ini files and other related files are created in the
default system directory (C:\Windows). Restore the user mode to execute after the installation.

Security in a Windows domain environment

An example that uses a Windows domain group topology to run IBM App Connect Enterprise in a Windows
domain environment.

About this task

You can use Windows domain groups to organize different levels of authorization to selective IBM App
Connect Enterprise resources across your domain. To design and implement this domain group topology,
add each domain group to the relevant local security groups on the domain workstations. You can now
manage authorities by adding domain user accounts to the appropriate domain groups.

Procedure
1. Design your authorization group categories, and define domain groups on the domain controller
system that correspond to these authorization categories, by using Windows security.
For example, suppose that you have a single domain that contains three distinct sets of systems, which
are used in development, testing, and production. Within your organization, various user roles require
different levels of authorization to IBM App Connect Enterprise resources on those systems.
Here is an example of how those authorization categories might map to domain groups:

Domain group Description

ADM-MBprd IBM App Connect Enterprise administrator
authorities on production systems
ADM-MBuat IBM App Connect Enterprise administrator
authorities on test systems
ADM-MBdev IBM App Connect Enterprise administrator
authorities on development systems

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 73

 2. Define and configure domain user accounts on the domain controller, by using Windows security.
Add each domain user account to one or more domain groups to configure the access for that account.
For example:

Table 9.
Domain user account Role Domain group membership
MBadmPRD IBM App Connect Enterprise ADM-MBprd
administrator for production
systems
MBadmUAT IBM App Connect Enterprise ADM-MBuat
administrator for test systems
MBadmDEV IBM App Connect Enterprise ADM-MBdev
administrator for development
systems
john.smith IBM App Connect Enterprise ADM-MBuat, ADM-MBdev
administrator for test and
development systems
3. Install and configure IBM App Connect Enterprise on domain workstations.
a) Install IBM App Connect Enterprise on the workstation.
b) Add your domain groups to the local mqbrkrs group as appropriate.
In this example, if a particular workstation is to serve as a development system, add the domain
group ADM-MBdev to the local mqbrkrs group.

Configuring temporary space on distributed systems

Configure temporary directory space to enable IBM App Connect Enterprise Java components to operate
correctly.

About this task

IBM App Connect Enterprise contains Java components. Some of these components require temporary
directory space on the file system in order to extract class files from node packages (PAR files) and Java
packages (JAR files).
The extracted files might not be visible to interactive users on the system, however, they consume space
in the temporary directory.
The Java Runtime Environment also creates files in the temporary directory to support debug facilities.
To enable correct operation, allow at least 50 MB of space per integration server in the file system
temporary directory for IBM App Connect Enterprise components. This space is required in addition to
any space required for operation of user developed artifacts. Use of JavaCompute nodes, Java user-
defined nodes, or additional plug-in nodes implemented in Java might require further temporary directory
space.
On Linux, UNIX, and z/OS® computers, the TMPDIR directory is typically /tmp; on Windows computers, it
is c:\temp. If this directory is not large enough to hold the JAR files, the integration node does not start.
To change the location of the temporary directory, use one of the following methods:

Procedure
• Use the environment variable TMPDIR.
• Set the system property java.io.tmpdir.

74 IBM App Connect Enterprise 12.0: User Guide

 Checking the kernel configuration on Linux and AIX
Check the kernel configuration parameters on Linux and AIX for prerequisite and corequisite products.

About this task

IBM App Connect Enterprise has no specific requirements for kernel configuration parameters; however,
other products might require particular settings. If you do not tune your kernel parameters to suit the
products that you have installed, you might see unexpected results or a deterioration in performance.
Follow these steps to configure your kernel parameters:

Procedure
1. Check the documented values for the following products:
• IBM MQ (if it is installed)
• DB2 (if it is installed)
• Other software that you have installed to work with IBM App Connect Enterprise, including other
databases.
You can access the relevant information for IBM products online at IBM Documentation.
2. Take the highest value for each parameter and compare it to the corresponding value in your kernel
configuration.
3. If the current value is lower than the highest documented value, update the current setting by using
the appropriate tooling that is supplied by the operating system provider. If the current value is higher,
leave it unchanged.
4. If you have changed any kernel values, you might need to restart your system for these changes to
take effect. Check the documentation for your operating system for further information about these
parameters.

Installing IBM App Connect Enterprise software

You can install IBM App Connect Enterprise on a number of platforms.

About this task

To install IBM App Connect Enterprise, complete the following steps:

Procedure
1. Check the readme.html file for any updates to the installation instructions.
For more details, see “Finding the latest information” on page 1.
2. Check that you have enough memory and disk space; see IBM App Connect Enterprise system
requirements.
3. Depending on your operating system, complete the instructions to install IBM App Connect Enterprise:
•
See “Installing IBM App Connect Enterprise on Windows” on page 76.
•
See “Installing IBM App Connect Enterprise on Linux” on page 79.
•
See “Installing IBM App Connect Enterprise on AIX” on page 81.
4. Optional: To use IBM App Connect Enterprise Toolkit, in a supported language other than English; see
Installing language packs for the IBM App Connect Enterprise Toolkit.

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 75

 Installing IBM App Connect Enterprise on Windows
Install IBM App Connect Enterprise on Windows.

Before you begin

• Check the readme.html file for any updates to these installation instructions; see the product readme
web page.
• Check that you have enough memory and disk space; see IBM App Connect Enterprise system
requirements.
• Complete any prerequisite steps; see “Preparing the system” on page 71.

Installing the software

Procedure
To install IBM App Connect Enterprise, complete the following steps.
1. Extract the downloaded .zip file for the version of IBM App Connect Enterprise that you want to
install to unpack the installation files into a local directory:
For example, if you extract the file ACESetup12.0.2.0.zip into C:\temp, the following extracted
files appear in C:\Temp\ACESetup12.0.2.0
• ACESetup12.0.2.0.exe. This file is the installation executable file.
• ACEtk1.cab. This file contains the product files for the IBM App Connect Enterprise Toolkit
component.
• ACEae1.cab. This file contains the product files for the OpenAPI editor component.
• ACEws1.cab. This file contains the product files for the WebSphere Service Registry and Repository
nodes component.
• readmes. This folder contains the readme files for all of the supported national languages.
All of the extracted files are required to do a full installation of the product. If you want to package
the installation files into a scripted deployment of IBM App Connect Enterprise on your server
environment, you can omit the files for the components that you do not want. If you want to install
the OpenAPI editor component, then you must also install the IBM App Connect Enterprise Toolkit
component.
If you want to install by using the command-line, complete step 2. If you want to install by using the
Install wizard, complete step 3.
2. Optional: To install IBM App Connect Enterprise on Windows by using the command-line options, run
the following command with the options that you require:

ACESetup12.0.n.0.exe

For example, if you do not want to install the IBM App Connect Enterprise Toolkit component, run the
command with the following options:

ACESetup12.0.n.0.exe InstallToolkit=0

For more information about command-line options you can use, for example, to initiate an installation
in silent mode, see “Command-line options for installing IBM App Connect Enterprise on Windows” on
page 78.
3. Optional: To install IBM App Connect Enterprise on Windows by using the Install wizard, by
completing the following steps:
a) Required: In the directory where you unpacked the installation files, right -click on the file
ACESetup12.0.n.0Setup.exe to open the menu, and then select Run as administrator to

76 IBM App Connect Enterprise 12.0: User Guide

 open the Install wizard. Alternatively, in the command prompt, navigate to the directory where you
unpacked the installation files and run the following command to open the Install wizard:

ACESetup12.0.n.0.exe

The Install wizard opens in which you select the components that you want to install.
b) Click Options to display the components that you can install and the path for the install location.
c) Optional: By default, both the IBM App Connect Enterprise Toolkit and the IBM App Connect
Enterprise runtime component are installed. If you do not want to install the IBM App Connect
Enterprise Toolkit, deselect the Install IBM App Connect Enterprise Toolkit checkbox.
d) Optional: By default, the OpenAPI editor is installed. If you do not want to install the OpenAPI
editor, deselect the Install IBM App Connect Enterprise Open API editor checkbox. If you
want to install the OpenAPI editor component, then you must also install the IBM App Connect
Enterprise Toolkit component.
e) Optional: By default, the WebSphere Service Registry and Repository nodes are not installed. If you
want to install the WebSphere Service Registry and Repository nodes, select the Install IBM App
Connect Enterprise WebSphere Service Registry and Repository message flow nodes checkbox.
If you choose not to install the WebSphere Service Registry and Repository nodes, the
<install_dir>/server/wsrrcomponent directory is not created during the
installation. However, the WebSphere Service Registry and Repository nodes still appear
in the IBM App Connect Enterprise Toolkit.
f) Optional: By default IBM App Connect Enterprise is installed in C:\Program Files\IBM\ACE
\12.0.n.0. If you want to change the installation directory, type or navigate to the directory path
that you want to use.
If you specify your own directory path, be aware of the following restrictions:
• Specify a directory path to a new or empty directory. Do not install IBM App Connect Enterprise
12.0 over an existing deployment of IBM App Connect Enterprise. To upgrade the product, you
can uninstall the existing version of IBM App Connect Enterprise before you install the new
version of the product. Alternatively, you can install the new version alongside the existing version
and migrate your resources to the new version.
• The Windows operating system has a file system limit of 256 characters for the combination of
a directory path and file name. If the combination of path and resource name (for example, a
message flow) exceeds this length, you might have access problems. Choose a short name for
your directory path to avoid problems that are associated with this restriction.
g) Accept the license terms and conditions and then click Install to start the installation.
If the Microsoft.NET framework is not already installed on your computer, then the framework
is installed as part of the IBM App Connect Enterprise installation. The installation of the
Microsoft.NET framework might involve communicating with Microsoft servers over the internet.
Depending on the configuration of your firewall, you might need to accept a prompt to allow this
communication.

Results
The installation wizard proceeds to install the IBM App Connect Enterprise software. After some minutes,
the installation process finishes with the message "Installation successfully completed". You can then
close the installation wizard.

What to do next
If you install the IBM App Connect Enterprise Toolkit, you can verify your installation by starting the
toolkit by using either of the following methods:
• Use the Windows Start menu option for IBM App Connect Enterprise 12.0.n.0 > 12.0.n.0.
• From the IBM App Connect Enterprise Console, type ace toolkit.

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 77

 Command-line options for installing IBM App Connect Enterprise on Windows
You can use command-line options to customize the installation process.
You can use one or more of the following options with the ACESetup12.0.n.0.exe command:

Purpose Command-line option

Accept the license. This option is mandatory when LICENSE_ACCEPTED=true
you run the installation in silent or passive mode.
Run the installation in silent mode; the installation /quiet, /q, /silent, or /s
is completed in the background.
For example:
Note: You must run the command from an elevated
command prompt (a command prompt where you ACESetup12.0.n.0.exe /quiet
LICENSE_ACCEPTED=true
have administrative privileges), otherwise you are
prompted for an administration password.

Run the installation in passive mode; installation /passive

progress is displayed but no user interaction is
For example:
required.
Note: You must run the command from an elevated ACESetup12.0.n.0.exe /passive
LICENSE_ACCEPTED=true
command prompt (a command prompt where you
have administrative privileges), otherwise you are
prompted for an administration password.

Install IBM App Connect Enterprise to a directory of InstallFolder="install_location", where

your choice. install_location is the fully qualified path of the
directory where you want to install IBM App
Connect Enterprise.
For example:

ACESetup12.0.n.0.exe InstallFolder="C:
\ACEV12"

Save the installation log file in a custom location. By /log "log_location", where log_location
default, the installation log is saved in the system is the fully qualified path to the file where you
temporary directory. want to save the log information for the IBM App
Connect Enterprise installation.
For example:

ACESetup12.0.n.0.exe /log "C:\InstallLogs

\ace_v12.log"

Do not install the IBM App Connect Enterprise InstallToolkit=0

Toolkit.
For example:

ACESetup12.0.n.0.exe InstallToolkit=0

'Do not install the OpenAPI editor. ACESetup12.0.n.0.exe InstallAPICeditor=0

Install the WebSphere Service Registry and InstallWSSRnodes=1

Repository nodes.
For example:

ACESetup12.0.n.0.exe InstallWSRRnodes=1

78 IBM App Connect Enterprise 12.0: User Guide

Purpose Command-line option
Change the language that is used by the installation /lang localeID, where localeID is the locale
wizard. ID for the language that you want the installation
wizard to use. Table 10 on page 79 lists the
Note: The language of the IBM App Connect
options that you can use for the locale ID.
Enterprise installation wizard defaults to the
language set in Control Panel > Region and For example, to display the installation wizard in
Language > Format. English when your operating system locale is not
set to English, use the command:

ACESetup12.0.n.0 /lang 1033

Uninstall IBM App Connect Enterprise. /uninstall.

For example:

ACESetup12.0.n.0.exe /uninstall

List the most commonly used command-line /? or /help

options.
For example:

ACESetup12.0.n.0.exe /?

Table 10. Locale ID table

Locale ID Language code Language
1028 zh_TW Chinese (Traditional)
1031 de_DE German
1033 en_US English
1036 fr_FR French
1040 it_IT Italian
1041 ja_JP Japanese
1042 ko_KR Korean
1045 pl_PL Polish
1046 pt_BR Portuguese (Brazil)
1049 ru_RU Russian
1055 tr_TR Turkish
2052 zh_CN Chinese (Simplified)
3082 es_ES Spanish

Installing IBM App Connect Enterprise on Linux

You can install IBM App Connect Enterprise on Linux, either for use by a single user or for use by multiple
users.

Before you begin

• Check the readme.html file for any updates to these installation instructions; see the product readme
web page.

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 79

 • Check that you have enough memory and disk space; see IBM App Connect Enterprise system
requirements.
• Check that you completed any prerequisite steps; see “Preparing the system” on page 71.

About this task

As a user without administrative privileges, you can create a single-user installation of IBM App Connect
Enterprise in your home directory. This single-user installation is then accessible only by your user ID.
As a user with administrative privileges, you can create a shared installation of IBM App Connect
Enterprise. To authorize any users of the computer to access the shared installation of IBM App Connect
Enterprise, add the users to the mqbrkrs group by using the security facilities that are provided by your
operating system.

Installing the software

Procedure
To install IBM App Connect Enterprise, complete the following steps:
1. Log in to the system where you are installing IBM App Connect Enterprise.
• If you are deploying a single-user installation, log in with your personal user ID.
• If you are deploying a shared installation, either:
– Log in as root or as a super user who has write access to the /var directory, or
– Log in as a non-root user who is a member of mqbrkrs and has write access to the /var/mqsi
directory.
2. Unpack the installation image by completing the following steps:
a) Create or navigate to a directory where you have write access.
For example, $HOME for a single-user installation, or /opt/IBM for a shared installation.
b) Run the following command to unpack the installation image:
tar -xzvf ace-12.0.n.0.tar.gz
Note: On all Linux systems, except for Linux on Z, and Linux on POWER®, the installation includes
the IBM App Connect Enterprise Toolkit and the WebSphere Service Registry and Repository nodes.
If you do not want to install the IBM App Connect Enterprise Toolkit, you can run the following
command instead:
tar -xzvf ace-12.0.n.0.tar.gz --exclude ace-12.0.n.0/tools
If you do not want to install the WebSphere Service Registry and Repository nodes, you can run the
following command instead:
tar -xzvf ace-12.0.n.0.tar.gz --exclude ace-12.0.n.0/server/wsrrcomponent
If you do not want to install the IBM App Connect Enterprise Toolkit or the WebSphere Service
Registry and Repository nodes, you can run the following command instead:
tar -xzvf ace-12.0.n.0.tar.gz --exclude ace-12.0.n.0/server/wsrrcomponent
--exclude ace-12.0.n.0/tools
If you choose not to install the WebSphere Service Registry and Repository nodes, the
<install_dir>\server\wsrrcomponent directory is not created during the
installation. However, the WebSphere Service Registry and Repository nodes still appear
in the IBM App Connect Enterprise Toolkit.

80 IBM App Connect Enterprise 12.0: User Guide

3. Accept the IBM App Connect Enterprise license by completing the following steps:
a) Navigate to the installation directory.
For example, install_dir/ace-12.0.n.0 where install_dir is the directory where you
unpacked the installation image.
b) Type one of the following commands:
• For a single-user installation:
– ./ace accept license. If you use this command, you are prompted to accept the license.
– ./ace accept license silently. If you use this command, the license is accepted even
though the license dialog is not displayed.
The following directory is created: $HOME/aceconfig. This directory is the work path for IBM
App Connect Enterprise, and stores the IBM App Connect Enterprise configuration files.
• For a shared installation:
– ./ace make registry global accept license. If you use this command, you are
prompted to accept the license.
– ./ace make registry global accept license silently. If you use this command,
the license dialog is suppressed and the license is automatically accepted.
The following directory is created: /var/mqsi. This directory is the work path for IBM App
Connect Enterprise, and stores the IBM App Connect Enterprise configuration files.
4. Optional: If you installed a shared installation of IBM App Connect Enterprise, grant users access to
the installation by adding them to the mqbrkrs user group.
Note: On Linux, the user ID that installed IBM App Connect Enterprise is not automatically added to
the mqbrkrs group. If you want to use this user ID with IBM App Connect Enterprise, you must add the
user ID to the mqbrkrs group.

Installing IBM App Connect Enterprise on AIX

You can install IBM App Connect Enterprise on AIX, for use by a single user or multiple users.

Before you begin

• Check the readme.html file for any updates to these installation instructions; see the product readme
web page.
• Check that you have enough memory and disk space; see IBM App Connect Enterprise system
requirements.
• Check that you have completed any prerequisite steps; see “Preparing the system” on page 71.

About this task

As a user without administrative rights, you can create a single-user installation of IBM App Connect
Enterprise in your home directory. This single-user installation is then accessible only by your user ID.
As a user with administrative rights, you can create a shared installation of IBM App Connect Enterprise.
To authorize any users of the computer to access the shared installation of IBM App Connect Enterprise,
add the users to the mqbrkrs group by using the security facilities that are provided by your operating
system.

Installing the software

Procedure
To install IBM App Connect Enterprise, complete the following steps:

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 81

 1. Log in to the system where you are installing IBM App Connect Enterprise.
• If you are deploying a single-user installation, log in with your personal user ID.
• If you are deploying a shared installation, either:
– Log in as root or as a super user who has write access to the /var directory, or
– Log in as a non-root user who is a member of mqbrkrs and has write access to the /var/mqsi
directory.
2. Unpack the installation image by completing the following steps:
a) Create or navigate to a directory where you have write access.
For example, $HOME for a single-user installation, or /opt/IBM for a shared installation.
b) Run the following command to unpack the installation image:

zcat ace-12.0.n.0.tar.Z | tar -xvf -

3. Accept the IBM App Connect Enterprise license by completing the following steps:
a) Navigate to the installation directory.
For example, install_dir/ace-12.0.n.0 where install_dir is the directory where you
unpacked the installation image.
b) Type one of the following commands:
• For a single-user installation:
– ./ace accept license. If you use this command, you are prompted to accept the license.
– ./ace accept license silently. If you use this command, the license is accepted even
though the license dialog is not displayed.
The following directory is created: $HOME/iibconfig. This directory is the work path for IBM
App Connect Enterprise, and stores the IBM App Connect Enterprise configuration files.
Note: After you accept the license, IBM App Connect Enterprise does not function correctly if you
copy the program code to another location. To relocate the IBM App Connect Enterprise program
code, choose one of the following options:
– To refer to IBM App Connect Enterprise as if it is installed in another location, leave the IBM
App Connect Enterprise program where it is currently installed and create a symbolic link to the
program. See your operating system instructions for information about creating symbolic links.
– To move IBM App Connect Enterprise to another physical location, uninstall the IBM App
Connect Enterprise program and reinstall the program in the required location.
• For a shared installation:
– ./ace make registry global accept license. If you use this command, you are
prompted to accept the license.
– ./ace make registry global accept license silently. If you use this command,
the license is accepted even though the license dialog is not displayed.
The following directory is created: /var/mqsi. This directory is the work path for IBM App
Connect Enterprise, and stores the IBM App Connect Enterprise configuration files.
4. Optional: If you installed a shared installation of IBM App Connect Enterprise, grant users access to
the installation by adding them to the mqbrkrs user group.
On AIX, the user ID that installed IBM App Connect Enterprise is not automatically added to the
mqbrkrs group. You must add this user ID to the mqbrkrs group if you want to use the user ID with IBM
App Connect Enterprise.

82 IBM App Connect Enterprise 12.0: User Guide

Setting up a command environment
Runtime components and commands that administer runtime components must be run from a command
environment. You must initialize this environment by running the mqsiprofile command.

About this task

The mqsiprofile command places the Version 12.0 commands and libraries at the front of your search
path, and can override any combination of PATH, CLASSPATH, or library PATH.
ODBC settings on Linux systems are found in a text file that is defined by the ODBCINI environment
variable. If you are using Linux, set ODBCINI to point to a copy of the sample file install_dir/
server/ODBC/unixodbc/odbc.ini, where install_dir is the IBM App Connect Enterprise installation
directory.
On Linux, if you want to use IBM MQ features, you must set the IBM MQ environment where you want the
integration server to run; for more information, see “Setting the IBM MQ environment on Linux and AIX”
on page 84.
Ensure that you use this environment each time you run an administrative command, or start an
integration server.
The mqsiprofile command also runs extra scripts that are copied to the common\profiles directory
(on Windows) or the common/profiles directory (on Linux systems). These scripts can be used to
initialize the environment for runtime components and other resources, such as databases.
The following steps explain how to initialize your command environment, either by explicitly running the
mqsiprofile command (on Linux) or by starting the command console (on Windows).

Procedure
• On Windows, open a command console by searching for IBM App Connect Enterprise Console. If you
have multiple installations of IBM App Connect Enterprise, make sure that you are running the IBM
App Connect Enterprise Console from the build of the IBM App Connect Enterprise installation that you
want to administer.
• On Linux systems, locate and run the mqsiprofile.sh script in the directory in which you installed
the appropriate product.

. install_dir/server/bin/mqsiprofile

You must include the period and space for this command to work correctly. If you want to run this
command at the start of every session, add it to your login profile.
If you use the zsh shell, running the mqsiprofile might cause the terminal session to exit.
To resolve this issue, run the unsetopt function_argzero command before you run the
mqsiprofile command.

What to do next
From the command line in the initialized environment, you can run commands to administer IBM App
Connect Enterprise. For example, you can configure and start an integration server, as described in
“Configuring an integration server by modifying the server.conf.yaml file” on page 172 and “Starting an
integration server” on page 250.

Running database setup scripts before starting an integration node

Configure an integration server to access databases from deployed message flows by customizing the
command environment. This process is relevant only when you are starting an integration node.
When you install a database product, the relevant settings might be made to the system environment
(typical for Windows systems). However, some database managers provide a profile to perform this setup,

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 83

 or provide details of actions that you must take. Always check the database product documentation for
environment setup details; the information that is provided here is for general guidance only.
If a profile is provided for the database that you are using, complete the following process:
If you can update the profile to provide permanent values for the details that are required (for example,
the database server name or the installation directory), complete Step “1” on page 84. You must also
complete either Step “2” on page 84 or Step “3” on page 84. If you cannot update the profile to
provide permanent values, then you must complete Step “4” on page 84
1. Complete the changes to the database profile.
2. If your platform is Windows copy the profile file to the appropriate directory:
• For an HA integration node, use shared_work_path\config\node_name\profiles.
• If the integration node was created with a specified work path, which has a subdirectory workPath
\config\node_name\profiles, then use that profiles directory.
• In the default case, use %MQSI_REGISTRY%\config\node_name\profiles.
3. If your platform is Linux or UNIX copy the profile file to the appropriate directory:
• For an HA integration node, use shared_work_path/common/profiles.
• If the integration node was created with a specified work path, under which has a subdirectory
work_path/config/node_name/profiles, then use that profiles directory.
• In the default case, use ${MQSI_REGISTRY}/config/node_name/profiles.
4. If you cannot update the profile permanently, but need to make changes repeatedly, you must edit it in
the appropriate directory as specified in Step “2” on page 84 or Step “3” on page 84. You must
edit the profile each time before you start the integration node.
Note:
The directory, workPath is the machine-wide IBM App Connect Enterprise working directory. To verify
the machine-wide IBM App Connect Enterprise working directory, enter the following command in a
command console:

echo %MQSI_WORKPATH%

The directory, shared_work_path is the working directory for a multi-instance integration node.
For more information about the parameters for the working directory of an integration node, see
command, and command - systems.

Setting the IBM MQ environment on Linux and AIX

On Linux and AIX, configure an integration server to use the specified IBM MQ environment.
In addition to the scripts that you must run to create your default system queues (as described in
“Creating the default system queues on an IBM MQ queue manager” on page 99), on Linux and
AIX systems, you must configure the IBM MQ environment where you want the integration server to
run, before you start it. If you do not set the environment, your integration server might not run in the
expected location.
Set the environment by using the IBM MQ setmqenv command; for more information see the setmqenv
command in the IBM MQ product documentation. For example, if you want the integration server to use
the IBM MQ installation path /opt/mqm:

. /opt/mqm/setmqenv -s -x 64

Because the setmqenv command is not persistent, you can create an IBM App Connect Enterprise
common profile to run this command in either of the following ways:
• Run setmqenv when mqsiprofile is run.
• Run setmqenv when the integration server is started.

84 IBM App Connect Enterprise 12.0: User Guide

Configuring your IBM App Connect Enterprise installation to conform to your
license
You must ensure that your installation conforms to the terms of your license.

Before you begin

For a full description of the operation mode, see “Operation modes” on page 3.

Procedure
• Upgrading from IBM App Connect Enterprise for Developers (Developer Edition)
If you installed the Developer Edition, and you have now purchased a fully supported version of the
product such as the Advanced Edition, you can keep the components and all the associated resources
that you have already created and configured. Before you install the purchased product, uninstall the
Developer Edition. You can retain your existing integration servers and workspace, and any Developer
mode resources remain in Developer mode by default. You can leave them in Developer mode, or you
can use the mqsimode command to change the operation mode to reflect the license that you have
purchased.
To change the operation mode, complete the following steps.
– If you intend to keep the integration servers that you created with the Developer Edition for further
development and unit test by your developers, change the operation mode to advanced, as
described in “Changing the operation mode” on page 86.
Check the license agreement file to ensure that your configuration conforms to any restrictions
for development and unit test. Development and unit test conditions are described in “License
requirements” on page 5.
– If you intend to use the integration nodes that you created with Developer Edition for production
purposes, change the operation mode to conform to the license that you have purchased:
- If you have purchased Standard Edition, change the operation mode to standard.
- If you have purchased the Nonproduction license, change the operation mode to
nonproduction.
- If you have purchased the full IBM App Connect Enterprise license, change the operation mode to
advanced.
If you reinstall IBM App Connect Enterprise with the new package for your purchased product, the
default operation mode is advanced. If you have purchased a full IBM App Connect Enterprise
license, you can leave the operation mode as advanced, otherwise you must change the mode of your
integration nodes to conform to the license that you have purchased (for example, standard mode).
• Standard Edition
If you have purchased IBM App Connect Enterprise Standard Edition, and installed components from
the full runtime package, read the following information.
– All integration servers that you have created have an operation mode set to advanced, which is the
default setting for this installation. You can keep them for further development and unit test, subject
to any restrictions that apply for unit test environments, as indicated in your license. Development
and unit test conditions are described in “License requirements” on page 5.
– If you intend to use the integration servers for production purposes, follow the instructions in
“Changing the operation mode” on page 86, to conform to the license that you have purchased.
- If you have purchased Standard Edition, change the operation mode to standard.

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 85

 • Full (unrestricted) license for IBM App Connect Enterprise
If you have purchased a full (unrestricted) license and installed components from the full runtime
package, all components that you create have an operation mode set to the default value of
advanced, which is the correct setting for your license.
You can continue to work with all the components and associated resources that you have already
created. For example, after you have completed verification, you might keep the resources that you
have created for further development and unit test (subject to any restrictions that apply for unit test
environments, as indicated in your license). Development and unit test conditions are described in
“License requirements” on page 5.

Changing the operation mode

Change the operation mode in which your integration servers are working by using the mqsimode
command.

About this task

You must change your configuration to ensure that your integration servers are running in the operation
mode for which you have purchased a license. You can change the mode to standard, nonproduction,
nonproductionfree, or advanced.

Procedure
1. Run the mqsimode command with the -o parameter to change the operation mode, or without the -o
parameter to view the current setting; for more information, see command.
2. Check for error messages. If you attempt to reconfigure your installation to a mode that is not
sufficient for the deployed resources, the mqsimode command issues a warning indicating that
changing the mode is not allowed. Resolve any violations, if required.
3. (Optional) Run the mqsimode command again to confirm that there are no violations.

Moving from Developer Edition

If you want to move from Developer Edition to an alternative edition, you must uninstall Developer Edition
before installing the new edition.

Before you begin

Contact your IBM representative to upgrade your license.

Procedure
To move from Developer Edition to an alternative edition, complete the following steps.
1. Stop all running integration servers, as described in “Starting an integration server” on page 250.
2. Uninstall the Developer Edition.
3. Install your new licensed edition.
4. Restart your integration servers, which will now run in an unrestricted mode.

86 IBM App Connect Enterprise 12.0: User Guide

 Checking the operation mode
Run the mqsimode command to report the operation mode that is being used by your IBM App Connect
Enterprise installation.

About this task

Use the mqsimode command on its own, without the -o parameter, to receive a report about the
operation mode that is being used by your installation of IBM App Connect Enterprise, and a report about
any mode violations. For example:

mqsimode

Configuring the IBM App Connect Enterprise web user interface

You can use the node.conf.yaml and server.conf.yaml configuration files to configure the port that
is used to connect to the web user interface, and to secure the connection.

Before you begin

Configure an integration node or server, by following the instructions described in “Configuring an
integration node by modifying the node.conf.yaml file” on page 118 or “Configuring an integration server
by modifying the server.conf.yaml file” on page 172.

About this task

The IBM App Connect Enterprise web user interface enables you to access integration node or integration
server resources by using a web browser, and it provides integration administrators with a method
of administering those resources. For more information about the web user interface, see web user
interface. To learn some basics about administering IBM App Connect Enterprise with the web user
interface, see the tutorial "Getting started - Exploring the Web UI" in the IBM App Connect Enterprise
Toolkit.

Procedure
1. Open the node.conf.yaml or server.conf.yaml configuration file for your integration node or
server, by using a YAML editor.
If you do not have access to a YAML editor, you can edit the file by using a plain text editor. However,
you must ensure that you do not include any tab characters, which are invalid characters in YAML and
would cause your configuration to fail. If you are using a plain text editor, ensure that you use a YAML
validation tool to validate the content of your file.
Set the RestAdminListener properties, which control the settings for the web user interface:
2. Set the port property to the port to be used by the web user interface and the IBM App Connect
Enterprise Toolkit. By default, this port is set to 4414.

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 87

 3. Optional: If you want to secure the connection, set the following properties:
a) Set host: 'hostname'
Specify the hostname where the integration node or integration server is running.
b) If you want to use basic authentication for users who log in to the web user interface, uncomment
the following property:
basicAuth: true
Specify whether clients require a web username and password (true or false).
You also need to create at least one username and password, by running the mqsiwebuseradmin
command as described in the later step section "Additional steps for security configuration".
c) If you want to use SSL or TLS to secure the connection:
Set the following properties:
sslCertificate
Specify the path to a certificate store for use in securing the REST Administration port, which is
used by the Web User Interface and IBM App Connect Enterprise Toolkit, in the form /path/
to/serverPKCS.p12.
If you are using a .pem certificate, the sslCertificate is the full path to the server
certificate key.
If you are using .p12 or .pfx certificate, the sslCertificate is the full path to the server
certificate store file.
The certificate store cannot be in JKS format, and hence must be a separate certificate store
from the certificate store that is used by the integration server for things such as HTTPS
message flow nodes.
sslPassword
Specify the server certificate password alias, in the form adminRestApi::sslpwd.
If you are using a .pem certificate, the sslPassword is the full path to the server private key,
which must be a standard private key and not an encrypted one.
If you are using .p12 or .pfx certificate, the sslPassword is the passphrase or alias to the
passphrase of the certificate store.
You also need to set the password to be used for your server certificate, by running the
mqsisetdbparms command as described in the later step section "Additional steps for security
configuration".
d) If you want to use SSL client certificates (mutual authentication):
requireClientCert
Specify whether a certificate is to be requested from the client (true or false).
caPath
Specify the file path that contains certificate authority certificates; all files in this path are read.
4. If you want to view message flow statistics in the web user interface, you must also enable the
reporting of message flow statistics and accounting data, as described in “Configuring the collection
of message flow statistics by using a .yaml configuration file” on page 2729. The web user interface
consumes message flow statistics and accounting data in JSON format, which means that you must
include json as one of the values in the outputFormat property in the .conf.yaml configuration
file.
5. If you want to view resource statistics in the web user interface, you must enable the reporting of
these statistics as described in “Managing resource statistics collection” on page 2741.
6. Save the .yaml file. The properties that you set in the .yaml file take effect when the integration node
or server is started. If you modify these properties again, you must also restart the integration node or
server.
7. Restart the integration node or server for the changes to take effect.
Additional steps for security configuration:

88 IBM App Connect Enterprise 12.0: User Guide

8. If you set basicAuth: true, create one or more usernames and passwords that users must specify
when they start the web user interface.
In the IBM App Connect Enterprise command console, create a username and password by issuing the
mqsiwebuseradmin command. For example:

mqsiwebuseradmin -w c:\workdir\ACEServ1 -u admin -a password -c

For more information about configuring basic authentication, see “Configuring HTTP basic
authentication for an integration node or server” on page 2548.
9. If you set sslCertificate and sslPassword to use SSL or TLS to secure the connection.
In the IBM App Connect Enterprise command console, use the mqsisetdbparms command to set the
password to be used for your server certificate. For example:

mqsisetdbparms -w c:\workdir\ACEServ1 -n adminRestApi::sslpwd -u dummy -p password

For more information about configuring use of SSL or TLS to secure the connection, see “Configuring
SSL or TLS for an integration node or server” on page 2548.

Results
You can now access the web user interface by opening a browser and specifying the host and port that
you configured in the .yaml configuration file. For more information, see “Accessing the web user
interface” on page 89.

Accessing the web user interface

You can use the IBM App Connect Enterprise web user interface to access integration node and
integration server resources through a web browser.

Before you begin

Configure the web user interface, by completing the steps in “Configuring the IBM App Connect Enterprise
web user interface” on page 87.

About this task

When the web user interface has been configured (by modifying the node.conf.yaml or
server.conf.yaml configuration file), you can access it by completing the following steps:

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 89

 Procedure
1. Start the web user interface, by using one of the following methods:
• From the IBM App Connect Enterprise Toolkit: In the toolkit, right-click the integration node or
server and select Start web user interface from the menu.
• From a web browser: Enter the URL for the web user interface into a web browser, in the following
form:
protocol://hostname:port
where:
– protocol is either http or https
– hostname is the host that you specified in the host property in the .yaml configuration file for the
integration node or server (for example, localhost or 127.0.0.1)
– port identifies the port that is to be used for the web user interface and the toolkit, and must
match the value that you set for the port property in the .yaml configuration file; by default this
is set to 4414.
For example:

https://localhost:4414

or

https://127.0.0.1:4414

If the integration server is configured to require authentication for administrative tasks (that is, if the
basicAuth property in the .yaml configuration file is set to true), you are prompted to enter your
user ID and password.
2. If prompted, enter your user ID and password and log in to the system.
If the connection to the web user interface is not secured, you can access all data and resources
without logging in. Users have permissions granted to them according to their role, so administrators
and web users can have different access to resources based on their role. For more information about
roles, see “Role-based security” on page 2503. For information about creating user accounts, see
“Managing web user accounts” on page 2510.

Results
A web browser window opens, in which you can view and administer your resources.

Applying service to IBM App Connect Enterprise

Install IBM App Connect Enterprise fix packs to get the latest service updates and fixes.

About this task

Service updates and other fixes are delivered occasionally in the form of fix packs. You can find
information about available fix packs on the IBM App Connect Enterprise support web page.
IBM App Connect Enterprise fix packs are complete App Connect Enterprise installations and are installed
in the same way as the initial product release. For more information, see “Installing IBM App Connect
Enterprise software” on page 75. You can install a fix pack on the same computer as a previous release,
or on a different computer. For more information about installing more than one fix pack (at the same
or different levels) on a single computer, see “Coexistence of IBM App Connect Enterprise 12.0 with
previous versions” on page 70.
When you have installed a fix pack, see New function added in and subsequent modification and fix packs
for information about the function that is provided in that fix pack and in any previous fix packs.

90 IBM App Connect Enterprise 12.0: User Guide

IBM App Connect Enterprise supports interoperability between different fix packs of the same version.
However, errors might occur if you create (or edit) an artifact or enable a new feature, and then use the
artifact with a component that is using an earlier fix pack. For example, the following situations might
generate errors:
• Editing source artifacts in the IBM App Connect Enterprise Toolkit that were created on an IBM App
Connect Enterprise Toolkit that is using a later fix pack.
• Building BAR files from artifacts that were created on an IBM App Connect Enterprise Toolkit that is
using a later fix pack than the build system.
• Deploying BAR files that were built by using a component that is using a later fix pack than the target
integration server.
• Connecting a REST administration application (including the IBM App Connect Enterprise Toolkit and
commands) to a remote integration server that is using a later fix pack.
It is good practice to ensure that downstream components (such as integration servers and build
systems) are using the same or later fix pack as upstream components (such as the IBM App Connect
Enterprise Toolkit). An alternative option is to ensure that you install the earliest common fix pack on the
build systems so that you are warned about any incompatible options as early as possible.
If you installed the fix pack on the same computer as an existing installation of IBM App Connect
Enterprise 12.0, complete the following steps to convert your integration nodes to run with the new code.
These methods are valid only for switching an integration node between different fix pack levels that are
associated with the same product code version. You must use the mqsiextractcomponents command
to migrate an integration node to a different version and release.

Procedure
•
On Windows, complete one of the following steps:
– Start the IBM App Connect Enterprise Console for the new fix pack level, and then start the
integration node by using the mqsistart command.
– Start the IBM App Connect Enterprise Toolkit for the new fix pack level. Any local integration nodes
that are stopped and configured to start automatically with the IBM App Connect Enterprise Toolkit
use the product code that is associated with the version of the IBM App Connect Enterprise Toolkit.
– Start the integration node by using a script that first runs the mqsiprofile for the new fix pack
level.
– If your integration node is configured to start as an IBM MQ service, you must manually update
the IBM MQ Service definition on the queue manager that is associated with the integration node.
This update enables the integration node to use the new code. For more information, see “Applying
service to an integration node that starts under the control of an IBM MQ queue manager” on page
92.
•
On Linux:
– Start the IBM App Connect Enterprise Toolkit for the new fix pack level. Any local integration nodes
that are stopped and configured to start automatically with the IBM App Connect Enterprise Toolkit
use the product code that is associated with the version of the IBM App Connect Enterprise Toolkit.
– Run the mqsiprofile command from the new fix pack level, and start your integration node by
using the mqsistart command.
– If your integration node is configured to start as an IBM MQ service, you must manually update
the IBM MQ Service definition on the queue manager that is associated with the integration node.
This update enables the integration node to use the new code. For more information, see “Applying
service to an integration node that starts under the control of an IBM MQ queue manager” on page
92.

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 91

 •
On AIX :
– Run the mqsiprofile command from the new fix pack level, and start your integration node by
using the mqsistart command.
– If your integration node is configured to start as an IBM MQ service, you must manually update
the IBM MQ Service definition on the queue manager that is associated with the integration node.
This update enables the integration node to use the new code. For more information, see “Applying
service to an integration node that starts under the control of an IBM MQ queue manager” on page
92.

What to do next
You can use any Version 11.0 fix pack level of the IBM App Connect Enterprise Toolkit to deploy
integration solutions to an integration server that runs any Version 11.0 fix pack level.

Applying service to an integration node that starts under the control of an

IBM MQ queue manager
If an integration node starts under the control of an IBM MQ queue manager, you must manually update
the WebSphere MQ Service definition on the queue manager that is associated with the integration node.
This update enables the integration node to use the new code.

Procedure
To update the IBM MQ Service definition on the queue manager, complete the following steps:
1. At a command line, type runmqsc qmgr where qmgr is the name of the queue manager that is
associated with the integration node.
2. To display the current settings for the integration node type display service('serviceName'),
where serviceName is the name of your IBM MQ service.
The output details the current settings, for example, when your integration node is running the IBM
App Connect Enterprise Version 11.0 code, you might see the following output:

AMQ8629: Display service information details.

SERVICE(MQSI_integrationNodeName) CONTROL(QMGR) SERVTYPE(COMMAND)
STARTCMD(C:\PROGRA~1\IBM\ACE\1100~1.0\server\bin\runMQService.bat)
STARTARG(C:\PROGRA~1\IBM\ACE\1100~1.0\server\bin integrationNodeName)
STOPCMD(C:\PROGRA~1\IBM\ACE\1100~1.0\server\bin\endMQService.bat)
STOPARG(C:\PROGRA~1\IBM\ACE\1100~1.0\server\bin integrationNodeName)
STDOUT(C:\PROGRA~3\IBM\MQSI\common\log\integrationNodeName.mqservice.log)
STDERR(C:\PROGRA~3\IBM\MQSI\common\log\integrationNodeName.mqservice.log)
DESCR( ) ALTDATE(2019-12-19) ALTTIME(11.07.52)

3. Provide new fully qualified values for the following parameters: STARTCMD, STARTARG, STOPCMD, and
STOPARG, but preserve the existing command names.
For example, you might type the following command (on a single line) at the runmsc command line to
change the integration node to use the IBM App Connect Enterprise Version 11.0.0.n code:
Note: If you are on Windows, you must use short names .

alter service('MQSI_integrationNodeName')
startcmd('C:\PROGRA~1\IBM\ACE\1100~1.n\server\bin\runMQService.bat')
startarg('C:\PROGRA~1\IBM\ACE\1100~1.n\server\bin integrationNodeName')
stopcmd('C:\PROGRA~1\IBM\ACE\1100~1.n\server\bin\endMQService.bat')
stoparg('C:\PROGRA~1\IBM\ACE\1100~1.n\server\bin integrationNodeName')

where C:\PROGRA~1\IBM\ACE\1100~1.1 is the short name for C:\Program Files\IBM\ACE

\11.0.0.1
If the IBM MQ service definition is changed, the message AMQ8624: IBM MQ service changed. is
displayed.

92 IBM App Connect Enterprise 12.0: User Guide

Uninstalling IBM App Connect Enterprise
Remove IBM App Connect Enterprise, IBM App Connect Enterprise service, or other IBM App Connect
Enterprise features from your computer.

Procedure
1. Check that your user ID has the correct permissions to uninstall IBM App Connect Enterprise or IBM
App Connect Enterprise features.
The requirements are defined in “Security requirements” on page 72.
2. Follow the instructions that are provided in the appropriate topic:
• “Uninstalling IBM App Connect Enterprise on Windows” on page 93
• “Uninstalling IBM App Connect Enterprise on Linux and UNIX systems” on page 94

What to do next
You might also want to uninstall complementary products. See the documentation that is provided by
those products to complete this task.
• IBM DB2: See the DB2 product documentation.
• IBM License Metric Tool: See the IBM License Metric Tool website.

Uninstalling IBM App Connect Enterprise on Windows

You can uninstall IBM App Connect Enterprise on Windows by using the Windows Control Panel, or by
using silent mode.

Before you begin

Delete any integration servers that are not required by removing the contents of their work directories.

Procedure
Uninstall IBM App Connect Enterprise on Windows by completing the following steps.
1. Log on to the computer on which IBM App Connect Enterprise is installed.
2. Uninstall IBM App Connect Enterprise by using one of the following methods:
• Windows Control Panel: Select Control Panel > Programs > Programs and Features, select the IBM
App Connect Enterprise deployment that you want to uninstall, and click Uninstall.
• Silent mode: Navigate to the directory where the installation file is located, and type the following
command from an elevated command prompt (a command prompt where you have administrative
privileges):

ACESetup12.0.n.0.exe /q /uninstall

Results
You uninstalled IBM App Connect Enterprise.
Note: The following entities are created after the installation of IBM App Connect Enterprise and so they
are not removed by the uninstallation wizard. You can manually remove the entities if you do not want to
keep them.
• The IBM App Connect Enterprise configuration information in the work path directory; by default the
work path directory is C:\ProgramData\IBM\MQSI.
• The IBM App Connect Enterprise Toolkit workspace; by default the workspace is C:\Users
\user_name\IBM\ACET12\workspace.

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 93

 • The IBM App Connect Enterprise Toolkit configuration folder; by default the configuration folder is C:
\Users\user_name\AppData\Local\IBM\ACET12-config\12.0.n.0.
• The Windows services that are associated with each local integration node that is defined on your
computer (if you did not delete the integration nodes before you uninstalled IBM App Connect
Enterprise). For example, IBM Integration Bus Component TESTNODE_user_name.

Uninstalling IBM App Connect Enterprise on Linux and UNIX systems

You can uninstall IBM App Connect Enterprise on Linux and UNIX systems by using the same user ID that
you used to install the product.

Before you begin

Delete any integration servers that are not required, by removing the contents of their work directories.

Procedure
1. Log on with the user ID that you used to install IBM App Connect Enterprise.
2. Delete the IBM App Connect Enterprise entities that you do not want to keep:
• The IBM App Connect Enterprise installation directory. For example, install_dir/
ace-12.0.n.0.
• (Linux only) The IBM App Connect Enterprise Toolkit workspace directory. For example, $HOME/
IBM/ACET12/workspace. Do not delete the workspace if you want to keep any development
resources that you created, such as applications or libraries. You can use existing applications and
libraries with another installation of IBM App Connect Enterprise.
• The IBM App Connect Enterprise work path directory. For example, $HOME/iibconfig for a single-
user deployment or /var/mqsi for a shared deployment. Do not delete the work path directory
if you want to keep any integration nodes and integration servers that you created. You can use
existing integration nodes and integration servers with another installation of IBM App Connect
Enterprise.

Results
You uninstalled IBM App Connect Enterprise.

Uninstalling language packs from the IBM App Connect Enterprise Toolkit
You can remove language packs from the IBM App Connect Enterprise Toolkit.

About this task

If you have installed one or more language packs for the IBM App Connect Enterprise Toolkit, you can
remove any of these language packs by using one of the following methods:
• “Uninstalling language packs by using the IBM App Connect Enterprise Toolkit” on page 94
• “Uninstalling language packs by using the command line” on page 95

Uninstalling language packs by using the IBM App Connect Enterprise Toolkit

Procedure
1. Start the IBM App Connect Enterprise Toolkit.
2. From the menu, click Help > About IBM App Connect Enterprise Toolkit.
The About IBM App Connect Enterprise Toolkit dialog is displayed.
3. Click Installation Details.
The IBM App Connect Enterprise Toolkit Installation Details dialog is displayed and all the language
packs that are installed are listed.

94 IBM App Connect Enterprise 12.0: User Guide

4. Select the language packs that you want to remove, click Uninstall, and then click Finish.
The selected language packs are uninstalled and you are prompted to restart the IBM App Connect
Enterprise Toolkit.
5. Click Yes to restart the IBM App Connect Enterprise Toolkit.
If your operating system locale is configured for one of the languages that is supported by the
language packs you uninstalled, the IBM App Connect Enterprise Toolkit user interface is now
displayed in English.

Results
You have uninstalled one or more language packs from the IBM App Connect Enterprise Toolkit.

Uninstalling language packs by using the command line

Procedure
At the command line, type the following command on a single line:
• On Windows:

InstallPath\common\jdk\jre\bin\java
-jar InstallPath\tools\plugins\org.eclipse.equinox.launcher_1.3.0.v20130327-1446.jar
-launcher InstallPath\tools\eclipse
-application org.eclipse.equinox.p2.director
-uninstallIU LanguagePack

• On Linux:

InstallPath/common/jdk/jre/bin/java
-jar InstallPath/tools/plugins/org.eclipse.equinox.launcher_1.3.0.v20130327-1446.jar
-launcher InstallPath/tools/eclipse
-application org.eclipse.equinox.p2.director
-uninstallIU LanguagePack

where:
InstallPath
Specifies the directory where IBM App Connect Enterprise is installed.
LanguagePack
Specifies the language pack or language packs that you want to uninstall:
• To uninstall Language Pack 1 only, type com.ibm.etools.ace.toolkit.nl1.feature.group
• To uninstall Language Pack 2 only, type com.ibm.etools.ace.toolkit.nl2.feature.group
• To uninstall Language Pack 2a only, type
com.ibm.etools.ace.toolkit.nl2a.feature.group
• To uninstall more than one language pack, separate the entries with a comma.
For example, to uninstall Language Pack 1 and Language Pack 2 on Windows, where IBM App Connect
Enterprise is installed in the default location, type the following command on a single line:

"C:\Program Files\IBM\ACE\12.0.n.0\common\jdk\jre\bin\java"
-jar "C:\Program Files\IBM\ACE\12.0.n.0\tools\plugins
\org.eclipse.equinox.launcher_1.3.0.v20120522-1813.jar"
-launcher "C:\Program Files\IBM\ACE\12.0.n.0\tools\eclipse"
-application org.eclipse.equinox.p2.director
-uninstallIU
com.ibm.etools.ace.toolkit.nl1.feature.group,com.ibm.etools.ace.toolkit.nl2.feature.group

A message is displayed listing the language packs that are being uninstalled. When the uninstallation is
complete, a message is displayed that details how long the uninstallation took. For example:
Uninstalling com.ibm.etools.ace.toolkit.nl1.feature.group 11.0.0.v20180911-1900.
Uninstalling com.ibm.etools.ace.toolkit.nl2.feature.group 11.0.0.v20180911-1900.
Operation completed in 53088 ms.

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 95

 Results
You have uninstalled one or more language packs by using the command line.

Installing and uninstalling complementary products

IBM App Connect Enterprise works with several other products to provide complementary services.

About this task

If you want to use these optional services in your IBM App Connect Enterprise environment, refer to the
following installation information:

Installing IBM MQ
When you purchase a license for IBM App Connect Enterprise, your license entitles you to install IBM MQ
for use by App Connect Enterprise, within the terms of the license.

About this task

IBM MQ is fully supported by IBM App Connect Enterprise, and a subset of IBM App Connect Enterprise
capabilities require access to IBM MQ components.
• Some capabilities require IBM MQ to be part of the IBM App Connect Enterprise infrastructure, and you
must associate a queue manager with the integration server.
• Some capabilities do not require IBM MQ to be part of the IBM App Connect Enterprise infrastructure,
and you do not always need to associate a queue manager with the integration server.
• Some capabilities require access to IBM MQ, either locally or on a remote server.
Capabilities that require IBM MQ to be part of the IBM App Connect Enterprise infrastructure
For these capabilities, you must install an IBM MQ server on the same machine as the integration server
that is to use the capabilities, and you must associate a queue manager with the integration server or
integration node by setting the defaultQueueManager configuration property. For more information
about setting the configuration property, see either “Configuring an integration server by modifying the
server.conf.yaml file” on page 172 or “Configuring an integration node by modifying the node.conf.yaml
file” on page 118.
For some capabilities, you must also complete additional configuration actions indicated in the
"Additional configuration notes" column.

Capability Detail Additional configuration notes

Managed file You have any of the following nodes in your
support message flows:
• node
• node
• node
• node

High You have multi-instance integration nodes.

availability
High You are using the HTTP proxy servlet with You must create the set of IBM App
availability your integration node. Connect Enterprise queues on your queue
manager; see “Creating the default system
queues on an IBM MQ queue manager” on
page 99.

96 IBM App Connect Enterprise 12.0: User Guide

Capability Detail Additional configuration notes
Load You are using an integration node listener You must create the set of IBM App
balancing (instead of embedded listeners) with your Connect Enterprise queues on your queue
integration node. manager; see “Creating the default system
queues on an IBM MQ queue manager” on
page 99.
Global You are using globally-coordinated (XA)
coordination transactions.
of
transactions
(XA)

Capabilities that do not require IBM MQ to be part of the infrastructure for your IBM App Connect
Enterprise deployment
For these capabilities, you must install either an IBM MQ client or an IBM MQ server on the same
machine as the integration server or integration node that is to use the capabilities, but you do not need
to associate a queue manager with the integration server or integration node unless specified in the
"Additional configuration notes" column:

Capability Detail Additional configuration notes

Java You have one of the following nodes in your
connectivity message flows:
and JDBC
• node
• node
• node

Capabilities that require access to IBM MQ, either locally or on a remote server
For these capabilities, you must install an IBM MQ client or server either on the same machine as the
integration server or on another machine that can be accessed through a client connection:

Capability Detail Additional configuration notes

IBM MQ You have any of the following nodes in your You need to specify a queue manager on
connectivity message flows: the integration server or integration node
only if you want to use the queue manager
• node
by default for your MQ connection. For
• node more information, see “Configuring a local
• node connection to IBM MQ” on page 744 and
“Using a remote default queue manager”
• node
on page 750.
Advanced You have any of the following nodes in your You must create the set of IBM App
data message flows: Connect Enterprise queues on your queue
processing manager, as described in “Creating the
• node
default system queues on an IBM MQ
• node queue manager” on page 99.
• node You must configure the default
• node queue manager by setting either
• node the defaultQueueManager or
remoteDefaultQueueManager property.
• node For more information, see “Processing
• node events” on page 1819.

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 97

 Capability Detail Additional configuration notes
• node An integration server that supports this
capability must not share a queue manager
with another integration server unless
a unique queue prefix is set. You set
a unique queue prefix either by using
a policy or, if a remote default queue
manager is being used, by setting the
replacementQueuePrefix property.
For more information, see “Configuring an
integration server to use a remote default
queue manager” on page 751.
For TimeoutNotification nodes using
Controlled mode on a managed
integration server, a local default
queue manager is required. For
TimeoutNotification nodes using
Controlled mode on an independent
integration server, either a local
default queue manager or a remote
default queue manager is required.
For TimeoutNotification nodes using
Automatic mode, no queue manager is
required.

Publish and You are using publish and subscribe By default, events use the queue manager
subscribe capabilities to emit events or accounting that is associated with the integration
and statistics data over IBM MQ and MQTT. server or integration node. However, you
can use a policy to configure events to use
For more information, see “Configuring the
a different queue manager.
publication of event messages” on page
2807.

Transactional You have any of the following nodes in your You must associate a queue manager with
support for message flows: the integration server or integration node,
SAP or use a SAPConnection policy and specify
• node
a CCDT through the Shared TID store
• node client definition file property.
• node The remoteDefaultQueueManager
setting does not apply to these nodes,
but the CCDT can specify a remote queue
manager to achieve the same effect.

Procedure
1. To install IBM MQ components, see the IBM MQ product documentation: http://www.ibm.com/
support/knowledgecenter/SSFKSJ_8.0.0/com.ibm.mq.ins.doc/q008250_.htm.
2. For capabilities listed in Capabilities that require IBM MQ to be part of the IBM App Connect Enterprise
infrastructure, associate a queue manager with the integration server or integration node that is to use
the capabilities.
3. Complete any additional configuration actions for the capability that you want to use, as indicated in
the "Additional configuration notes" column of the tables above.

98 IBM App Connect Enterprise 12.0: User Guide

Creating the default system queues on an IBM MQ queue manager
You can create the default system queues on the queue manager that is associated with your integration
server, by running a script.

Before you begin

• You must have an IBM MQ server and a queue manager to use with your IBM App Connect Enterprise
deployment. For more information about installing IBM MQ components, see the IBM MQ product
documentation: https://www.ibm.com/support/knowledgecenter/SSFKSJ_9.1.0/com.ibm.mq.ins.doc/
q008320_.htm.
• You must be a member of the mqm and mqbrkrs operating system groups.
•
Ensure that the command environment is initialized, by running the mqsiprofile script
command. For more information, see “Setting up a command environment” on page 64.

About this task

Some IBM App Connect Enterprise capabilities require access to IBM MQ components. Some of these
capabilities require a set of default system queues to be created on the queue manager that is associated
with the integration server. The default system queues are used to store information about in-flight
messages. For more information about the capabilities that require the default system queues, see
“Installing IBM MQ” on page 96.
Note: By default, running the iib_createqueues command disables IBM MQ channel authentication
for the specified queue manager. If you want to enable channel authentication, you can modify the
sample MQSC script, iib_queues_create.mqsc, that the command iib_createqueues uses to
define queues.
You cannot use a secured queue manager as the local default queue manager for an integration node or
an integration server.
Complete the following steps to create the default system queues on Windows and Linux.

Procedure
1. From the command environment (on Linux) or the IBM App Connect Enterprise Console (on Windows),
navigate to the following directory:
•
install_dir\server\sample\wmq
•
install_dir/server/sample/wmq
2. Run the following command:
•
iib_createqueues.cmd qmgr_name
•
./iib_createqueues.sh qmgr_name iib_group
The qmgr_name parameter specifies the name of the IBM MQ queue manager where you want to
create the queues.
The iib_group parameter specifies the primary group of the system account that runs the integration
server.

Results
The default IBM App Connect Enterprise queues are created on the queue manager.
To check that the queues were created, type the following commands:

runmqsc qmgr_name

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 99

 display queue(SYSTEM.BROKER*)

A message is returned that lists the queues that were created:

1 : display queue(SYSTEM.BROKER*)
AMQ8409: Display Queue details.
QUEUE(SYSTEM.BROKER.ADAPTER.FAILED) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.ADAPTER.INPROGRESS) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.ADAPTER.NEW) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.ADAPTER.PROCESSED) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.ADAPTER.UNKNOWN) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.ADMIN.STREAM) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.AGGR.CONTROL) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.AGGR.REPLY) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.AGGR.REQUEST) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.AGGR.TIMEOUT) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.AGGR.UNKNOWN) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.AUTH) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.CD.MODEL) TYPE(QMODEL)
QUEUE(SYSTEM.BROKER.CONTROL.QUEUE) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.DC.AUTH) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.DC.BACKOUT) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.DC.RECORD) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.DEFAULT.STREAM) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.EDA.COLLECTIONS) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.EDA.EVENTS) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.FTE.MODEL) TYPE(QMODEL)
QUEUE(SYSTEM.BROKER.INTER.BROKER.COMMUNICATIONS) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.MODEL.QUEUE) TYPE(QMODEL)
QUEUE(SYSTEM.BROKER.SEQ.EXPIRY) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.SEQ.GROUP) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.SEQ.NUMBER) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.TIMEOUT.QUEUE) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.WS.ACK) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.WS.INPUT) TYPE(QLOCAL)
QUEUE(SYSTEM.BROKER.WS.REPLY) TYPE(QLOCAL)

Note: You can delete the queues that are created for an integration server on a specified queue manager,
by running the following MQSC command from the same directory:

runmqsc qmgr_name < iib_queues_delete.mqsc

For more information about the runmqsc command, see https://www.ibm.com/support/

knowledgecenter/SSFKSJ_9.1.0/com.ibm.mq.ref.adm.doc/q083460_.htm.

Installing IBM License Metric Tool

IBM License Metric Tool (ILMT) enables you to monitor the use of IBM (and other) software products.

About this task

Use ITLM to perform the following software auditing functions:
• Monitor the licenses used by different machines.
• Help keep unnecessary licenses to a minimum.
• Guard against software license compliance problems.
Ensure that you choose the correct ILMT license for the IBM App Connect Enterprise edition that you have
purchased. See “Operation modes” on page 3.
If you are using one or more of the WebSphere Adapters with IBM App Connect Enterprise, you must
activate ILMT to include those adapters, for example in monitoring activities. If you require this support,
follow the instructions in “Activating IBM License Metric Tool for WebSphere Adapters” on page 1108.
If you intend to use any of the IBM App Connect Enterprise features that require MQ functionality, you
can install and use IBM MQ within the terms of your IBM App Connect Enterprise license. For more
information about using IBM MQ with IBM App Connect Enterprise, see “Installing IBM MQ” on page
96.

100 IBM App Connect Enterprise 12.0: User Guide

To find out more about using ILMT to monitor usage of IBM App Connect Enterprise and other IBM
products, or to purchase ILMT, see the IBM License Metric Tool website.
For information about installing this product, see the IBM License Metric Tool website.

Chapter 3. Installing and uninstalling IBM App Connect Enterprise 101

102 IBM App Connect Enterprise 12.0: User Guide
Chapter 4. Configuring IBM App Connect Enterprise
You can set up your application development environment to create, test, and deploy message flows
and associated resources, and then configure IBM App Connect Enterprise to run in a production
environment, either on premises or in a container. Alternatively, you can download an image from
https://hub.docker.com/r/ibmcom/ace/ and run it in a Docker container, or you can create your
own Docker images.

About this task

IBM App Connect Enterprise provides an integration server component and an integration node
component. You can configure an integration node as the central point of administrative control over a set
of owned integration servers (typically in an on-premise environment), or you can configure integration
servers that are run independently from any integration node (typically in a container environment).
This flexibility enables you to develop a solution that is best suited to the environment in which you intend
to run your App Connect Enterprise applications. You can use integration nodes to provide management
and control of your integration server processes, and to configure administration security for your
resources. Alternatively, you can choose to develop and deploy your applications to an independent
integration server quickly and easily, without the need to create and configure an integration node.
For information about configuring integration nodes and integration servers, see “Configuring integration
nodes” on page 113 and “Configuring integration servers” on page 167.

Procedure
1. Set up your development environment, as described in “Configuring the IBM App Connect Enterprise
Toolkit” on page 103.
2. Configure IBM App Connect Enterprise to run in a production environment, by following the
instructions in one of the following topics:
• “Configuring App Connect Enterprise to run on premises (on a physical or virtual machine)” on page
110
• “Configuring App Connect Enterprise to run in a container” on page 111
• “Configuring App Connect Enterprise to run in Docker” on page 111

Configuring the IBM App Connect Enterprise Toolkit

Set up your application development environment on Linux on x86-64 or Windows 64-bit to create, test,
and deploy message flows and associated resources. You can configure various settings in the IBM App
Connect Enterprise Toolkit to suit your requirements and your working environment.

About this task

Use the IBM App Connect Enterprise tutorials to help you get started with developing integration
solutions. The tutorials are in the Tutorials Gallery, which you can find by clicking Help > Tutorials Gallery
in the IBM App Connect Enterprise Toolkit. When you have tried out your first few tutorials, you can set up
an environment that can support your application developers.
When you start the IBM App Connect Enterprise Toolkit, a workbench session opens, which you can
use to create, configure, and manage your application development resources. You can configure your
workbench session in various ways to suit your working environment and preferences. These options are
described in “Configuring the IBM App Connect Enterprise Toolkit” on page 103.
If you are planning to run your IBM App Connect Enterprise integrations in a container, you will need to
create and configure your integration servers. If you are planning to run your integrations on premises (on

© Copyright IBM Corp. 2016 103

 a physical or virtual machine), you will need to create your integration servers and at least one integration
node.
The following topics show you how to configure aspects of the IBM App Connect Enterprise Toolkit.

Results
A minimum display resolution of at least 1024 x 768 is required for some dialog boxes, such as the
Preferences dialog box.

Starting the App Connect Enterprise Toolkit

Use the development environment on Linux or Windows to develop your message flows.

Before you begin

Install the IBM App Connect Enterprise Toolkit; for more information, see “Installing IBM App Connect
Enterprise software” on page 75.

Procedure
To start using your development environment, complete the following steps.
1. Start the App Connect Enterprise Toolkit in the following way:
•
From the installation directory, for example $HOME/ace-11.0.0.0, type the following
text:
./ace toolkit
•
Search for IBM App Connect Enterprise Toolkit 12.0.n and start it.
Your IBM App Connect Enterprise Toolkit session opens, and displays the Welcome page. You can
tailor various settings in the IBM App Connect Enterprise Toolkit to suit your requirements and your
working environment; for example, the colors and fonts. These options are described in “Configuring
the IBM App Connect Enterprise Toolkit” on page 103.
2. Close the Welcome page.
You can return to the Welcome page later by clicking Help > Welcome. If more than one option is
listed, select IBM App Connect Enterprise.
3. In the Integration Development perspective, select the Integration Explorer view.
Your configuration might be affected by the operation mode in which IBM App Connect Enterprise is
running. The default operation mode is advanced mode, in which your integration servers run with
no restrictions. Check with your integration administrator which operation mode applies to your
organization; you might have to change the mode of your integration node or servers after you have
created them. For more information about operation modes, see “Operation modes” on page 3.
4. If you are planning to run your integration in a container, you must configure at least one integration
server.
For more information, see “Configuring an integration server by modifying the server.conf.yaml file” on
page 172.
5. If you are planning to run your integration on premises (on a physical or virtual machine), you must
have at least one integration node with at least one associated integration server.
For information about how to create an integration node, see “Creating an integration node” on page
114. To add integration servers to your integration node, right-click the integration node, and click
New > Integration Server. Enter a name for your integration server, and click OK.
The integration server is the runtime environment in which your message flows run. You can create
many integration servers on a single integration node, and you can deploy your message flows to one
or more integration servers on one or more integration nodes.
For more detailed instructions about this task, see “Creating an integration server” on page 168.

104 IBM App Connect Enterprise 12.0: User Guide

 Results
Your configuration is now ready to use.

What to do next
You can start to develop resources to deploy to your integration server. You can create your own message
flows, or you can use the patterns and samples that are provided to get you started. For details of these
options, see Chapter 6, “Developing integration solutions,” on page 481.
This task has covered the minimum set of steps that you must complete to create an integration server
and (optionally) an integration node, and to configure your development environment. Typically, as an
application developer, you are working in a single platform environment to create, deploy, and test your
message flows before they are ready for use in a test of production environment.
More options are available for enhanced configurations, including policies. When the requirements of your
message flows extend beyond this basic configuration, and you need additional configuration to support
those requirements, you can find details of these more advanced options in “Configuring App Connect
Enterprise to run on premises (on a physical or virtual machine)” on page 110 and “Configuring App
Connect Enterprise to run in a container” on page 111.

Changing IBM App Connect Enterprise Toolkit preferences

The IBM App Connect Enterprise Toolkit has many preferences that you can change to suit your
requirements. Some of these preferences are specific to IBM App Connect Enterprise. Other preferences
control more general options, such as the colors and fonts in which information is displayed.

Procedure
To access the IBM App Connect Enterprise Toolkit preferences, complete the following steps.
1. Select Window > Preferences.
2. Click the plus sign that is associated with General, typically the first entry in the left pane.
An expanded list of options appears, Select the aspect of the IBM App Connect Enterprise Toolkit that
you want to modify. These options might be of interest:
Startup and shutdown
Display or suppress the dialog that prompts you to confirm the workspace location when you start
IBM App Connect Enterprise Toolkit. By default, the dialog is suppressed.
Specify whether to display the dialog box that prompts you to confirm shutdown of the IBM App
Connect Enterprise Toolkit.
Appearance
Change the default fonts and colors that appear in the IBM App Connect Enterprise Toolkit.
Perspectives
Choose whether to open a new perspective in a new window.
3. When you have made your changes, click OK to close the Preferences dialog.

What to do next
Below the General category in the Preference dialog, there are items that refer specifically to IBM App
Connect Enterprise resources, such as message flows. Review the following topics for information about
setting preferences and other values that are specific to your use of these resources:
• Message flow preferences
• “Changing ESQL preferences” on page 1625
• “Message Sets: Configuring message set preferences” on page 2249
• “Testing and troubleshooting message flows” on page 647

Chapter 4. Configuring IBM App Connect Enterprise 105

Changing workbench capabilities
You can configure the workbench to disable access to some of the functional capabilities of IBM App
Connect Enterprise.

About this task

Capabilities is an Eclipse concept that allows you to enable or disable the components of a product. By
default, all components of the workbench are enabled.
To access the workbench capabilities:

Procedure
1. Select Window > Preferences.
2. Click the plus sign associated with General.
An expanded list of options appears.
3. Click Capabilities.
You can use the capabilities that are listed to enable or disable various product components; the
capabilities are grouped according to a set of predefined categories.
4. Select IBM Integration Toolkit from the list of capabilities that is displayed, and select the Advanced
button.
A window opens that has a check box for each of the predefined categories.
5. Select the check boxes for the categories that you want to either enable or disable; click either the
Enable All or Disable All button and click OK.
A pane describes the functionality that is enabled following this action.

What to do next
The predefined categories for the workbench are listed together with a reference to more information
about the relevant functional area of IBM App Connect Enterprise:
• IBM Integration Toolkit - Administration. See Chapter 5, “Administering IBM App Connect Enterprise,”
on page 243.
• IBM Integration Toolkit - Core. See #unique_127.
• IBM Integration Toolkit - Development. See Chapter 6, “Developing integration solutions,” on page
481.

106 IBM App Connect Enterprise 12.0: User Guide

Configuring CVS to run with the IBM App Connect Enterprise Toolkit
Install CVS as a normal program by following the usual prompts. Not all versions of CVSNT are supported
by Eclipse.

Procedure
1. Configure CVS by carrying out the following tasks:
a) Create a directory on your computer, for example, on Windows - c:\CVSRepository.
b) Start the CVSNT control panel.
Select Start > Programs > CVSNT to see the icon on the desktop.
c) Stop both the CVS Service and the CVS Lock Service.
d) Select the Repositories tag, click Add and create a new repository.
Note that no entry appears on the screen the first time that you do this.
e) Use the ... button on the next window to select the directory that you created in step “1.a” on
page 107 and click OK.
Note that when CVS has finished formatting its repository the backslash in the directory name is
changed to a forward slash.
f) Select the Service Status tab and restart both the CVS Service and the CVS Lock Service.
2. Enable the CVS Revision tag to be populated in the Eclipse Version fields in the IBM App Connect
Enterprise Toolkit.
To do this on Windows:
a) Select Window->Preferences
b) Expand the Team section and click CVS
c) Use the drop down in the Default keyword substitution: field and set the value to ASCII with
keyword expansion(-kkv)
3. Add the IBM App Connect Enterprise file types to the Eclipse CVS configuration.
To do this:
a) Select File Content in the Team section of the window you opened in step “2” on page 107
b) Click Add and add msgflow as an allowable file extension.
Ensure that the value is set to ASCII.
c) Repeat the above procedure for the following file extensions that the integration node uses:
• esql
• mset
• mxsd
If you use CVS to store other file types, for example, COBOL copybooks add the appropriate file
types as well.
d) Click OK when you have finished.

Configuring the IBM App Connect Enterprise Toolkit to run Rational

ClearCase
To use Rational® ClearCase® with the IBM App Connect Enterprise Toolkit, install Rational ClearCase
Remote Client for Eclipse.

About this task

To enable Rational ClearCase in the IBM App Connect Enterprise Toolkit you must install
Rational ClearCase Remote Client for Eclipse version 7.1.2.9 or later; see http://www.ibm.com/
support/knowledgecenter/SSSH27_7.1.2/com.ibm.rational.clearcase.cc_ms_install.doc/topics/

Chapter 4. Configuring IBM App Connect Enterprise 107

 t_install_ccrc_eclipse.htm. Follow the instructions to install Rational ClearCase Remote Client for Eclipse
on Eclipse 3.4.
For information about the system requirements for Rational ClearCase Remote Client for Eclipse, see
http://www.ibm.com/support/docview.wss?uid=swg21224586.

Results
After you enable the ClearCase capability, the ClearCase menu is displayed in the Integration
Development perspective.

What to do next
To work with ClearCase:
1. Click ClearCase > Connect to Rational ClearCase.
2. Right-click your project and click Team > Add to Version Control to add your projects to the ClearCase
source control.
3. After you add your projects to the ClearCase source control, you can perform ClearCase operations.

Creating a working set

Create a working set to limit the number of resources that are displayed in the Application Development
view.

Before you begin

To read about working sets, see Working sets.

About this task

By creating and using a working set, you can reduce the visual complexity of what is displayed in the
Application Development view, making it easier to manage and work with your projects.
To create a new working set, complete the following steps:

Procedure
1. Click the arrow on the toolbar of the Application Development view, then click Select Working Set.
A list is displayed containing existing working sets. A working set is created automatically when
you create an application or library. The names of these working sets are enclosed by brackets; for
example [Application1].
2. To open the New Working Set wizard, click New.
3. Select a type for the new working set (for example, Integration node), then click Next.
4. Enter a name for the working set.
5. Select the resources that you want to include in this working set. You can also include all the projects
that are dependent on your selected resources by selecting Automatically include dependent
projects in this working set.
6. Click Finish.

Results
The new working set is created.

What to do next
• To show only the resources in a working set, click the arrow on the toolbar of the Application
Development view, click Select Working Set, then select the relevant working set. If you select the

108 IBM App Connect Enterprise 12.0: User Guide

 working set that is created automatically for an application or library (as indicated by brackets; for
example, [Application1]), the Application Development view shows only the selected container and its
contents.
• To edit the selected working set, click the arrow on the toolbar of the Application Development view,
then click Edit Active Working Set. When you delete the active working set, all resources are shown
automatically. You cannot edit the working sets that are created automatically for an application or
library, as indicated by brackets; for example, [Application1].
• To delete the selected working set, click the arrow on the toolbar of the Application Development view,
click Select Working Set, then click Remove.
• To show all resources, click the arrow on the toolbar of the Application Development view, then
click Deselect Working Set. Alternatively, click the Remove all filters icon on the toolbar of the
Application Development view.

Integrating the Rational Team Concert client with the IBM App Connect
Enterprise Toolkit
You can integrate the Rational Team Concert client with the IBM App Connect Enterprise Toolkit.

About this task

To integrate the Rational Team Concert client with the IBM App Connect Enterprise Toolkit, complete the
following steps.
The supported versions of Rational Team Concert are V4.0.3 or later, and V5.0 or later, with Eclipse 4.2.2
support.

Procedure
1. Download the Rational Team Concert client.
a) Navigate to the Rational Team Concert download site: https://jazz.net/downloads/rational-team-
concert/.
b) Select the client that you want and click More download options.
For example, select Rational Team Concert 5.0.2 if you want the Rational Team Concert V5.0.2
client.
c) Select p2 Install Repository in the Plain .zip Files section to select the p2 install repository.
d) Sign in to Jazz® and locate the p2 install directory.
For example, the p2 install repository for the Rational Team Concert V5.0.2 client is RTC-Client-
p2Repo-5.0.2.zip.
e) Unzip the p2 install repository into a local directory.
2. Start the IBM App Connect Enterprise Toolkit and select Help > Install New Software.
3. In the Available Software window, click Add.
4. In the Add Repository window, click Archive, navigate to the local directory in which you unzipped the
p2 install repository in step “1.e” on page 109, and click OK.
5. Ensure that Group items by category is selected, and then select Rational Team Concert Client
(extend an Eclipse installation).
6. Click Next, then Next again in the Install Details window.
7. Accept the terms of the license agreement and click Finish.
A security warning window opens during the installation because the Rational Team Concert client
bundles and features are not signed.
8. Click OK to complete the installation.
9. Click Restart Now when prompted to restart the IBM App Connect Enterprise Toolkit.

Chapter 4. Configuring IBM App Connect Enterprise 109

 What to do next
To work with Rational Team Concert source control:
1. Start the IBM App Connect Enterprise Toolkit.
2. Open the Work Items perspective and click Window > Open Perspective > Other > Work Items.
3. Click the Create Repository Connection link in the Team Artifacts view.
4. Follow the dialog and enter the information given to you by your Jazz administrator.
5. To add your project to the repository, right-click the project and select Team > Share Project.
6. In the Share Project window, select Jazz Source Control as the repository type.
See Getting started in your Rational Team Concert® source control workspace for more details about the
Rational Team Concert source control operations.
You can also use the Jazz Team Build as your build engine for the IBM App Connect Enterprise Toolkit; see
Building with Jazz Team Build for more information.

Configuring App Connect Enterprise to run on premises (on a

physical or virtual machine)
You can create one or more integration nodes on one or more computers, and configure them on your test
and production systems to process messages that contain your business data.

About this task

On Linux and Windows systems, you can install IBM App Connect Enterprise and the IBM App Connect
Enterprise Toolkit, and start developing your applications. You can also configure an environment for
more advanced application development and unit test, as described in “Configuring the IBM App Connect
Enterprise Toolkit” on page 103.
Use the information in this section to plan and configure the resources that you need to run on premises.
Alternatively, you can configure App Connect Enterprise to run in a container or in Docker.

Procedure
1. Plan your system; see “Planning an IBM App Connect Enterprise environment” on page 8.
2. Ensure that you have the correct authorization and permissions to create and access components.
For more information, see “Authorization for configuration tasks” on page 2492 and “Security for
runtime components” on page 2632.
3. Create the components, as described in “Configuring integration nodes” on page 113 and
“Configuring integration servers” on page 167.
4. If you want to ensure that you are using the correct operation mode for your license, see “Checking
the operation mode” on page 87 and “Changing the operation mode” on page 86.
5. Create and configure the databases.
6. If you want to ensure the data integrity of transactions, Configure global coordination of transactions.
7. If you want to connect to external resources such as Enterprise Information Systems, IMS, or JMS,
Configure properties to connect to external resources.
8. If you want to configure the storage of events for aggregation, Collector, resequence, or timeout
nodes, or configure monitoring event sources, Configure internal resources that are required by
message flows.
9. If you want to view objects in a different language or code page, Change the locale.
10. If you want to operate your IBM App Connect Enterprise instances in a highly available configuration;
see “Configuring integration nodes for high availability” on page 120.
11. If you want to operate your integration node as an IBM MQ service; see “Configuring an integration
node as an IBM MQ service” on page 166.

110 IBM App Connect Enterprise 12.0: User Guide

Configuring App Connect Enterprise to run in a container
You can configure one or more integration servers and deploy them to run in a container, where they will
process messages that contain your business data.

About this task

On Linux and Windows systems, you can install IBM App Connect Enterprise and the IBM App Connect
Enterprise Toolkit, and start developing your applications. You can also configure an environment for
more advanced application development and unit test, as described in “Configuring the IBM App Connect
Enterprise Toolkit” on page 103.
Use the information in this section to plan and configure the resources that you need to run in a container.
Alternatively, you can configure App Connect Enterprise to run on premises or in Docker.
If you are intending to run App Connect Enterprise in a container, you can develop and deploy your
applications to an independent integration server quickly and easily, without the need to create and
configure an integration node.

Procedure
Configure App Connect Enterprise to run in a container by following these steps:
1. Plan your system; see “Planning an IBM App Connect Enterprise environment” on page 8.
2. Configure security for the integration server, as described in “Configuring HTTP basic authentication
for an integration node or server” on page 2548 and “Configuring SSL or TLS for an integration node or
server” on page 2548.
3. Create and configure your integration servers, as described in “Configuring integration servers” on
page 167.
4. If you want to ensure that you are using the correct operation mode for your license, see “Checking the
operation mode” on page 87 and “Changing the operation mode” on page 86.
5. Create and configure the databases.
6. If you want to connect to external resources such as Enterprise Information Systems, IMS, or JMS,
Configure properties to connect to external resources.
7. If you want to configure the storage of events for aggregation, Collector, resequence, or timeout nodes,
or configure monitoring event sources, Configure internal resources that are required by message
flows.
8. If you want to view objects in a different language or code page, Change the locale.

Configuring App Connect Enterprise to run in Docker

You can configure IBM App Connect Enterprise to run in a Docker container on AIX, Linux, and Windows
systems, and in IBM z/OS Container Extensions (zCX).

About this task

You can use Docker to package an integration server into a standardized unit for software development.
Changes to your IBM App Connect Enterprise environment can then be deployed to test and staging
systems quickly and easily, which can be a major benefit to continuous delivery in your enterprise. You
can choose to build specific configurations into your IBM App Connect Enterprise Docker images, such
as integration servers where particular applications are deployed. Or you can choose to start a Docker
container from the image, then deploy changes to the running integration server.
You can create your own Docker images by using the supplied files on ot4i (at https://github.com/ot4i/
ace-docker). Alternatively, you can download a pre-built image of the IBM App Connect Enterprise
for Developers edition (on selected platforms) to run in a Docker container. For more information, see
Obtaining the IBM App Connect Enterprise server image from the IBM Cloud Container Registry. A pre-
built image is not currently available for download for IBM z/OS Container Extensions (zCX).

Chapter 4. Configuring IBM App Connect Enterprise 111

 Procedure
Use the information in the following topics to help you plan, install, and configure IBM App Connect
Enterprise to run in Docker:
• “Docker support on Linux systems” on page 112
• “Stopping an IBM App Connect Enterprise Docker container” on page 112
• “Building a sample IBM App Connect Enterprise image using Docker” on page 113

What to do next
For more information about using Docker with IBM App Connect Enterprise, see Running IBM App
Connect Enterprise in a Docker container.

Docker support on Linux systems

IBM App Connect Enterprise supports the use of Docker for hosting production servers, and for
development and test environments. You can configure IBM App Connect Enterprise to run in a Docker
container on AIX, Linux, and Windows systems, and in IBM z/OS Container Extensions (zCX).

About this task

For the latest information about version numbers and supported environments, see the system
requirements information on the IBM Support web pages.
When you are running IBM App Connect Enterprise in a Docker container, you can build your own Docker
images or you can use the samples that are provided. Note the following requirements:
• You must use Docker v1.7 or higher.
• The Docker guest must be an IBM App Connect Enterprise supported operating system.
• The host on which the Docker container is running must use a Linux kernel at level 3.10 or later.
• IBM App Connect Enterprise has no specific requirements for kernel configuration parameters, but
other supporting products such as IBM MQ might have additional requirements.
• As advised in the Docker documentation, if you want data that is related to IBM App Connect Enterprise
to be persisted independently of the container lifecycle, you must ensure that it is stored on a Docker
volume. For more information, see https://docs.docker.com/engine/tutorials/dockervolumes/.
• To receive IBM support, you must have the following:
– A means of capturing syslog messages.
– A means of running commands against the running node; for example, by using docker exec bash
-c mqsilist with the mqsiprofile set on login, or through ssh.
– Access to the workpath directories, for diagnostic purposes.
For more information about Linux support, see IBM App Connect Enterprise system requirements for
Linux systems:

Stopping an IBM App Connect Enterprise Docker container

You can stop your IBM App Connect Enterprise Docker container by running the docker stop command
or by pressing Ctrl-C. You can configure IBM App Connect Enterprise to run in a Docker container on
AIX, Linux, and Windows systems, and in IBM z/OS Container Extensions (zCX).

About this task

You can stop a Docker container by using one of the following methods:

112 IBM App Connect Enterprise 12.0: User Guide

 • If the container is running with a pseudo-TTY allocated (by specifying the -t flag on the docker run
command), you can stop it by pressing Ctrl-C. The signal is caught by the integration server, which
shuts down gracefully.
• Run the docker stop command against the running container, as shown in the following example:

docker stop myAce

Building a sample IBM App Connect Enterprise image using Docker

You can build a sample IBM App Connect Enterprise Docker image. You can configure IBM App Connect
Enterprise to run in a Docker container on AIX, Linux, and Windows systems, and in IBM z/OS Container
Extensions (zCX).

About this task

To run IBM App Connect Enterprise in a Docker container, you must first build a base image containing an
installation of IBM App Connect Enterprise. Instructions are available in the IBM App Connect Enterprise
GitHub repository, at https://github.com/ot4i/ace-docker. Alternatively, you can download an image of the
IBM App Connect Enterprise for Developers edition (for selected platforms) from https://hub.docker.com/
r/ibmcom/ace/ and use this to run a Docker container.
If you plan to use IBM z/OS Container Extensions (zCX), ensure that you have installed the Linux on
zSeries package. Until APAR OA59111 is available, you can build an image on IBM z/OS Container
Extensions (zCX) only by using the experimental Ubuntu Dockerfiles. A pre-built image is not currently
available for download for IBM z/OS Container Extensions (zCX).
A Dockerfile is a set of instructions for building a Docker image. Images can be stored in local or remote
registries, and are used to create a running Docker container. To build the image, Docker executes the
instructions in the Dockerfile. Each instruction causes a new image layer to be created. Docker best
practice guidelines recommend that you keep the number of Dockerfile instructions to a minimum,
because the number of layers in an image might be limited. The guidelines, which are available at https://
docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices, suggest that you “find the
balance between readability (and thus long-term maintainability) of the Dockerfile and minimizing the
number of layers it uses. Be strategic and cautious about the number of layers you use.”
The following GitHub repository contains a Dockerfile and some additional files that show how you can
build an IBM App Connect Enterprise Docker image: https://github.com/ot4i/ace-docker.
If you do not have access to the GitHub CLI (which is not currently available on IBM z/OS Container
Extensions (zCX)), you can obtain the contents of the repository by running the following curl command:

curl -Lk https://github.com/ot4i/ace-docker/tarball/master | tar xz

Configuring integration nodes

Create and configure the integration node that you want on the operating system of your choice.

Before you begin

Ensure that the following requirements are met:
• Your user ID has the correct authorizations to perform the task. The authorizations are defined in
Security requirements for administrative tasks.
•
On Windows: you have created a user ID to be used as the service user ID. You specify this
ID when you create the integration node; it is used to run the integration node.
For more information about user ID authorization and creation, refer to “Planning for security” on page
17.

Chapter 4. Configuring IBM App Connect Enterprise 113

 • You have initialized the command environment on distributed systems; see “Setting up a command
environment” on page 64.

About this task

When you have created your physical components, you can administer your test and production
environments programmatically by using the IBM Integration API.
This collection of tasks uses specific resource names and user IDs. These names are examples only; you
can use your own names. Follow existing naming conventions for IBM MQ and other resources.

Procedure
• Create an integration node by following in the instructions in “Creating an integration node” on page
114.
• Verify that the integration node is created by following the instructions in “Verifying an integration
node” on page 120.
• Modify the integration node by following the instructions in “Configuring an integration node by
modifying the node.conf.yaml file” on page 118.
• (Optional) If you are developing message flows that include resources such as the WebSphere
Adapters nodes, IMS nodes, or the CICSRequest node, you must set up your environment to support
these applications. Details of the setup that you require is in “Configuring the environment to access
external applications and resources” on page 182.
• (Optional) If you are working with web services message flows and want to ensure reliable messaging,
you can configure WS-RM using policy sets. See “Web Services Reliable Messaging” on page 818.
• (Optional) You can use WS-Security with your web services message flows to provide quality of
protection through message integrity, message confidentiality, and single message authentication. See
“WS-Security” on page 2650.

Creating an integration node

You can create integration nodes on every software platform that is supported by IBM App Connect
Enterprise.

Before you begin

Complete the following tasks:
• Ensure that your user ID has the correct authorizations to perform the task. Refer to Security
requirements for administrative tasks.
• On distributed systems, you must set up your command line environment before you create
an integration node by running the product profile or console; refer to “Setting up a command
environment” on page 64.

About this task

Create an integration node by using the command line on the computer on which you installed IBM App
Connect Enterprise.
You must give the integration node a name that is unique on the local computer. Integration node names
are case-sensitive on all supported platforms except Windows.
Optionally, on all distributed systems you can specify a queue manager to be associated with the
integration node. This queue manager is used by default for IBM MQ processing in the message flow if no
queue manager has been specified explicitly on the MQ node. Some message flow nodes such as CD and
FTE nodes, and event-driven processing nodes used for aggregation, timeout, message collections, and
message sequences, require a queue manager to be specified for the integration node. These nodes use
system queues, which are owned by the queue manager, to store information about in-flight messages.

114 IBM App Connect Enterprise 12.0: User Guide

For information about creating the system queues, see “Creating the default system queues on an IBM
MQ queue manager” on page 99.
Queues that are specified on event-driven processing nodes are created automatically when the flow is
deployed, provided that the integration node has the required permissions to create the queues. If the
queues are not created automatically, you can create them manually; see “Creating the default system
queues on an IBM MQ queue manager” on page 99. For more information about using IBM MQ with IBM
App Connect Enterprise, see “Installing IBM MQ” on page 96 and “Enhanced flexibility in interactions with
IBM MQ ” on page 26.
Multiple integration nodes can specify the same queue manager. You can also specify a queue manager
to be used by an existing integration node, by modifying the node.conf.yaml configuration file for the
integration node. You must then restart the integration node for the changes to take effect.
The mode in which IBM App Connect Enterprise is running can affect the number of integration servers
and message flows that you can deploy. For more information, see “Restrictions that apply in each
operation mode” on page 5.
To create an integration node, complete the steps in “Creating an integration node by using the command
line” on page 115.
If you want to configure the integration node as an IBM MQ trusted application, see “Using IBM MQ
trusted applications” on page 117.

Creating an integration node by using the command line

On Linux, UNIX and Windows, you can create integration nodes on the command line.

Before you begin

• If you want to configure the integration node as an IBM MQ trusted application, see “Using IBM MQ
trusted applications” on page 117.
• Read “Controlling access to IBM App Connect Enterprise” on page 2633.
• Check which operation mode you are licensed to use. If you do not set a mode, the automatic default is
advanced mode; see “Operation modes” on page 3.

About this task

When you create an integration node, you can optionally specify a queue manager for the integration
node. If you do not specify a queue manager, features that require access to IBM MQ will be unavailable.
For more information about using IBM MQ with IBM App Connect Enterprise, see “Enhanced flexibility in
interactions with IBM MQ ” on page 26 and “Installing IBM MQ” on page 96.
When you create an integration node, a subdirectory is created to store files for the integration node (and
its integration servers and the resources deployed to those servers). These files include the integration
node's configuration file, node.conf.yaml. By default, the node's subdirectory is created under the
IBM App Connect Enterprise working directory, which was set when the product was installed. On the
mqsicreatebroker command you can optionally use the -w workPath parameter to specify your own
choice of working directory.
For example, for the integration node node_name, the default working directory on Windows is C:
\ProgramData\IBM\MQSI\components\node_name, which has the following structure:
C:\ProgramData\IBM\MQSI\components\node_name
C:\ProgramData\IBM\MQSI\components\node_name\node.conf.yaml
...
C:\ProgramData\IBM\MQSI\components\node_name\servers

The node_name\servers directory is created when you later create an integration server for the
integration node, and a subdirectory is created under node_name\servers to store files for each
integration server. These files include the server's configuration file, server.conf.yaml. For example,
two integration servers created under the integration node NODEIPL102:
C:\ProgramData\IBM\MQSI\components\NODEIPL102\servers\N101ISAA

Chapter 4. Configuring IBM App Connect Enterprise 115

 C:\ProgramData\IBM\MQSI\components\NODEIPL102\servers\N102ISAB

When you create an integration node by running the mqsicreatebroker command, an overrides
subdirectory is also created under the working directory for the integration node. This overrides directory
contains an additional node.conf.yaml configuration file, which contains property values that are set
by IBM App Connect Enterprise commands, including the mqsicreatebroker command. These values
override any values that are set for the same properties in the integration node's base node.conf.yaml
file.
When you have created the integration node, you can configure it by modifying properties in its
node.conf.yaml configuration file (for example, C:\ProgramData\IBM\MQSI\components
\acev11node\node.conf.yaml). If any commands are run subsequently, which modify settings
for the integration node, those modified settings are saved in a node.conf.yaml file in the overrides
directory (for example, C:\ProgramData\IBM\MQSI\components\acev11node\overrides
\node.conf.yaml).
If a property has been set in the integration node's base node.conf.yaml file, and also in the overrides
directory (\overrides\node.conf.yaml), the property value that has been set in the overrides
directory is used. Therefore, if an integration node does not appear to be using the settings that you would
expect, check the node.conf.yaml file in the overrides directory to see if your expected property value
has been overridden by a command. If you want to manually override the settings that have resulted
from a command, you can either edit the property in the node.conf.yaml file in the overrides directory,
or you can remove the entry from the overrides directory and modify the base node.conf.yaml file
instead.
To create an integration node by using the command line, complete the following steps:

Procedure
1. Ensure that you have the authority to create an integration node by following the steps for your
operating system:
•
On Linux and UNIX, ensure that you are logged in using a user ID that has
authority to run the mqsicreatebroker command.
Run the mqsiprofile script to set up the command environment for the integration node:

install_dir/server/bin/mqsiprofile

You must run this script before you can run the IBM App Connect Enterprise commands.
For more information, see “Setting up a command environment” on page 64.
•
On Windows, open an IBM App Connect Enterprise command prompt for the runtime
installation in which you want to create the integration node. For more information about initializing
the runtime environment, see “Setting up a command environment” on page 64.
On Windows systems, you must open a command console with elevated privileges. To open a
command console with elevated privileges, use the mqsicommandconsole command. For more
information, see command.
2. Use the mqsicreatebroker command to create the integration node.
For example, if you want to create an integration node that is called INODE with a queue manager that
is called ACEQMGR, enter the following command:

mqsicreatebroker INODE -i wbrkuid -a wbrkpw -q ACEQMGR

Where wbrkuid and wbrkpw are the user name and password under which the integration node runs.
Note: You can specify a queue manager name that does not exist, but the specified queue manager
must be running before you start your integration node.
When you create your first integration node, the web user interface uses the default port 4414, and
for each integration node created after the port number increments automatically by one. You can

116 IBM App Connect Enterprise 12.0: User Guide

 change the port number to be used by editing the integration node's node.conf.yaml file. You can
also change the port number or disable the web user interface by using the mqsichangeproperties
command. If administration security is not enabled, web users can access the web user interface as a
default user with unrestricted access to data and integration node resources.
For more information about the command parameters, see command.

Results
You have created an integration node.

What to do next
(Optional) If you want to configure properties of the integration node, edit its node.conf.yaml file.
For example, you can set a REST administration port and an HTTPS port, you can enable administration
security, and you can configure the trace level, activity logging, JVM, and the reporting of statistics
and accounting data. For more information, see “Configuring an integration node by modifying the
node.conf.yaml file” on page 118.
Start the integration node by using the mqsistart node_name command. See “Starting and stopping an
integration node on Windows, Linux, and UNIX systems” on page 247.
1. If you want to work with the integration node in the IBM App Connect Enterprise Toolkit (or a custom
integration application), connect the toolkit to the integration node. For example, connect to the
integration node before you can use the Enterprise Toolkit to start the node's web user interface or
create integration servers associated with the integration node. See “Connecting to an integration
node by using the Toolkit” on page 245.
2. If you want to use the web user interface to manage the integration node's integration servers and
their resources, start the web user interface using the administration URI (hostname and port)
configured for the integration node. The hostname and port are reported by the mqsilist command;
for example:

mqsilist
...
BIP1325I: Integration node 'NODEIPL101' with administration URI 'http://<host>:4417' is
running.

For more information about using the web user interface to manage integration servers and their
resources, see “Managing integration servers” on page 249 and “Managing deployed resources” on
page 316.
3. Create integration servers under the integration node; for example, by using the Enterprise Toolkit or
the web user interface. For more information, see “Creating an integration server” on page 168.
When you have completed these tasks, you can create the resources that you want to associate with the
integration node; for example message flows. You can create and work with resources by using either the
IBM App Connect Enterprise Toolkit or the IBM Integration API.

Using IBM MQ trusted applications

Configure an integration node to run as an IBM MQ trusted application.

Before you begin

You must complete the following tasks:
• Ensure that your user ID is a member of the mqm group. On UNIX and Linux, specify the user ID mqm
as the service user ID when you create the integration node. On Windows, use any service user ID that
is a member of mqm. Refer to Security requirements for administrative tasks.
• Review the restrictions that IBM MQ places on trusted applications that apply to your environment. See
Connecting to a queue manager using the MQCONNX call in the IBM MQ product documentation online.

Chapter 4. Configuring IBM App Connect Enterprise 117

 About this task
You can configure an integration node to run as a trusted (fastpath) application on all supported
platforms . If the integration node is configured as a trusted application, it runs in the same process as
the IBM MQ queue manager agent, and all integration node processes benefit from an improvement in the
overall system performance.
An integration node does not run as a trusted application by default; therefore, you must create a trusted
application by using the command.
Configuring an integration node as a trusted application does not affect the operation of IBM MQ channel
agents or listeners. For more information about running these as trusted applications, see Running
channels and listeners as trusted applications in theIBM MQ product documentation online.
Take care when deploying user-defined message flow nodes or parsers. Because a trusted application
(the integration node) runs in the same operating system process as the queue manager, a user-defined
message flow node or parser might compromise the integrity of the queue manager. Consider fully the
restrictions that apply to your environment and test user-defined nodes and parsers in a non-trusted
environment before deploying them in a trusted integration node.
You can configure an integration node to run as a trusted application when you create it.

Procedure
• To create an integration node on a command line, run the mqsicreatebroker command with the -t
flag, which specifies that the integration node is created as a trusted application.
For example, enter the following command to create an integration node called INODE as a trusted
application:

mqsicreatebroker INODE -q ACEQMGR -i mqm -t

See “Creating an integration node” on page 114 for more detailed information about how to create an
integration node for your platform.

Configuring an integration node by modifying the node.conf.yaml file

You can configure an integration node by setting properties in the node.conf.yaml configuration file for
the integration node.

Before you begin

You must have completed the following tasks:
• Ensure that your user ID has the correct authorizations to perform the task; see Security requirements
for administrative tasks.
• Create an integration node.

About this task

When you create an integration node, a default node.conf.yaml configuration file is created
automatically for the integration node and stored in the working directory for the integration node; for
example: C:\ProgramData\IBM\MQSI\components\acev11node\node.conf.yaml. You can then
configure the operation of the integration node and associated resources, by modifying properties in
the node.conf.yaml file. For example, you can set a REST administration port and an HTTPS port, you
can enable administration security, and you can configure the trace level, activity logging, JVM, and the
reporting of statistics and accounting data.
When you create an integration node, an overrides subdirectory is also created under the integration
node's working directory. This overrides directory contains an additional node.conf.yaml configuration
file, which contains property values that are set by IBM App Connect Enterprise commands, including the

118 IBM App Connect Enterprise 12.0: User Guide

mqsicreatebroker command. These values override any values that are set for the same properties in
the integration node's base node.conf.yaml file.
When commands are run that modify settings for the integration node, those modified settings are
saved in a node.conf.yaml file in the overrides directory (for example, C:\ProgramData\IBM\MQSI
\components\acev11node\overrides\node.conf.yaml).
If a property has been set in the integration node's base node.conf.yaml file, and also in the overrides
directory (\overrides\node.conf.yaml), the property value that has been set in the overrides
directory is used. Therefore, if an integration node does not appear to be using the settings that you would
expect, check the node.conf.yaml file in the overrides directory to see if your expected property value
has been overridden by a command. If you want to manually override the settings that have resulted
from a command, you can either edit the property in the node.conf.yaml file in the overrides directory,
or you can remove the entry from the overrides directory and modify the base node.conf.yaml file
instead.
When you create integration servers that are owned by the integration node, a default
server.conf.yaml configuration file is created for each of the integration servers, and they are stored
in the file system in subdirectories below the integration node directory. Any properties that you set for
the integration node, in the node.conf.yaml file, are inherited by the integration servers that it owns.
However, you can change any of the integration server properties by modifying them in the appropriate
server.conf.yaml file. For more information about configuring integration servers that are managed by
an integration node, see “Configuring an integration server by modifying the server.conf.yaml file” on page
172.

Procedure
Change the properties of an integration node, by following these steps:
1. Use a YAML editor to open the node.conf.yaml file for the integration node that you want to modify.
If you do not have access to a YAML editor, you can edit the file by using a plain text editor; however,
you must ensure that you do not include any tab characters, which are not accepted in YAML and will
cause your integration node configuration to fail. If you choose to use a plain text editor, ensure that
you use a YAML validation tool to validate the content of your file.
For more information about working with YAML, see http://www.yaml.org/start.html.
2. Modify the properties that you want to change:
a) Set the administration REST API port for the App Connect Enterprise web user interface and
the App Connect Enterprise Toolkit, by setting a value for the port property. You can leave this
property set to the default value of 4414.
b) Specify a value for the host property.
c) Enable authentication for the integration node, by setting the basicAuth property to true:

basicAuth: true

d) Enable administration security and specify an authorization mode, by setting the

authorizationEnabled and authorizationMode properties.
For example:

authorizationEnabled: true
authorizationMode: 'file'

e) You can also modify properties to enable the integration node listener, to configure the MQTT
server, and to specify a default queue manager.
3. Specify the security credentials to be used by the integration node when connecting to a secured
resource (such as a database) by using the mqsisetdbparms command. When you run this command,
the user ID and password are stored securely in the IBM App Connect Enterprise credentials store. For
more information about using this command, see command.

Chapter 4. Configuring IBM App Connect Enterprise 119

 4. Restart the integration node.
The properties that you set in the node.conf.yaml file take effect when the integration node is
started. If you modify these properties again, you must start the integration node again for the latest
changes to take effect. For more information, see “Starting and stopping an integration node” on page
247.

Verifying an integration node

Use the mqsilist command to display the status of integration nodes.

About this task

If you run the mqsilist command with no parameters, that command displays a one line summary for
every integration node in the current version of IBM App Connect Enterprise. For example:

mqsilist
...
BIP1325I: Integration node 'ACE01NODE' with administration URI 'http://localhost:4414' is
running.
BIP1326I: Integration node 'ACE02NODE' is stopped.
BIP8071I: Successful command completion.

You can request further details about all resources by specifying the parameter -d 2 on the command.
You can also specify the -r parameter so that the command recursively returns information about
integration servers, and the message flows and files that you have deployed to those integration servers.
You can also use this command to display a list of integration nodes that you have created for all
concurrent installations on this computer. For example, you might have installed both Version 10.0 and
Version 12.0 for assessment and migration. For example:

mqsilist -a
...
BIP1325I: Integration node 'ACE01NODE' with administration URI 'http://localhost:4414' is
running.
BIP1326I: Integration node 'ACE02NODE' is stopped.
BIP8221I: Broker: IB01NODE (Version 10.0) -
BIP8071I: Successful command completion.

Configuring integration nodes for high availability

If you want to operate your IBM App Connect Enterprise instances in a highly available configuration, you
can set up your integration nodes to work with IBM MQ multi-instance queue managers, a replicated data
queue manager (RDQM), the HTTP proxy servlet, an existing Windows Cluster (Windows Server), or a high
availability manager such as HACMP, HA/XD, or Veritas Cluster Server (VCS).

About this task

The following topics describe how to configure your integration node for high availability:
• “Configuring multi-instance integration nodes” on page 121
• “Configuring the HTTP proxy servlet” on page 149
• “Using an integration node with an RDQM configuration” on page 139
• “Using an integration node with an existing high availability manager” on page 130
• “Using an integration node with an existing Windows Cluster (Windows Server)” on page 138

High availability overview

An overview of the high availability configuration and topology options available in IBM App Connect
Enterprise.
In IBM App Connect Enterprise, you can create a high availability solution by using any of the following
methods:

120 IBM App Connect Enterprise 12.0: User Guide

Multi-instance integration nodes with IBM MQ
Use a multi-instance integration node so that the integration node is available in the same location
as the IBM MQ multi-instance queue manager in a high availability IBM MQ configuration. The multi-
instance integration node can either dynamically start in all locations where the multi-instance queue
manager runs, or can be set as an MQ Service dependency.
For more information, see “Configuring multi-instance integration nodes” on page 121.
An existing high availability manager
Use an external high availability manager by mounting the external resources to the shared file
system. Script files are provided for the common tasks that are required to create a multi-instance
integration node.
For more information, see “Using an integration node with an existing high availability manager” on
page 130.
An RDQM configuration
Configure an integration node to work with an IBM MQ replicated data queue manager (RDQM).
For more information, see “Using an integration node with an RDQM configuration” on page 139.
An existing Windows Cluster
Add an integration node to the nodes in a Windows Cluster.
For more information, see “Using an integration node with an existing Windows Cluster (Windows
Server)” on page 138.
The HTTP proxy servlet
Use the HTTP proxy servlet in a servlet container so that you can support high availability, load
distribution, access to the integration node from multiple IP addresses and ports, and a larger number
of concurrent HTTP sessions.
For more information, see HTTP proxy servlet overview.

Configuring multi-instance integration nodes

Use IBM MQ to configure an integration node to run in multi-instance mode for high availability.

Before you begin

• Review the topic Multi-instance queue managers in the IBM MQ product documentation to understand
the use of multi-instance queue managers.

About this task

The set of tasks that describe how to configure a multi-instance integration node assumes the following
criteria:
• A file server is configured to host both the shared work path directory for the multi-instance integration
node and the shared directories for the multi-instance queue manager.
• The file server is shared between two computers, each of which has a licensed copy of the IBM App
Connect Enterprise and IBM MQ products installed.
The steps apply to all operating systems that are supported by IBM App Connect Enterprise and IBM MQ.
To configure an integration node to run in multi-instance mode, complete the following steps.

Procedure
1. Create a shared path directory on an NFS or NAS server.
On Windows, you can use a shared UNC path. Follow the steps as described in the IBM MQ product
documentation; see Creating a shared file system.

Chapter 4. Configuring IBM App Connect Enterprise 121

 2. Create or configure the multi-instance queue manager. Follow the appropriate steps for your operating
system as described in the IBM MQ product documentation; see Create a multi-instance queue
manager.
3. Follow the steps to create the multi-instance integration node as described in “Creating a multi-
instance integration node” on page 122.

What to do next
After you have created a multi-instance integration node, you can also optionally complete the following
actions.
• Use the mqsilist command to view integration nodes, and which integration nodes are multi-instance.
• Delete a multi-instance integration node, as described in “Deleting a multi-instance integration node”
on page 125.
• Delete a multi-instance queue manager, as described in the IBM MQ product documentation, Deleting a
multi-instance queue manager.
• Verify shared file system locks, as described in the IBM MQ product documentation, Verifying shared file
system behavior.
• Back up, and later restore a multi-instance integration node, as described in “Backing up and restoring a
multi-instance integration node” on page 128
• Learn how to fail over multi-instance integration nodes, as described in “Failing over a multi-instance
integration node and queue manager” on page 129.

Creating a multi-instance integration node

If you specify a multi-instance queue manager for an integration node, you must configure that integration
node as multi-instance.

Before you begin

• Create the shared directories that you require for the multi-instance integration node, as described in
the topic Create a multi-instance queue manager in the IBM MQ product documentation. The examples
shown in this topic assume that you have created a shared directory called MQHA.
• Create the IBM MQ multi-instance queue manager. On Windows, the queue manager must be created
with the "-a" or "-ar" flag on crtmqm, specifying a domain group that IBM MQ can use for securing
shared files. If you have the choice, use the "-ar" flag. For more information, see Create a multi-
instance queue manager in the IBM MQ product documentation.

About this task

You can use two configurations for a multi-instance integration node:
• Configure the multi-instance integration node with explicit instances where the queue manager can run.
The multi-instance integration node runs in all the defined locations where the multi-instance queue
manager is available, and is inactive in locations where the queue manager is not running.
• Configure the multi-instance integration node as an MQ Service dependency. When a multi-instance
integration node depends on an MQ Service, whenever the multi-instance queue manager becomes
unavailable, the integration node stops. When the queue manager starts, the integration node is also
started on the same computer that the queue manager is running on.
To create a multi-instance integration node of either configuration, complete the following steps:

122 IBM App Connect Enterprise 12.0: User Guide

Procedure
1. On the computers that will run the instances of the integration node, configure the required users and
groups so that they will have access to the directory for the shared file system:
•
On Linux and UNIX, the uid and gid for the mqbrkrs group in /etc/password
must be the same on each server. For more information, see Create a multi-instance queue
manager in the IBM MQ product documentation.
•
On Windows, create the following users and groups:
a. A domain group that is a member of the local mqbrkrs group on both systems. For example,
ACE\Domain mqbrkrs.
b. A domain user that is a member of the Domain mqbrkrs and mqm groups. This ID is used for
running the integration node.
c. A domain user that is a member of the Domain mqbrkrs group and a member of the local
Administrators group on both machines. This ID is used for creating the integration node. You
can use the same ID for both creating and running the integration node, but you do not have
to be an Administrator to run the integration node. For example, WMB\mqsiuser-admin. The
listed user and groups are using the example domain name ACE.
2. Create a directory for the integration node shared files on the file server:
•
On Linux and UNIX systems, create a subdirectory (such as mqsi) on the shared drive
(MQHA); for example: /MQHA/mqsi. Ensure that this directory is owned by the mqbrkrs user and
group, and has the access permissions rwx. The UID of the integration node user ID in /etc/
passwd and the GID for mqbrkrs in /etc/group must be the same on each server.
•
On Windows, update the security permissions of the folder:
a. In Windows Explorer, right-click the shared directory that you created, and select Properties.
b. Click the Security tab, then click Advanced > Change Permissions...
c. Clear include inheritable permissions from this objects parent.
d. In the Permission entries window, select the entries for individual users and then click
Remove. Leave the entries for SYSTEM, Administrators, and CREATOR OWNER.
e. Add mqbrkrs with Full Control. If this folder is also being used for multi-instance queue
manager, then the domain group that is used to secure the queue manager must also be added
with Full Control set.
f. Add the global group domain mqm. Click Check Names, and then click OK. If this folder is also
being used for multi-instance queue manager, then the domain group that is used to secure the
queue manager must also be added with Full Control set.
g. Remove the default Everyone user from the list.
3. Open the command console or command prompt by running one of the following commands:
•
On Linux and UNIX systems, as a non-root user that is in the mqm and mqbrkrs
groups, open a command prompt, navigate to the bin directory of the installation, and run the
mqsiprofile command. For example:

. /opt/ibm/ace-11.0.0.n/server/bin/mqsiprofile

•
On Windows, as the user mqsiuser-admin, open a command prompt with elevated
privileges by using the mqsicommandconsole command; see command

Chapter 4. Configuring IBM App Connect Enterprise 123

 4. Create a multi-instance integration node on computer A, by running one of the following commands:
•
On Linux and UNIX systems:

mqsicreatebroker INODE -q QM1 -e /MQHA/mqsi

where INODE is the name of the integration node and the -e parameter specifies the name of the
shared directory created in step 2.
•
On Windows:

mqsicreatebroker INODE -i "WMB\mqsiuser" -a password -q QM1 -e \\MQHA\\mqsi -B "WMB\Domain

mqbrkrs"

where INODE is the name of the integration node, and password is the mqsiuser-admin password.
The -e parameter specifies the name of the shared directory that was created in step 2, and QM1 is
the name of the multi-instance queue manager that was created previously.
If you want to start the multi-instance integration node as an MQ Service dependency, specify -d as
defined on the mqsicreatebroker command. For more information, see command.
Note: You must be a member of the mqm group to run the mqsicreatebroker command with the -
d parameter.
You must ensure that the shared location exists, and that your user ID has access to the shared
location before you run this command.
5. Add the details of integration node INODE onto computer B as an instance of that integration node.
Use the mqsiaddbrokerinstance command, in the appropriate format for your operating system.
•
On Linux and UNIX:

mqsiaddbrokerinstance INODE -e /MQHA/mqsi

where the -e parameter specifies the name of the shared directory created in step 2.
•
On Windows:

mqsiaddbrokerinstance INODE -i "WMB\mqsiuser" -a password -e \\MQHA\\mqsi

where the -e parameter specifies the name of the shared directory created in step 2.
For more information, see command.
Repeat this step for every computer that the multi-instance queue manager runs on.
6. Start queue manager QM1 so that it is active on computer A.
See Starting and stopping a multi-instance queue manager in the IBM MQ product documentation.
7. Start integration node INODE on computer A.
Use the mqsistart command:

mqsistart INODE

8. Start integration node INODE on computer B.

You can observe that integration node INODE is running in standby mode against the standby queue
manager QM1 by running the command mqsilist.

124 IBM App Connect Enterprise 12.0: User Guide

9. Optional: Optional: test that the integration node works as follows:
a) Stop integration node INODE and queue manager QM1 on computer A.
Observe on computer B that integration node INODE and queue manager QM1 change from standby
to active mode.
b) Restart queue manager QM1 and integration node INODE on computer A.
Observe on computer A that queue manager QM1 and integration node INODE are in standby mode
and, on computer B, queue manager QM1 and integration node INODE remain in active mode.

Results
You have configured a multi-instance integration node, and created an instance of that integration node.
When integration node INODE and queue manager QM1 stop on computer A, the same integration node
and queue manager on computer B become active, and return to standby when computer A becomes
active again.
If you chose to define the multi-instance integration node as an MQ Service dependency, then the
integration node stops whenever the multi-instance queue manager becomes unavailable. The integration
node is started again when the queue manager starts.

Deleting a multi-instance integration node

Delete a multi-instance integration node without affecting the shared multi-instance configuration.

About this task

Important: The order of deletion of a multi-instance integration node and its associated instances affects
the shared configuration. Take care to use the correct command for each step in the process.
You must remove the integration node instances by using the mqsiremovebrokerinstance command
before you attempt to remove the integration node itself. This command removes all local references
to the integration node instance, but does not affect the shared configuration for the multi-instance
integration node on the shared work path. The mqsiremovebrokerinstance command cannot be
run against the standby integration node instance when it is running; stop the integration node instance
before you run this command.
If you unintentionally remove an integration node instance, it can be re-created by using the
mqsiaddbrokerinstance command, providing that the mqsideletebroker command was not
already used to delete the integration node.
If the multi-instance integration node was removed by using the mqsideletebroker command before
the associated integration node instances were removed, it will not be possible to start the integration
node instances. To recover from this situation, re-create the multi-instance integration node by using the
mqsicreatebroker command with the -e parameter, specifying the original shared work path location.
The following procedure gives an overview of how to delete a multi-instance integration node:

Procedure
1. Stop the multi-instance integration node on computer A.
2. Stop the integration node instance on computer B.
3. Remove the integration node instance on computer B.
Use the following command, where INODE represents the name of the integration node:

mqsiremovebrokerinstance INODE

For more information, see command.

Repeat this step for all integration node instances.

Chapter 4. Configuring IBM App Connect Enterprise 125

 4. Remove the multi-instance integration node on computer A.
Use the following command:

mqsideletebroker INODE

This process removes all references to the integration node on both the local and shared work paths.
For more information, see command.

Results
You have deleted the multi-instance integration node, and removed all of its instances.

Migrating an integration node to a multi-instance integration node

Migrate an integration node to a multi-instance integration node by moving the queue manager data to a
shared directory, and reconfiguring the integration node on two other servers.

Before you begin

Multi-instance integration nodes require a multi-instance queue manager. You must first check the
prerequisites for running a multi-instance queue manager, and migrate your queue manager if it is single-
instance. For more information, see Migrating from a single instance to a multi-instance queue manager in
the IBM MQ product documentation.
For the latest information about tested environments, see Testing statement for IBM MQ multi-instance
queue manager file systems. This support statement contains detailed version and prerequisite
information for each environment. A test tool is provided with IBM MQ to assist you in testing
unsupported environments.
You must provide three servers to run a multi-instance integration node, which provide the following
functions:
• A shared file system to store the integration node data and logs.
• Active instances of the integration node.
• Standby instances of the integration node
For more information, see Create a multi-instance queue manager in the IBM MQ product documentation.

Procedure
On the servers that will run the active and standby instances of the integration node, configure the
required users and groups so that they have access to a shared directory on the network file system.
1. On Windows, create the following users and groups:
a) A domain group that is a member of the local mqbrkrs group on both servers. For example, WMB
\Domain mqbrkrs
b) A domain group that is a member of the local mqm group on both servers. For example, WMB
\Domain mqm
c) A domain user that is a member of the domain mqbrkrs and mqm groups. This ID is used for
running the integration node. For example, WMB\mqsiuser
d) A domain user that is a member of the domain mqbrkrs group and a member of the local
administrators group on both machines. For example, WMB\mqsiuser-admin. This ID is used for
creating the integration node. It can be the same as the previous ID, but you do not have to run
the integration node as an administrator.
2. On UNIX and Linux, the uid and gid for mqbrkrs in /etc/password must be the same on
each server. For more information, see Creating a shared file system in the IBM MQ product
documentation.
Create a shared directory on the network file system with the correct access permissions. A typical
configuration consists of a single shared directory that contains all data for all integration nodes that use
the shared file system. Each integration node creates its own data directories under the shared directory.

126 IBM App Connect Enterprise 12.0: User Guide

 3. On Windows, create a directory on the file server for the files shared by the integration node, for
example, C:\mqsishare. Update the security permissions of the directory by completing the
following steps:
a) In Windows Explorer, right-click the shared directory that you have just created and select
Properties.
b) Click the Security tab, then click Advanced > Change Permissions...
c) Clear the "Include inheritable permissions from this object's parent" checkbox.
d) In the Permission entries window, select the entries for individual users and click Remove. Leave
the entries for SYSTEM, Administrators, and CREATOR OWNER.
e) Click Add..., and then enter the name of the global group domain mqm. Click Check Names and
click OK.
f) In the Permission Entry window, select the Allow checkbox for the Full Control entry.
g) Repeat the previous two steps for the global group domain mqbrkrs.
h) In the Properties window, click the Sharing tab and then click Advanced Sharing. Select the
Share this folder checkbox, and leave the share name as mqsishare. Click Permissions.
i) Click Add, and enter the name of the global group domain mqbrkrs. Click Check Names.
j) In the Group or user names panel, select the domain mqbrkrs. Select the Allow checkbox for
the Full Control entry, and then click Apply.
k) Repeat the previous two steps for the global group Administrators.
l) In the Group or user names panel, remove the group Everyone.
4. On Linux and UNIX, complete the following steps:
a) Create /HA/mqsi on the shared drive.
Ensure that /HA/mqsi is owned by the user and group mqbrkrs, and has the access permissions
rwx.
b) If you are using an NFS v4 file server, add the following line to the /etc/exports file:

/IBHA * rw,sync,no_wdelay,fsid=0)

Start the NFS daemon by using the following command:

/etc/init.d/nfs start

Copying the integration node data to the share is a manual procedure. Before you continue, ensure that
you have backed up your integration node. For more information, see “Backing up the integration node”
on page 477.
5. Stop the integration node.
Move the IBM App Connect Enterprise configuration directories.
6. On Windows, run the following commands:
a) mkdir \\<server_name>\mqsishare\mqsi\
where <server_name> is the name of your server.
b) xcopy /e /i /q /z C:\ProgramData\IBM\MQSI\components\<int_node_name> \
\<server_name>\mqsishare\mqsi\components\<int_node_name>
where <int_node_name> is the name of your integration node.
c) xcopy /e /i /q /z C:\ProgramData\IBM\MQSI\registry\<int_node_name> \
\<server_name>\mqsishare\mqsi\registry\<int_node_name>
d) rmdir C:\ProgramData\IBM\MQSI\components\<int_node_name> /q /s
e) rmdir C:\ProgramData\IBM\MQSI\registry\<int_node_name> /q /s

Chapter 4. Configuring IBM App Connect Enterprise 127

 7. On Linux and UNIX, run the following commands:
a) mkdir -p /HA/mqsi/components/
b) mkdir -p /HA/mqsi/registry/
c) mv /var/mqsi/components/<int_node_name>\ /HA/mqsi/components/
d) mv /var/mqsi/registry/<int_node_name>\ /HA/mqsi/registry/
Create a file called HASharedWorkPath that contains the location of the new shared directory and place
it with the integration nodes registry directory. The file must not contain any newline characters.
8. On Windows, run the following commands:
a) mkdir C:\ProgramData\IBM\MQSI\registry\<int_node_name>
b) <nul set /p =\\<server_name>\mqsishare\mqsi> C:\ProgramData\IBM\MQSI
\registry\<int_node_name>\HASharedWorkPath.dat
9. On Linux and UNIX, run the following commands:
a) mkdir /var/mqsi/registry/<int_node_name>
b) chmod 770 /var/mqsi/registry/<int_node_name>
c) echo –n /HA/mqsi> /var/mqsi/registry/<int_node_name>/HASharedWorkPath
On the standby server, add the standby instance using mqsiaddbrokerinstance. For more information,
see command.
10. Configure the standby integration node:
a) On Windows, run the following command: mqsiaddbrokerinstance <int_node_name> -i
<user_name> -a <password> -e \\<server_name>\mqsishare
b) On Linux and UNIX, run the following command: mqsiaddbrokerinstance <int_node_name>
-e /HA/
11. On the active server, run the following command: mqsistart <int_node_name>
12. On the standby server, run the following command: mqsistart <int_node_name>

Results
Your single-instance integration node has been converted to a multi-instance integration node. You can
verify this by using the mqsilist command. See command.

Backing up and restoring a multi-instance integration node

Back up the registry and configuration of the multi-instance integration node and its associated resources,
and re-create that integration node from the backup.

Before you begin

To ensure that the backup is complete and correct, back up the integration node when the integration
node is stopped, or when it is not processing a configuration change (such as a deployment or property
change).

About this task

When you back up a multi-instance integration node, you back up the registry and configuration from the
shared work path of the integration node and its associated instances. Therefore, the backup procedure
that is described in this topic applies to the multi-instance integration node only. No additional steps exist
for backing up the associated instances of the integration node.
When you restore a multi-instance integration node, you re-create associated instances by using the
mqsiaddbrokerinstance command.

128 IBM App Connect Enterprise 12.0: User Guide

Procedure
1. Back up a multi-instance integration node by using the mqsibackupbroker command.
For example:

mqsibackupbroker INODE -d /BackupDirectory/ACE

where:
• INODE is the name of the integration node.
• /BackupDirectory/ACE is the directory in which the backup file is created.
The command detects a multi-instance integration node and backs up the registry and configuration
from the shared work path of the integration node.
2. Restore a multi-instance integration node by using the mqsirestorebroker command.

mqsirestorebroker INODE -d /BackupDirectory/ACE -a 20091009.zip

where:
• INODE is the name of the integration node.
• /BackupDirectory/ACE is the directory in which the backup file is stored.
• 20091009.zip is the name of the backup (archive) file.
The command detects a multi-instance integration node and restores the registry and configuration to
the shared work path of the integration node.
3. Re-create associated instances of the multi-instance integration node by using the
mqsiaddbrokerinstance command.
For more information, see the command.

Failing over a multi-instance integration node and queue manager

An active integration node instance fails over when its associated active multi-instance queue manager
either terminates unexpectedly, or stops in a controlled manner. The action of stopping an active
integration node instance on an active multi-instance queue manager does not by itself cause a standby
integration node instance to become active.

About this task

The following examples list the 3 failover scenarios, and how to failover:

Procedure
• Controlled failover.
– Switch over to a standby instance by stopping an active queue manager with the endmqm command:

endmqm -s QueueManager

where QueueManager is the name of the queue manager that you are stopping. As the active
instance of the queue managers goes down, the standby instance starts.
• Immediate failover.
– Stop an active queue manager process with the kill command on Linux and UNIX, or end the
process with the Windows task manager on Windows:

kill -9 amqzxma0 ProcessID

where ProcessID is the process ID of the amqzxma0 process that you need to kill. The standby
instance of the queue manager becomes active.

Chapter 4. Configuring IBM App Connect Enterprise 129

 • Shutting down the server.
– Restart the server that the active instance of the queue manager is running on. The standby instance
of the queue manager becomes active.

Results
If the multi-instance integration node was configured as dependent on an MQ Service, when the multi-
instance queue manager restarts, the integration node instance will also start on the computer on which
the queue manager is running. Otherwise, the integration node that is in standby node becomes active.

Using an integration node with an existing high availability manager

You can use IBM App Connect Enterprise with an existing high availability manager, for example HACMP,
HA/XD, Veritas Cluster Server (VCS), or HP-UX Serviceguard.

About this task

The provision of multi-instance nodes facilitates the configuration of IBM App Connect Enterprise with a
high availability (HA) manager.
This topic summarizes how to complete the following tasks:
1. Create an integration node.
2. Add an integration node instance.
3. Start an integration node.
4. Stop an integration node.
5. Monitor an integration node.
6. Delete an integration node.

Procedure
1. To create an integration node, mount the shared resource onto your primary node and use the
following mqsicreatebroker command with the -e parameter to specify your shared resource
location.

mqsicreatebroker INODE -e /MQHA/MyIntNode/

where:
• INODE is the name of the integration node.
• /MQHA/INODE/ is the directory for your shared resource.
2. To add another integration node instance, mount the shared resource onto your secondary nodes and
use the following mqsiaddbrokerinstance command.

mqsiaddbrokerinstance INODE -e /MQHA/MyIntNode/

where:
• INODE is the name of the integration node.
• /MQHA/INODE/ is the directory for your shared resource.
3. To start an integration node, you can use one of the following script files:
hamqsi_start_broker

#!/bin/ksh
# Module:
# hamqsi_start_broker
#
# Args:
# BROKER = name of integration node to start
#

130 IBM App Connect Enterprise 12.0: User Guide

# Description:
# This script attempts to start the MQSI integration node
#
# Runs as the userid which runs integration node, and must have
# the user's environment (i.e. invoke from "su - $MQUSER ..")
#

BROKER=$1

if [ -z "$BROKER" ]
then
echo "hamqsi_start_broker: ERROR! No integration node name supplied"
echo " Usage: hamqsi_start_broker <BROKER>"
exit 1
fi

# Ensure that the integration node is not already running. In this test
# we look for any integration node-related processes, which might have
# been left around after a previous failure. Any that remain
# must now be terminated. This is a severe method of cleaning
# up integration node processes.
# We stop the processes in the following order:
# bipservice - first so it cannot issue restarts
# bipbroker - next for same reason
# biphttplistener
# bipMQTT
# startDataFlowEngine
# DataFlowEngine - last
#
echo "hamqsi_start_broker: Ensure $BROKER not already running"
for process in bipservice bipbroker biphttplistener startDataFlowEngine DataFlowEngine
do
# Output of kill redirected to /dev/null in case no processes
ps -ef | grep "$process $BROKER" | grep -v grep | \
awk '{print $2}'| xargs kill -9 > /dev/null 2>&1
done

# Start the integration node

echo "hamqsi_start_broker: Start integration node " $BROKER
mqsistart $BROKER > /dev/null 2>&1
if [ $? -ne "0" ]
then
echo "hamqsi_start_broker: Bad result from mqsistart for $BROKER"
exit 1
fi

# Check to see if the integration node service has started. This loop
# uses a fixed online timeout of approx. 10 seconds.
TIMED_OUT=yes
i=0
while [ $i -lt 10 ]
do
# Check for integration node start. We look for bipservice and
# bipbroker to be running; there might be no message flows
# deployed.
# Look to see whether bipservice is running
cnt=`ps -ef | grep "bipservice $BROKER" | grep -v grep | wc -l`
if [ $cnt -gt 0 ]
then
# Look to see whether bipbroker is running
cnt=`ps -ef | grep "bipbroker $BROKER" | grep -v grep | wc -l`
if [ $cnt -gt 0 ]
then
# Integration node is online
echo "hamqsi_start_broker: ${BROKER} is running"
TIMED_OUT=no
break # out of timing loop
fi
fi
# Manage the loop counter
i=`expr $i + 1`
sleep 1
done

# Report error if integration node failed to start in time

if [ ${TIMED_OUT} = "yes" ]
then
echo "hamqsi_start_broker: Integration node service failed to start: " $BROKER
exit 1
fi

Chapter 4. Configuring IBM App Connect Enterprise 131

 exit 0

hamqsi_start_broker_as

#
#!/bin/ksh
# Module:
# hamqsi_start_broker_as
#
# Args:
# integration node = integration node name
# qm = name of integration node queue manager
# mquser = user account under which QM and Integration node are run
#
# Description:
# Starting an MQSI integration node requires the following services:
# (1) The MQSeries Queue Manager which supports the integration node
# (2) The MQSI integration node service
# This script provides a single source to initiate the required
# services in sequence.
#
# Queue Manager:
# This script uses the strmqm script supplied by MQSeries V7
#
# Integration node:
# This script then invokes the hamqsi_start_broker script which
# checks that the integration node is fully stopped and then starts it.
#
# The hamqsi_start_broker_as script should be run as root.

# Check running as root

if [ `id -u` -ne 0 ]
then
echo "Must be running as root"
exit 1
fi

BROKER=$1
QM=$2
MQUSER=$3

# Check all parameters exist

if [ -z "$BROKER" ]
then
echo "hamqsi_start_broker_as: ERROR! No integration node name supplied"
echo " Usage: hamqsi_start_broker_as <BROKER> <QM> <MQUSER>"
exit 1
fi

if [ -z "$QM" ]
then
echo "hamqsi_start_broker_as: ERROR! No queue manager name supplied"
echo " Usage: hamqsi_start_broker_as <BROKER> <QM> <MQUSER>"
exit 1
fi

if [ -z "$MQUSER" ]
then
echo "hamqsi_start_broker_as: ERROR! No Userid supplied"
echo " Usage: hamqsi_start_broker_as <BROKER> <QM> <MQUSER>"
exit 1
fi

# -------------------------------------------------------------------
# Start the Queue Manager
#
echo "hamqsi_start_broker_as: Start Queue manager " $QM
su $MQUSER -c "/opt/mqm/bin/strmqm $QM"
rc=$?
if [ $rc -ne 0 ]
then
echo "hamqsi_start_broker_as: Could not start the queue manager"
exit $rc
fi

# -------------------------------------------------------------------

132 IBM App Connect Enterprise 12.0: User Guide

 # Start the Integration node
#
# Ensure that the integration node is not already running and start the Integration node
su - $MQUSER -c "/MQHA/bin/hamqsi_start_broker $BROKER"
rc=$?
if [ $rc -ne 0 ]
then
echo "hamqsi_start_broker_as: Could not start the integration node"
exit $rc
fi

exit $rc

4. To stop an integration node, you can use one of the following script files:
hamqsi_stop_broker

#!/bin/ksh
# Module:
# hamqsi_stop_broker
#
# Args:
# integration node = name of integration node
# timeout = max time to allow for each phase of termination
#
# Description:
# This script stops the integration node, forcibly if necessary.
# The script should be run by the user account under which
# the integration node is run, including environment.

BROKER=$1
TIMEOUT=$2

if [ -z "$BROKER" ]
then
echo "hamqsi_stop_broker: ERROR! No integration node name supplied"
echo " Usage: hamqsi_stop_broker <BROKER> <TIMEOUT>"
exit 1
fi

if [ -z "$TIMEOUT" ]
then
echo "hamqsi_stop_broker: ERROR! No timeout supplied"
echo " Usage: hamqsi_stop_broker <BROKER> <TIMEOUT>"
exit 1
fi

for severity in normal immediate terminate

do
# Issue the stop method in the background - we don't
# want to risk having it hang us up, indefinitely. We
# want to be able to concurrently run a TIMEOUT timer
# to give up on the attempt, and try a more forceful
# stop. If the kill version fails then there is nothing
# more we can do here anyway.

echo "hamqsi_stop_broker: Attempting ${severity} stop of ${BROKER}"

case $severity in

normal)
# Minimum severity of stop is to issue mqsistop
mqsistop $BROKER > /dev/null 2>&1 &
;;

immediate)
# This is an immediate stop.
mqsistop $BROKER -i > /dev/null 2>&1 &
;;

terminate)
# This is a severe method of cleaning up integration node processes.
# We stop the processes in the following order:
# bipservice - first so it cannot issue restarts
# bipbroker - next for same reason
# biphttplistener
# bipMQTT
# startDataFlowEngine
# DataFlowEngine - last
for process in bipservice bipbroker biphttplistener startDataFlowEngine DataFlowEngine
do
# Output of kill redirected to /dev/null in case no processes

Chapter 4. Configuring IBM App Connect Enterprise 133

 ps -ef | grep "$process $BROKER" | grep -v grep | \
awk '{print $2}'| xargs kill -9 > /dev/null 2>&1
done
;;

esac

echo "hamqsi_stop_broker: Waiting for ${severity} stop of ${BROKER} to complete"

TIMED_OUT=yes
SECONDS=0
while (( $SECONDS < ${TIMEOUT} ))
do
# See whether there are any integration node processes still running
cnt=`ps -ef | \
grep -E "bipservice $BROKER|bipbroker $BROKER|startDataFlowEngine $BROKER|
DataFlowEngine $BROKER|biphttplistener $BROKER" | \
grep -v grep | wc -l`
if [ $cnt -gt 0 ]
then
# It's still running...wait for timeout
sleep 1 # loop granularity
else
# It's stopped, as desired
echo "${BROKER} has stopped"
TIMED_OUT=no
break # out of while ..offline timeout loop
fi
done # timeout loop

if [ ${TIMED_OUT} = "yes" ]
then
continue # to next level of urgency
else
break # instance is stopped, job is done
fi

done # next level of urgency

if [ ${TIMED_OUT} = "no" ]
then
echo "hamqsi_stop_broker: Completed"
exit 0
else
echo "hamqsi_stop_broker: Completed with errors"
exit 1
fi

hamqsi_stop_broker_as

#!/bin/ksh
# Module:
# hamqsi_stop_broker_as
#
# Arguments are:
# integration node = name of integration node
# qm = name of integration node queue manager
# mquser = user account under which QM and integration node run
# timeout = max time to allow each phase of stop processing
#
# Description:
# This script stops the integration node, Queue Manager in that sequence.
#
# Integration node:
# The script invokes the hamqsi_stop_broker script to stop the
# integration node, which checks that the integration node is fully stopped.
#
# Queue Manager:
# This script uses the strmqm script supplied by MQSeries V7
#
# The hamqsi_stop_broker_as script should be run as root.

# Check running as root

if [ `id -u` -ne 0 ]
then
echo "Must be running as root"
exit 1
fi

134 IBM App Connect Enterprise 12.0: User Guide

 BROKER=$1
QM=$2
MQUSER=$3
TIMEOUT=$4

# Check all parameters

if [ -z "$BROKER" ]
then
echo "hamqsi_stop_broker_as: ERROR! No Integration node name supplied"
echo " Usage: hamqsi_stop_broker_as <BROKER> <QM> <MQUSER> <TIMEOUT>"
exit 1
fi

if [ -z "$QM" ]
then
echo "hamqsi_stop_broker_as: ERROR! No queue manager name supplied"
echo " Usage: hamqsi_stop_broker_as <BROKER> <QM> <MQUSER> <TIMEOUT>"
exit 1
fi

if [ -z "$MQUSER" ]
then
echo "hamqsi_stop_broker_as: ERROR! No userid supplied"
echo " Usage: hamqsi_stop_broker_as <BROKER> <QM> <MQUSER> <TIMEOUT>"
exit 1
fi

if [ -z "$TIMEOUT" ]
then
echo "hamsi_stop_broker_as: ERROR! No Timeout value supplied"
echo " Usage: hamqsi_stop_broker_as <BROKER> <QM> <MQUSER> <TIMEOUT>"
exit 1
fi

METHOD_STATUS="OK"

# -------------------------------------------------------------------
# Stop the integration node
#
echo "hamqsi_stop_broker_as: Stop integration node " $BROKER
su - $MQUSER -c "/MQHA/bin/hamqsi_stop_broker $BROKER $TIMEOUT"
if [ $? -ne "0" ]
then
# Even if the above operation failed, just report and then continue by
# stopping other components
echo "hamqsi_stop_broker_as: Attempt to stop integration node $BROKER failed"
METHOD_STATUS="Error"
fi

# -------------------------------------------------------------------
# Stop the Queue Manager, using script from MQ V7
#
echo "hamqsi_stop_broker_as: Stop Queue Manager $QM"
su $MQUSER -c "/opt/mqm/bin/endmqm -i $QM"
if [ $? -ne "0" ]
then
# Even if the above operation failed, just report and then continue by
# stopping other components
echo "hamqsi_stop_broker_as: Attempt to stop queue manager $QM failed"
METHOD_STATUS="Error"
fi

if [ ${METHOD_STATUS} = "OK" ]
then
exit 0
else
echo "hamqsi_stop_broker_as: Completed with errors"
exit 1
fi

5. To monitor an integration node, you can use the following script file that checks only for the existence
of the main integration node processes and provides a successful return code if they are found:
hamqsi_monitor_broker_as

#!/bin/ksh
# Module:
# hamqsi_monitor_broker_as

Chapter 4. Configuring IBM App Connect Enterprise 135

 #
# Args:
# BROKER = name of integration node in AppServer
# QM = name of queue manager in AppServer
# MQUSER = userid under which queue manager and integration node run
#
# Description:
# This is the application monitor script used with HACMP/ES. It
# needs to be invoked by a parameter-less wrapper script because
# HACMP does not allow parameters to be passed to application
# monitor scripts.
#
# This hamqsi_monitor_broker_as script is run as root, and uses
# su as needed to monitor the 3 components of the application server.
#
# This script is tolerant of a queue manager that is still in
# startup. If the queue manager is still starting this application
# monitor script will exit with 0 - which indicates
# to HACMP that there's nothing wrong. This is to allow for
# startup time for the queue manager which might exceed the
# Stabilisation Interval set for the Application Monitor in HACMP/ES.
#
#
# Exit codes:
# 0 => Integration node & QM are all running OK or starting
# >0 => One or more components are not responding.
#

# Check running as root

if [ `id -u` -ne 0 ]
then
echo "Must be running as root"
exit 1
fi

BROKER=$1
QM=$2
MQUSER=$3

# Check the parameters

if [ -z "$BROKER" ]
then
echo "hamqsi_monitor_broker_as: ERROR! No integration node name supplied"
exit 1
fi

if [ -z "$QM" ]
then
echo "hamqsi_monitor_broker_as: ERROR! No queue manager name supplied"
exit 1
fi

if [ -z "$MQUSER" ]
then
echo "hamqsi_monitor_broker_as: ERROR! No mquser supplied"
exit 1
fi

# Use a state variable to reflect the state of components as they

# are tested. Valid values are "stopped", "starting" and "started"
# Initialise it to "stopped" for safety.
STATE="stopped"

# ------------------------------------------------------------------
# Check that the queue manager is running or starting.
#
su - $MQUSER -c "echo 'ping qmgr' | runmqsc ${QM}" > /dev/null 2>&1
pingresult=$?
# pingresult will be 0 on success; non-zero on error (man runmqsc)
if [ $pingresult -eq 0 ]
then
# ping succeeded
echo "hamqsi_monitor_broker_as: Queue Manager ${QM} is responsive"
STATE="started"
else
# ping failed
# Don't condemn the QM immediately, it might be in startup.
# The following regexp includes a space and a tab, so use tab-friendly
# editors.
srchstr=" $QM[ ]*$"
cnt=`ps -ef | grep strmqm | grep "$srchstr" | grep -v grep \

136 IBM App Connect Enterprise 12.0: User Guide

 | awk '{print $2}' | wc -l`
if [ $cnt -gt 0 ]
then
# It appears that QM is still starting up, tolerate
echo "hamqsi_monitor_broker_as: Queue Manager ${QM} is starting"
STATE="starting"
else
# There is no sign of QM start process
echo "hamqsi_monitor_broker_as: Queue Manager ${QM} is not responsive"
STATE="stopped"
fi
fi

# Decide whether to continue or to exit

case $STATE in
stopped)
echo "hamqsi_monitor_broker_as: Queue manager ($QM) is not running correctly"
exit 1
;;
starting)
echo "hamqsi_monitor_broker_as: Queue manager ($QM) is starting"
echo "hamqsi_monitor_broker_as: WARNING - Stabilisation Interval might be too short"
echo "hamqsi_monitor_broker_as: WARNING - No test of integration node $BROKER will be
conducted"
exit 0
;;
started)
echo "hamqsi_monitor_broker_as: Queue manager ($QM) is running"
continue
;;
esac

# ------------------------------------------------------------------
# Check the MQSI integration node is running
#
# Re-initialise STATE for safety
STATE="stopped"
#
# The integration node runs as a process called bipservice which is responsible
# for starting and re-starting the admin agent process (bipbroker).
# The bipbroker is responsible for starting any DataFlowEngines. The
# bipbroker starts the DataFlowEngines using the wrapper script
# startDataFlowEngine. If no integration servers have been assigned to
# the integration node there will be no DataFlowEngine processes. There should
# always be a bipservice and bipbroker process pair. This monitor
# script only tests for bipservice, because bipservice should restart
# bipbroker if necessary - the monitor script should not attempt to
# restart bipbroker and it might be premature to report an absence
# of a bipbroker as a failure.
#
cnt=`ps -ef | grep "bipservice $BROKER" | grep -v grep | wc -l`
if [ $cnt -eq 0 ]
then
echo "hamqsi_monitor_broker_as: MQSI integration node $BROKER is not running"
STATE="stopped"
else
echo "hamqsi_monitor_broker_as: MQSI integration node $BROKER is running"
STATE="started"
fi

# Decide how to exit

case $STATE in
stopped)
echo "hamqsi_monitor_broker_as: Integration node ($BROKER) is not running correctly"
exit 1
;;
started)
echo "hamqsi_monitor_broker_as: Integration node ($BROKER) is running"
exit 0
;;
esac

If you require more information than that supplied by the preceding example, you can code your
monitor to do the following actions:
• Subscribe to IBM App Connect Enterprise accounting and statistics, and analyze the results.
• Put a dummy message through the integration node and analyze the results.

Chapter 4. Configuring IBM App Connect Enterprise 137

 6. Before you delete the integration node on the primary node, you must delete any integration nodes on
the standby nodes. For more information, see “Deleting an integration node” on page 165.

Using an integration node with an existing Windows Cluster (Windows

Server)
You can use IBM App Connect Enterprise with the existing high availability manager for Windows Server
(Failover Cluster Manager).

About this task

For more information about the versions of Windows Server that are supported by IBM App Connect
Enterprise, see the IBM App Connect Enterprise system requirements web page.
This topic summarizes how to complete the following tasks:
1. Complete the prerequisite setup.
2. Configure a local group.
3. Create an integration node.
4. Add integration node instances to the additional nodes.
5. Add the integration node service to the cluster configuration
6. Start and stop an integration node.
7. Delete an integration node.

Procedure
1. To complete the prerequisite setup, complete the following steps:
a) Validate your Failover Cluster Manager configuration.
b) Complete all of the steps documented in 'Supporting the Microsoft Cluster Service' of the IBM MQ
documentation to create a cluster configuration that contains the queue manager on which you
want the integration node to run.
c) Note the haregtyp.exe command as a prerequisite for creating IBM MQ resources in the cluster.
2. To configure a local group, ensure that the domain user under which you want the integration node to
run exists in the local mqbrkrs group on all nodes on which you want the integration node to run.
3. To create an integration node, use the following mqsicreatebroker command on the node on which
your cluster is currently running.

mqsicreatebroker INODE -q MQ1 -e E:\ACE\Workspace

where:
• INODE is the name of the integration node.
• MQ1 is the name of the queue manager.
• E:\ACE\Workspace is the directory of a shared disk (nonquorum) in your cluster configuration.
4. To add this integration node instance to the other nodes in your cluster, switch your cluster to each
node in turn. When a node is active, use the following mqsiaddbrokerinstance command.

mqsiaddbrokerinstance INODE -e E:\ACE\Workspace

where:
• INODE is the name of the integration node.
• E:\ACE\Workspace is the directory of a shared disk (nonquorum) in your cluster configuration.

138 IBM App Connect Enterprise 12.0: User Guide

5. To add an integration node generic service resource to the cluster which contains the integration node
queue manager, complete the following steps:
a) Select the IBM App Connect Enterprise component integration_node service when asked. All
other settings can be left unchanged.
b) Add a dependency on the IBM MQ resource, to ensure that the queue manager is started before the
integration node.
6. To start and stop the integration node resource, use Failover Cluster Manager.
7. To delete an integration node resource from the Failover Cluster Manager, take the following steps:
a) Delete the integration node generic service from the cluster configuration.
b) Use the mqsiremovebrokerinstance command on all nodes but one, moving the cluster
between nodes before running each command.
c) On the final node, use the mqsideletebroker command to completely remove the integration
node configuration.

Results
For further information about configuring IBM MQ with a high availability manager for Windows Server,
see the IBM MQ product documentation online.
See the following topics:
• Introducing MSCS clusters
• Supporting the Microsoft Cluster Service (MSCS)
• Setting up IBM MQ for MSCS clustering

Using an integration node with an RDQM configuration

You can use IBM App Connect Enterprise with an IBM MQ replicated data queue manager (RDQM), to
provide a high availability (HA) solution.

About this task

An RDQM configuration consists of three servers configured in a high availability (HA) group, each with
an instance of the queue manager. One instance is the running queue manager, which synchronously
replicates its data to the other two instances. If the server running this queue manager fails, another
instance of the queue manager starts and has current data to work with. The three instances of the queue
manager share a floating IP address, so clients need to be configured with only a single IP address. Only
one instance of the queue manager can run at any one time, even if the HA group becomes partitioned
due to network problems. The server running the queue manager is known as the primary, and each of the
other two servers is known as a secondary.
For more information about RDQM, see the IBM MQ product documentation online.
You can configure an integration node to work with an RDQM high availability solution, by completing the
following steps:

Procedure
1. Install IBM App Connect Enterprise on all hosts that are part of the RDQM cluster.
2. On all hosts, add the mqm user ID and your login user ID to the mqbrkrs group.
3. Restart the queue manager to ensure that it gains the mqbrkrs group membership.
4. Create a directory in the queue manager vols directory for the integration node, as shown in the
following example:

# mkdir /var/mqm/vols/ha1/userdata/ace
# chown mqm:mqbrkrs /var/mqm/vols/ha1/userdata/ace

Chapter 4. Configuring IBM App Connect Enterprise 139

 # chmod 775 /var/mqm/vols/ha1/userdata/ace

5. Use the mqsicreatebroker command to create an integration node called ACEHA1, set the new
data directory, and specify that the integration node is to be started and stopped as an MQ service
when the queue manager starts and stops:

# mqsicreatebroker -e /var/mqm/vols/ha1/userdata/ace -d defined -q HA1 ACE1HA1

6. Configure the integration node by editing its node.conf.yaml configuration file:

# vi /var/mqm/vols/ha1/userdata/ace/mqsi/components/ACEHA1/node.conf.yaml

If your system has a limited amount of memory, consider reducing the amount of memory required
by IBM App Connect Enterprise by setting the startListener property in the NodeHttpListener
section to false to turn off the biphttplistener process:

NodeHttpListener:
startListener: false

7. Start the integration node by running the mqsistart command:

# mqsistart ACEHA1

8. Verify that the integration node is running by using the mqsilist command:

# mqsilist

A response similar to the following message confirms that the integration node is running:

BIP1376I: Integration node 'ACEHA1' is an active multi-instance or High Availability

integration node that is running on queue manager 'HA1'.
The administration URI is 'http://admin.myloc.company.com:4414'
BIP8071I: Successful command completion.

If the integration node does not start, check for FDC files in the /var/mqm/errors directory and the
contents on the queue manager error log. Also check the contents of the service log file:

/var/mqsi/common/log/ACEHA1.mqservice.log

9. Create an integration server on integration node ACEHA1:

# mqsicreateexecutiongroup -e default ACEHA1

10. Create the instances on the other nodes by using the mqsiaddbrokerinstance command. This
command cannot be run unless the /var/mqm/vols/ha1 filesystem exists, so you must fail over
to each node in turn by using the IBM MQ rdqmadm command and then add the broker instance by
using the mqsiaddbrokerinstance command.
For each node, complete the following steps:
a) Run the IBM MQ command rdqmadm, specifying the name of the queue manager (for example,
HA1):

# rdqmadm -p -m HA1

b) Run the IBM App Connect Enterprise command mqsiaddbrokerinstance, specifying the
integration node name (for example, ACEHA1) and the filesystem to be used:

# mqsiaddbrokerinstance ACEHA1 -e /var/mqm/vols/ha1/userdata/ace

11. You have now configured an RDQM solution.

140 IBM App Connect Enterprise 12.0: User Guide

HTTP proxy servlet overview
By using the HTTP proxy servlet in a servlet container, you can support high availability, load distribution,
access to the integration node from multiple IP addresses and ports, and a larger number of concurrent
HTTP sessions.
The HTTP proxy servlet is a Java servlet that you can use in a servlet container, such as WebSphere
Application Server Liberty Profile or Apache Tomcat, or in an application server such as IBM WebSphere
Application Server. The HTTP proxy servlet receives HTTP requests from web services client applications
and replaces the support that is provided by the integration node and embedded (integration server)
HTTP listeners.
The HTTP proxy servlet supports SSL (HTTPS) secure protocol when it is deployed in a servlet container
that is configured to support SSL.
If you are deploying a web browser-based JavaScript application that uses the JavaScript client API to
call an IBM App Connect Enterprise integration service, then you must deploy the proxy servlet on the
same web application server as your JavaScript application. For more information about the JavaScript
client API, see “Integration service JavaScript client API ” on page 1995.
You cannot use the HTTP proxy servlet if you configure your integration node environment to use multi-
instance IBM MQ queue managers, because the HTTP proxy servlet cannot connect to the standby queue
manager when it becomes active.
For a detailed description of the HTTP proxy servlet, see “HTTP proxy servlet operation” on page 141.
Before you install and test the HTTP proxy servlet, ensure that you understand the following concepts:
• “Working with HTTP flows” on page 792
• “HTTP listeners” on page 795
• “HTTP proxy servlet operation” on page 141
• “Importance of the context root when you configure the HTTP proxy servlet” on page 147
When you have gained an understanding of the HTTP proxy servlet concepts, read the following topics to
help you configure, install, and test the HTTP proxy servlet:
• “Configuring the HTTP proxy servlet” on page 149
• “Deploying the HTTP proxy servlet on a servlet container” on page 159
• “Testing the HTTP proxy servlet” on page 164

HTTP proxy servlet operation

Before you deploy the HTTP proxy servlet, ensure that you understand how the HTTP proxy servlet
manages the communication between IBM App Connect Enterprise applications and web services clients
in a number of supported configurations.
The HTTP proxy servlet is a Java Web Application Archive (.war) file that is part of the runtime
environment, and can be found in the following directory:
install_dir/tools
where install_dir is the name of your App Connect Enterprise runtime installation directory.
The HTTP proxy servlet is a Java servlet that receives HTTP requests. The HTTP proxy servlet matches
the received web address with the web address that the HTTP or SOAP input nodes are monitoring, then
passes the HTTP request message to the correct HTTP or SOAP input node flow by using IBM MQ.
The HTTP proxy servlet receives response messages from the HTTP or SOAP reply nodes and sends them
back to the client applications over HTTP or HTTPS. The integration node has several internal IBM MQ
queues (SYSTEM.BROKER.WS.* queues), which are used for the communication between the HTTP proxy
servlet and the HTTP or SOAP input and reply nodes.
The HTTP proxy servlet is deployed in a servlet container. A servlet container (or web container) is the
runtime environment for servlets and Java Server Pages (JSP). Apache Tomcat is an example of a servlet
container. WebSphere Application Server is an example of an application server, which includes the

Chapter 4. Configuring IBM App Connect Enterprise 141

 functions of a servlet container. The HTTP proxy servlet can be deployed in a local servlet container that
is running on the same machine as IBM App Connect Enterprise or on a remote servlet container that is
running on a different machine to IBM App Connect Enterprise. The servlet container must allow the HTTP
proxy servlet to configure and call the IBM MQ classes for Java.
After the HTTP proxy servlet is deployed and running on the servlet container, it uses the HTTP listener
of the servlet container to receive HTTP requests. If the servlet container is configured to support SSL
(HTTPS), web services requests are received by the message flows by using SSL.
The following topics describe some common scenarios that are based on typical IBM App Connect
Enterprise deployments, and the HTTP proxy servlet configuration parameters that are required:
• The HTTP proxy servlet is on the same machine as IBM App Connect Enterprise
• The HTTP proxy servlet is on a different machine to IBM App Connect Enterprise
• The HTTP proxy servlet is on a machine with its own queue manager
• The HTTP proxy servlet is deployed in an environment with a network local-balancer

HTTP proxy servlet is deployed to a servlet container on the same machine as IBM App Connect Enterprise
You can configure the HTTP proxy servlet for a deployment where the HTTP proxy servlet is deployed to a
servlet container on the same machine as IBM App Connect Enterprise.
In the following figure, the HTTP proxy servlet is running on the same machine as the integration node.
The HTTP proxy servlet connects to the integration node queue manager by using bindings mode (local
connection).

In this configuration example, you must configure the following HTTP proxy servlet configuration
parameters. For information about configuring the HTTP proxy servlet, see “Configuring the HTTP proxy
servlet” on page 149.
• Set useClientMode to false.
• Set useQueueManagerDataInsteadOfConfigFile to "".
• Set configFile to the location of the configuration file, for example, C:\ProgramData\IBM\MQSI
\components\my_node\config\wsplugin6.conf.

142 IBM App Connect Enterprise 12.0: User Guide

where my_node is the name of your integration node.
Before you configure, deploy, and test the HTTP proxy servlet, ensure that you understand the following
concepts:
• “Working with HTTP flows” on page 792
• “HTTP listeners” on page 795
• “HTTP proxy servlet operation” on page 141
• “Importance of the context root when you configure the HTTP proxy servlet” on page 147
When you have gained an understanding of the HTTP proxy servlet concepts, read the following topics to
help you configure, deploy, and test the HTTP proxy servlet:
• “Configuring the HTTP proxy servlet” on page 149
• “Deploying the HTTP proxy servlet on a servlet container” on page 159
• “Testing the HTTP proxy servlet” on page 164

HTTP proxy servlet is deployed to a servlet container that is on a different machine to IBM App Connect
Enterprise
You can configure the HTTP proxy servlet for a deployment where the HTTP proxy servlet is deployed to a
servlet container on a different machine to IBM App Connect Enterprise, with an IBM MQ client link to the
integration node queue manager.
In the following figure, the HTTP proxy servlet is running on a remote machine to the integration node.
The HTTP proxy servlet connects to the integration node queue manager by using an IBM MQ client
connection, the HTTP proxy servlet can be configured to access HTTP or SOAP nodes, and the HTTP or
SOAP node configuration is retrieved from the SYSTEM.BROKER.WS.ACK queue.

In this configuration example, you must configure the following HTTP proxy servlet configuration
parameters. For information about configuring the HTTP proxy servlet, see “Configuring the HTTP proxy
servlet” on page 149.
• Set useClientMode to true.

Chapter 4. Configuring IBM App Connect Enterprise 143

 • Set useQueueManagerDataInsteadOfConfigFile to * or the integration node queue manager
name.
• Set clientModeHostname, clientModeChannelName, and clientModePortNumber to the correct
values as detailed in “HTTP proxy servlet configuration parameters” on page 151.
The HTTP proxy servlet attempts to connect to the remote queue manager for the integration node by
reading the required configuration data from the IBM MQ client connection. For the client connection to
succeed, you must start the SYSTEM.DEFAULT.LISTENER.TCP listener in the queue manager. For more
information, search for START LISTENER in the IBM MQ product documentation.
Before you configure, deploy, and test the HTTP proxy servlet, ensure that you understand the following
concepts:
• “Working with HTTP flows” on page 792
• “HTTP listeners” on page 795
• “HTTP proxy servlet operation” on page 141
• “Importance of the context root when you configure the HTTP proxy servlet” on page 147
When you have gained an understanding of the HTTP proxy servlet concepts, read the following topics to
help you configure, deploy, and test the HTTP proxy servlet:
• “Configuring the HTTP proxy servlet” on page 149
• “Deploying the HTTP proxy servlet on a servlet container” on page 159
• “Testing the HTTP proxy servlet” on page 164

HTTP proxy servlet is deployed to a servlet container on a machine with its own queue manager
You can configure the HTTP proxy servlet for a deployment where the HTTP proxy servlet is deployed to
a servlet container that is on a machine with its own queue manager and an IBM MQ channel link to the
integration node queue manager.

In this configuration example, you must configure the following HTTP proxy servlet configuration
parameters. For information about configuring the HTTP proxy servlet, see “Configuring the HTTP proxy
servlet” on page 149.
• Set useClusterMode to true.
• Set clusterModeQueueManagerName to the queue manager of the Web servlet container.
• Set clusterModeReplyToQ to a queue that exists on that queue manager.
The HTTP proxy servlet attempts to open the queue SYSTEM.BROKER.WS.INPUT on the specified queue
manager by using the queue manager name from the configuration file. Therefore, you must set up
channels and transmit queues beforehand to ensure that the messages arrive on the queue manager of
the integration node.
You must copy the configuration files from the integration node machine in this scenario.
Before you configure, deploy, and test the HTTP proxy servlet, ensure that you understand the following
concepts:
• “Working with HTTP flows” on page 792
• “HTTP listeners” on page 795
• “HTTP proxy servlet operation” on page 141
• “Importance of the context root when you configure the HTTP proxy servlet” on page 147
When you have gained an understanding of the HTTP proxy servlet concepts, read the following topics to
help you configure, deploy, and test the HTTP proxy servlet:
• “Configuring the HTTP proxy servlet” on page 149
• “Deploying the HTTP proxy servlet on a servlet container” on page 159
• “Testing the HTTP proxy servlet” on page 164

144 IBM App Connect Enterprise 12.0: User Guide

HTTP proxy servlet is deployed to a servlet container that is on a different machine to IBM App Connect
Enterprise with a network load-balancer for distributing work to several integration nodes
You can configure the HTTP proxy servlet for a deployment where the HTTP proxy servlet is deployed to a
servlet container that is on a different machine to IBM App Connect Enterprise, and the servlet container
has an IBM MQ client link to the integration node queue manager. In this configuration, a network load-
balancer is used to distribute work to several integration nodes.
In the following figure the HTTP proxy servlet is configured to load balance IBM MQ connections across
multiple integration nodes. A network load balancer is required for this configuration.
When the HTTP proxy servlet is configured to connect to multiple integration nodes, the integration nodes
must be identical clones of each other, which means that the same HTTP and SOAP flows are deployed
with the same web addresses.
The HTTP proxy servlet sends the HTTP requests over the IBM MQ connections to distribute the load
between the active integration node connections.

Chapter 4. Configuring IBM App Connect Enterprise 145

 The configuration is the same as that described in “HTTP proxy servlet is deployed to a servlet container
that is on a different machine to IBM App Connect Enterprise” on page 143, but the network load-
balancer replaces the integration node machine. Configuration files cannot be used because there are
several integration nodes behind one virtual IP address, and each one has a different configuration
file. The HTTP proxy servlet loads information for each connection, and uses the relevant configuration
information for each integration node.
In this configuration example, you must configure the following HTTP proxy servlet configuration
parameters. For information about configuring the HTTP proxy servlet, see “Configuring the HTTP proxy
servlet” on page 149.
• Set useClientMode to true.

146 IBM App Connect Enterprise 12.0: User Guide

• Set useQueueManagerDataInsteadOfConfigFile to * or the integration node queue manager
name.
• Set clientModeHostname, clientModeChannelName, and clientModePortNumber to the correct
values as detailed in “HTTP proxy servlet configuration parameters” on page 151.
If failover is one of the reasons for deploying this configuration, it is recommended that you configure the
following additional HTTP proxy servlet configuration parameters:
• Set clientModeConnectRetryCount to a value equal or higher than the number of integration
nodes. This setting ensures that a single failed server does not cause intermittent errors, even if the
load-balancer does simple round-robin scheduling. The HTTP proxy servlet uses the first available
integration node.
• Set reconnectActiveLinksAge to a value less than the firewall timeout. This setting prevents the
reuse of old connections that might have been discarded by firewalls between the HTTP proxy servlet
and the load-balancer (or between the load-balancer and the integration nodes).
You can set testConnectionBeforeReuse to true as an alternative way to manage dropped IBM
MQ connections between the HTTP proxy servlet and integration node queue managers. However, this
option causes an MQINQ call to be performed before any attempt to send data to the integration node.
If the MQINQ call fails, a new connection is established, and the data is sent over the new connection.
Because the configuration adds another operation to the MQPUT and MQGET calls, it results in significant
processing for every message; use this option only if no alternative options are available. For information
about MQINQ, MQPUT, and MQGET calls, search for Function calls in the IBM MQ product documentation.
Before you configure, deploy, and test the HTTP proxy servlet, ensure that you understand the following
concepts:
• “Working with HTTP flows” on page 792
• “HTTP listeners” on page 795
• “HTTP proxy servlet operation” on page 141
• “Importance of the context root when you configure the HTTP proxy servlet” on page 147
When you have gained an understanding of the HTTP proxy servlet concepts, read the following topics to
help you configure, deploy, and test the HTTP proxy servlet:
• “Configuring the HTTP proxy servlet” on page 149
• “Deploying the HTTP proxy servlet on a servlet container” on page 159
• “Testing the HTTP proxy servlet” on page 164

Importance of the context root when you configure the HTTP proxy servlet
You must assign a context root to the HTTP proxy servlet when you deploy the HTTP proxy servlet to a
servlet container. The choice of context root determines the message flow nodes or integration service
URLs with which the HTTP proxy servlet can communicate.
Web addresses, or Universal Resource Locators (URLs), have an important role when HTTP or SSL
(HTTPS) protocols are used.
The HTTP proxy servlet passes the requests from the servlet container to the integration node and vice
versa.
Each HTTP or SOAP input node expects to receive requests from a specific web address (or web
addresses when wildcard characters are used). The servlet container also uses the web address to locate
the servlets that are going to process the HTTP or HTTPS requests that the servlet container receives on
behalf of the integration node.
The web address is structured in the following way:

schema://host_name:port/url_path

where:

Chapter 4. Configuring IBM App Connect Enterprise 147

 schema
Specifies the protocol (HTTP or HTTPS).
host_name
Specifies the host name or IP address of the server where the servlet container is running.
port
Specifies the port number on which the servlet container is listening.
url_path
Specifies the URL path; a series of tokens (separated by slashes /) that identify both the HTTP proxy
servlet, and the HTTP or SOAP input nodes.
When you use the HTTP proxy servlet, the URL path is partitioned as follows:

context_root/node_url_path

where:
context_root
Specifies the part of the URL path (context root) that is allocated to the proxy servlet by the servlet
container when the proxy servlet is deployed.
node_url_path
Specifies the part of the URL path that makes the web address unique to a specific HTTP or SOAP
input node.
Note: You can set context_root to / in which case url_path and node_url_path are the same.
The entire URL path must be configured in the properties of the HTTPInput or SOAPInput node. For more
information, see node and node.
For example, you might have HTTPInput nodes that are configured to receive requests for the following
web addresses:
• Node1: http://myhost.com/app1
• Node2: http://myhost.com/public/app2
• Node3: http://myhost.com/public/app3
• Node4: http://myhost.com/private/app4
If you set the context root for your HTTP proxy servlet to /public, then you can communicate with
Node2 and Node3 via the HTTP proxy servlet.
If you set the context root for your HTTP proxy servlet to /private, then you can communicate with
Node4 via the HTTP proxy servlet.
If you set the context root for your HTTP proxy servlet to /, then you can communicate with all of the
HTTPInput nodes via the HTTP proxy servlet.
Choosing a context root for the HTTP proxy servlet
• If you have many existing applications that you want to access with the HTTP proxy servlet, and the
input nodes or integration services do not use URLs with a common root, you might want to set the
context root for the HTTP proxy servlet to /. Then you do not need to modify the URLs used by your
input nodes or integration services. However, if you set the context root for the HTTP proxy servlet
to /, then the HTTP proxy servlet becomes the default application for the servlet container, and the
HTTP proxy servlet attempts to process all requests that do not match the context root of any other
applications that are hosted by the servlet container.
• If you want to access a subset of your existing applications with the HTTP proxy servlet, you might
configure the URLs for the input nodes or integration services to start with a consistent value, for
example /public. Then you must set the context root of the HTTP proxy servlet to the same value.
• If you are building applications from scratch, then consider the requirements of the HTTP proxy
servlet when you plan the structure of the URLs you configure for your input nodes or integration
services.

148 IBM App Connect Enterprise 12.0: User Guide

Before you install and test the HTTP proxy servlet, ensure that you understand the following concepts:
• “Working with HTTP flows” on page 792
• “HTTP listeners” on page 795
• “HTTP proxy servlet operation” on page 141
When you have gained an understanding of the HTTP proxy servlet concepts, read the following topics to
help you configure, install, and test the HTTP proxy servlet:
• “Configuring the HTTP proxy servlet” on page 149
• “Deploying the HTTP proxy servlet on a servlet container” on page 159
• “Testing the HTTP proxy servlet” on page 164

Configuring the HTTP proxy servlet

Configure the HTTP proxy servlet with the details of the integration node environment to which the HTTP
proxy servlet connects. The HTTP proxy servlet must be configured before you deploy the HTTP proxy
servlet to a servlet container.

Before you begin

In order that the HTTP proxy servlet can access the SOAPInput and SOAPReply nodes, you must enable
the integration node listener for each integration server where message flows with SOAP nodes are
deployed. See “HTTP listeners” on page 795 and “Switching from embedded listeners to an integration
node listener” on page 798.

About this task

The HTTP proxy servlet proxyservlet.war file is part of the runtime environment, and can be found in
the following directory:
install_dir/server/tools
where install_dir specifies the name of your runtime installation directory.
Complete the following steps to configure the web deployment descriptor (web.xml) for the HTTP proxy
servlet by using the IBM App Connect Enterprise Toolkit.

Procedure

Chapter 4. Configuring IBM App Connect Enterprise 149

 1. To import and configure a .war file, you must have the Eclipse Java EE developer Tools feature
installed in the IBM App Connect Enterprise Toolkit. This feature is not included in the IBM App
Connect Enterprise Toolkit by default but can be installed by completing the following instructions:
a) From the IBM App Connect Enterprise Toolkit menu, click Help > Install New Software.
b) Enter the following URL in the "Work with" field:
http://download.eclipse.org/releases/juno
c) Click Add and enter a name for the site.
For example, Eclipse Juno downloads.
d) Click OK and wait until the available features are listed.
e) Expand the Web, XML, Java EE and OSGi Enterprise Development category, select the Eclipse
Java EE Developer Tools feature and click Next.
The Install Details dialog is displayed.
f) Click Next, accept the license, and then click Finish.
The feature is installed.
g) Click Yes when you are prompted to restart the IBM App Connect Enterprise Toolkit.
The Eclipse Java EE Developer Tools feature is now available in the IBM App Connect Enterprise
Toolkit.
2. From the IBM App Connect Enterprise Toolkit menu, switch to the Java EE perspective by clicking
Window > Open Perspective > Other and clicking Java EE.
3. Click File > Import, expand the Web section, select WAR file in the list, and click Next.
4. Click Browse to find the proxyservlet.war file in install_dir\server\tools, where
install_dir specifies the name of your IBM App Connect Enterprise installation directory (for example,
C:\Program Files\IBM\ACE\12.0.n.0\server\tools\proxyservlet.war), and click
Open.
5. Set the name of the Web project to proxyservlet and click Finish.
The HTTP proxy servlet is now ready for configuring by using the Java EE perspective.
6. In the Project Explorer view, expand proxyservlet and double-click Deployment Descriptor to view
the web deployment descriptor.
7. Find the Servlets and JSPs section in the Web Deployment Descriptor, and click the servlet link
called WBIMBServlet to display the servlet web address mappings and initialization parameters.
The same parameters in the web.xml file can be configured through JNDI in WebSphere Application
Server. This alternative method means that you set up at the application server side only once for any
future deployment of the proxy servlet. This operation is possible because the JNDI configuration
parameters take precedence over the initialization parameters in the web.xml file. For more
information about setting up the JNDI interface for the proxy servlet, see “Setting up the JNDI
interface for the proxy servlet” on page 156.
8. Click the Source tab, which is found at the bottom of the Deployment Descriptor view.
The source of the web deployment descriptor (web.xml) displays the HTTP proxy servlet
parameters.
9. Edit the HTTP proxy servlet parameters as required; see “HTTP proxy servlet configuration
parameters” on page 151.
10. When the configuration is complete, save the changes to the web.xml file by pressing Ctrl+S.

150 IBM App Connect Enterprise 12.0: User Guide

11. Export the configured HTTP proxy servlet ready for deployment to a servlet container by completing
the following steps:
a) In the Project Explorer view, right-click the Deployment Descriptor for the proxyservlet Web
project, and click Export > WAR file.
The WAR Export dialog window is displayed.
b) Click Browse and specify a location and a name for the configured WAR file.
For example, myproxyserlet.war.
c) Click Save and then click Finish.

Results
You have now configured the HTTP proxy servlet with the initialization parameters.

What to do next
Deploy and configure the HTTP proxy servlet on the web application server that will host the JavaScript
application, see “Deploying the HTTP proxy servlet on a servlet container” on page 159.

HTTP proxy servlet configuration parameters

Before you can deploy the HTTP proxy servlet to the servlet container, you must configure it with the
following initialization parameters for the integration node environment to which the HTTP proxy servlet
connects.
The parameters that you can configure for the HTTP proxy servlet are detailed in the following sections.
For information about how to configure the HTTP proxy servlet, see “Configuring the HTTP proxy servlet”
on page 149.
• “General options” on page 152
• “Information options” on page 153
• “ReplyToQ and QMgr options” on page 153
• “SSL connection options” on page 153
• “MQ connection options” on page 154
The following topics describe some common scenarios and the HTTP proxy servlet configuration
parameters that are required.
• “HTTP proxy servlet is deployed to a servlet container on the same machine as IBM App Connect
Enterprise” on page 142
• “HTTP proxy servlet is deployed to a servlet container that is on a different machine to IBM App
Connect Enterprise” on page 143
• “HTTP proxy servlet is deployed to a servlet container on a machine with its own queue manager” on
page 144
• “HTTP proxy servlet is deployed to a servlet container that is on a different machine to IBM App
Connect Enterprise with a network load-balancer for distributing work to several integration nodes” on
page 145

Chapter 4. Configuring IBM App Connect Enterprise 151

 General options

Parameter name Default value Description

brokerName * Set to * or the name of your integration node.

Use this parameter to specify the name that is used
for error messages; the value is auto-detected if set to
"*"'.
Specify a value if several integration nodes are being
used by the HTTP proxy servlet, and a single name is
required for error messages.

configFilePath /var/mqsi/ Specify the full path of the configuration file.

components/INODE/
If the integration node that is used by the HTTP
config/wsplugin6.conf
proxy servlet is local, set this parameter to the
wsplugin6.conf file.
This value is used only when the parameter
useQueueManagerDataInsteadOfConfigFile is
set to blank. The configuration file is used only when
the HTTP proxy servlet is running on the same server
as the integration node, and it has access to the file.
In Windows, the file is stored in C:
\install_dir\config\wsplugin.conf or
C:\Documents and Settings\All Users
\IBM\MQSI\components\NodeName\config
\wsplugin6.conf where NodeName is the name of
your integration node.
On Linux and UNIX, the file is stored in /var/
mqsi/config/wsplugin.conf or in /var/
mqsi/components/NodeName/config/
wsplugin6.conf where NodeName is the name of
your integration node.

useFastpathBindingsConnection
false Specify true or false.
Set the value to true to make the HTTP proxy servlet
connect in fastpath mode if the HTTP proxy servlet is
using a local queue manager.

traceFileName Specify the full path of the trace file.

If this parameter is not specified the trace is sent to
stdout.

turnTraceOn 0 Set to 0, 1, or 2.
Set 0 for no trace, 1 for normal trace, or 2 for debug
trace.

152 IBM App Connect Enterprise 12.0: User Guide

 Information options

Parameter name Default value Description

enableStatusPage false Set to true or false.

Set the value to true, to make the page accessible
at http://HostName:Port/ContextRoot/
messagebroker/httpproxy/statuspage where
HostName is the name of your servlet container, Port
is the port for your servlet container, and ContextRoot
is the context root you have set for your HTTP proxy
servlet. For more information about the context
root, see “Importance of the context root when you
configure the HTTP proxy servlet” on page 147.

enableInfoHeadersfalse Set to true or false.

Set the value to true to make the HTTP proxy servlet
add extra headers in the response message. These
headers are:
• X-WMB-Broker-Name
• X-WMB-QM-Name
• X-WMB-MQ-URL-CorrelId
The headers also contain details of the configuration
that is used for the response message.

ReplyToQ and QMgr options

Parameter name Default value Description

useClusterMode false Set to true or false.

Set to true if the HTTP proxy servlet is required to
put reply-to queue and queue manager information in
the MQMD of sent messages to enable the integration
node to respond to the correct queue manager in a
cluster.

clusterModeQueueManagerName
SOME_OTHER_ Set to the queue manager name for initial MQCONN
QUEUE_MANAGER and ReplyToQMgr.

clusterModeReplyToQ
OUR.REPLYTO.QUEUE Set to the reply queue name on which to listen.

SSL connection options

Parameter name Default value Description

useSecuredChannelfalse Set to true or false.

Set to true if SSL is configured on the MQ channel. If
set to true, the proxy servlet attempts to establish
a secured connection to the MQ channel by using
the keyStore, keyStorePassword, trustStore,
trustStorePassword, and cipherSuite
parameter values.

Chapter 4. Configuring IBM App Connect Enterprise 153

Parameter name Default value Description

keyStore Set to the full path of the keystore file.

The fully qualified path to the keystore file, which is of
type "JKS".
For example, in Windows: C:\\Program Files\
\IBM\\MQSI\\keystore.jks
On Linux and UNIX: /var/mqsi/keystore.jks

keyStorePassword changeit Set to the password of the keystore file.

trustStore Set to the full path of the truststore file.

The fully qualified path to the truststore file, which is
of type "JKS".
For example, on Windows: C:\\Program Files\
\IBM\\MQSI\\truststore.jks
On Linux and UNIX: /var/mqsi/truststore.jks
This field is mandatory if useSecuredChannel is set
to true.

trustStorePassword
changeit Set to the password of the truststore file.

cipherSuite Set to the encryption type that is configured in the MQ

channel. For example: SSL_RSA_WITH_NULL_MD5
This field is mandatory if useSecuredChannel is set
to true.

MQ connection options

Parameter name Default value Description

useClientMode false Set to true or false.

Set the value to true to use the IBM
MQ client or set the value to false to
use the bindings connection. Normally,
useQueueManagerDataInsteadOfConfigFile
would also be set to the integration node queue
manager if this parameter is set to true.

clientModeHostname
localhost Set to the host name or the IP address for the queue
manager.

clientModeChannelName
SYSTEM.DEF.SVRCONN Set to the IBM MQ SVRCONN channel name

clientModePortNumber
1414 Set to the port number of the IBM MQ listener.

154 IBM App Connect Enterprise 12.0: User Guide

Parameter name Default value Description

clientModeConnectRetryCount
1 Specify the number of times to retry the IBM MQ
connect call.
Use this parameter in cases where a network
dispatcher or load balancer is used to distribute work
to a set of queue managers and one of the queue
managers fails. A new connect call might fail the first
time, but succeed the second time. The retry count
must be set to a high number to provide the greatest
chance of success.

useQueueManagerDataInsteadOfConfigFile Set to the queue manager name, * (remote proxy), or

leave blank (local proxy).
Set this value to the queue manager name to make the
HTTP proxy servlet retrieve web address data from a
queue, and avoid the need for a configuration file to be
accessible by the HTTP proxy servlet.

sleepBeforeGet 0 Set to the time (in seconds) to wait before the HTTP
proxy servlet issues an MQGET call for a response
message from the integration node.

disconnectBeforeSleep
true Set to true or false.
Set the value to true to release the IBM MQ
handle while sleeping and minimize the number of
simultaneous IBM MQ connections.

reconnectActiveLinksAge
-1 Set to a time (in seconds), 0, or -1
Set the value to a number greater than zero to
force IBM MQ connections to be disconnected and
reconnected if they have been inactive, because of low
traffic volumes, for more than the specified number of
seconds.
Set the value to -1 to prevent any reconnection.
Set the value to 0 to force all connections to be used
only one time.
This parameter is useful if the connection to IBM MQ
goes through a firewall that closes connections after a
period of inactivity.
Set the value to a value less than the firewall timeout
to prevent clients from receiving IBM MQ 2009
(connection broken) error code responses.

Chapter 4. Configuring IBM App Connect Enterprise 155

Parameter name Default value Description

testConnectionBeforeReuse
false Set to true or false.
Set the value to true, to make the HTTP proxy servlet
attempt an MQINQ before it does the MQPUT of the
HTTP data message. All problems with a cached IBM
MQ client connection are detected at that point, and
a new connection is established for the MQPUT of the
actual data (and MQGET of the response).
This parameter causes significant extra network
traffic, and must be used only if there are problems
with dropped connections, which are usually seen as
IBM MQ 2009 errors, indicating that the connection is
broken.

maximumConnectionAge
-1 Set to a time (in seconds), 0, or -1
Set the value to a number greater than zero to
disconnect and reconnect IBM MQ connections if they
are older than the specified number of seconds.
Set the value to -1 to prevents any reconnections.
Set the value to 0 to use all connections only one time.
This parameter is of most use if the frequent changes
to the IBM MQ connection parameters are expected
due to redeployment of the IBM App Connect
Enterprise flows, and you require the HTTP proxy
servlet to reflect these changes within the specified
number of seconds.

Setting up the JNDI interface for the proxy servlet

The JNDI interface for the proxy servlet requires a one time setup of the WebSphere Application Server
full profile.

About this task

The proxy servlet initialization parameters must be configured for the integration node environment that
the proxy servlet is connecting to each time the proxy servlet is deployed to the servlet container. It is
now possible to configure the web.xml parameters only once through the JNDI in WebSphere Application
Server, regardless of how many future deployments there might be of the proxy servlet. Because the
JNDI configuration parameters take precedence over the initialization parameters in the web.xml file,
using this method means that you need to set up at the application server side only once for any future
deployments of the proxy servlet.
These setup tasks must all be completed in the WebSphere Application Server administrative console.

Creating a resource environment provider

About this task

Configure a resource environment provider, which encapsulates the referenceables that convert
resource environment entry data into resource objects. These resource objects can then be accessed by
applications.

156 IBM App Connect Enterprise 12.0: User Guide

Procedure
1. Select Resources > Resource Environment > Resource Environment Providers.
The Resource environment providers wizard opens.
2. Click New.
The Configuration panel opens so that you can configure a new resource environment provider.
3. Type a name for the resource environment provider in the Name filed. For example,
MyResourceEnvironmentProvider. It is recommended that you enter a meaningful description in
the Description field, but it is not required. Click OK to continue and then save the changes.

Results
The new resource environment provider is listed in the wizard.

Creating a referenceable object

About this task

Configure a new referenceable, which specifies the factory class that converts data in the Java Naming
and Directory Interface (JNDI) name space into an object that represents your resource to WebSphere
Application Server.

Procedure
1. Select Resources > Resource Environment > Resource Environment Providers.
The Resource environment providers wizard opens.
2. From the Resource environment providers panel, select the provider that you created in the previous
task: In this example, it is called MyResourceEnvironmentProvider.
3. Click Referenceables.
The Referenceables panel opens.
4. Click New.
The Configuration panel opens.
5. In the Configuration panel, type the following values:
a) In the Factory class name field, type:
com.ibm.broker.httpproxy.MQResourceConnectionFactory
b) In the Class name field, type: com.ibm.broker.httpproxy.MQResourceConnection
6. Click OK and save the changes.

Creating resource environment entries

About this task

Configure resource environment entries, which are objects that contain information about a resource, and
represent it in the JNDI name space.

Procedure
1. Select Resources > Resource Environment > Resource Environment Providers >
MyResourceEnvironmentProvider.
The Resource environment providers wizard opens at the configuration panel for your provider.
2. Click Resource environment entries.
The Resource environment entries panel opens.
3. Click New.
The Configuration panel opens.

Chapter 4. Configuring IBM App Connect Enterprise 157

 4. In the Configuration panel, type your values. In this example, the values are:
a) In the Name field, type for example: MQResourceReference
b) In the JNDI name field, type for example: proxyservlet/reference/MQResourceReference
.
This JNDI name is used during application deployment resource mapping.
c) In the Referenceables drop-down list, ensure that
com.ibm.broker.httpproxy.MQResourceConnectionFactory is selected.
5. Click OK and save the changes.

Creating custom properties or define the parameters to be configured

About this task

Specify custom properties that your enterprise information system (IES) requires for the resource
providers and resource factories that you configure. For example, most database vendors require extra
custom properties for data sources that access the database.

Procedure
1. Select Resources > Resource Environment > Resource Environment Providers >
MyResourceEnvironmentProvider > ResourceEnvironment Entries > MQResourceReference. where
MyResourceEnvironmentProvider and MQResourceReference are your own specified values.
The Resource environment providers wizard opens at the configuration panel for your entry.
2. Click Custom properties.
The Configuration panel opens.
3. Click New.
4. In the Configuration panel, you must type your values for all the resources that are administered
through the administrative console. For example: The integration node name, the configuration file
path, the client mode channel name, and the client mode port number. For each resource, you must
provide values for Name, Value, Description, and Type. The following example is for the integration
node name:
Option Description
Name This field refers to the value in the "<param-
name> </param-name>" tag in the web.xml.
For example: brokerName
Value This field refers to the value in the "<param-
value> </param-value>" tag in the web.xml.
For example: RRB
Description Optional. It is recommended that you provide a
meaningful description.
Type Specify the type. For example:
java.lang.String
5. Click OK to save the configuration.
6. Click New to create a new configuration for the remaining resources.

Results
You have a list of configured resources that is similar to the following table, but with the values that you
specified:

Name Value Description Required

brokerName
RRB Integration node name false

158 IBM App Connect Enterprise 12.0: User Guide

Name Value Description Required
configFilePath
C:\\Documents and Settings\\All Users.WINDOWS\ Configuration file path false
\Application Data\\IBM\\MQSI\\components\\RRB\
\config\soapplugin6.conf
clientModeChannelName
SYSTEM.DEF.SVR.CONN Client mode channel name false
clientModePortNumber
2908 Client mode port number false

The WebSphere Application Server wizard does not provide an option to specify the Required attribute
and so the default value is set to false. This attribute can be ignored.

What to do next
After you complete these tasks, you must deploy the proxyservlet.war file. During the deployment,
you must provide the JNDI reference name for the Resource Environment reference that is defined in
the web.xml file. For example: proxyservlet/reference/MQResourceReference.
After the deployment, proxyservlet gives precedence to the values configures in the Resource
Environment Entries. If there is an environment change, the values must be modified in the custom
properties of the Resource Environment Entries. After you modify a value, restart the Proxyservlet
application in WebSphere Application Server for the new values to take effect.

Deploying the HTTP proxy servlet on a servlet container

Load and install the HTTP proxy servlet file on a servlet container, such as Apache Tomcat, WebSphere
Application Server Liberty Profile, or an application server such as WebSphere Application Server.

Before you begin

Before you deploy the HTTP proxy servlet, you must complete the following tasks:
• Enable the integration node listener for each integration server where message flows with SOAP nodes
are deployed. See “HTTP listeners” on page 795 and “Switching from embedded listeners to an
integration node listener” on page 798.
• “Configuring the HTTP proxy servlet” on page 149

About this task

Supported operating systems
This documentation describes the installation on Windows, but the HTTP proxy servlet can be
installed on any operating system that is supported by the servlet container.
Prerequisite components
In addition to IBM App Connect Enterprise, the HTTP proxy servlet requires the following
components:
• A supported version of IBM MQ. For the latest details of all supported levels of hardware and
software, see the IBM App Connect Enterprise system requirements website.
• A servlet container, such as WebSphere Application Server Liberty Profile or Apache Tomcat, or an
application server, such as WebSphere Application Server.
The following topics describe how to deploy the HTTP proxy servlet onto WebSphere Application Server
Liberty Profile, Apache Tomcat, and WebSphere Application Server; however, the process is similar for
other servlet containers or web servers:
• “Deploying the HTTP proxy servlet on WebSphere Application Server Liberty Profile” on page 160
• “Deploying the HTTP proxy servlet on Apache Tomcat” on page 161
• “Deploying the HTTP proxy servlet on WebSphere Application Server” on page 163

Chapter 4. Configuring IBM App Connect Enterprise 159

 Results
You have deployed the HTTP proxy servlet on a servlet container or web server

What to do next
Test the HTTP proxy servlet. For information about how to complete this task, see “Testing the HTTP
proxy servlet” on page 164.

Deploying the HTTP proxy servlet on WebSphere Application Server Liberty Profile
Load and install the HTTP proxy servlet file on WebSphere Application Server Liberty Profile.

Before you begin

Before you deploy the HTTP proxy servlet, you must complete the following tasks:
• “Configuring the HTTP proxy servlet” on page 149
• Enabling the integration node listener for SOAP nodes

About this task

Install and customize a WebSphere Application Server Liberty Profile (Liberty) server, and then deploy
the HTTP proxy servlet by completing the following steps. The instructions assume that IBM App Connect
Enterprise is installed and running on the same machine as the Liberty server.

Procedure
To deploy the HTTP proxy servlet on the Liberty server, complete the following steps:
1. Follow the instructions on the WebSphere Application Server Liberty Profile download page to
download and install a Liberty server.
2. Create the following sub directory in your Liberty server installation:
Liberty_installation_path\wlp\usr\shared\resources\wmq.
3. Copy the following IBM MQ JAR files from WebSphere_MQ_installation_path\Java\lib to
Liberty_installation_path\wlp\usr\shared\resources\wmq:
• com.ibm.mq.commonservices.jar
• com.ibm.mq.headers.jar
• com.ibm.mq.jar
• com.ibm.mq.jmqi.jar
• com.ibm.mq.pcf.jar
• connector.jar
The HTTP proxy servlet uses IBM MQ to communicate with IBM App Connect Enterprise.
4. Copy the HTTP proxy servlet .war file that you exported from IBM App Connect Enterprise (for
example, myproxyservlet.war) to Liberty_installation_path\wlp\usr\shared\apps.
5. In the Eclipse workspace for the Liberty server, click the Servers tab and open the server.xml file by
double-clicking the Server Configuration entry.
6. Add the following lines to server.xml to define the shared library that contains the IBM MQ .jar
files:

<library id="wmq" name="wmq">

<fileset dir="${shared.resource.dir}/wmq" includes="*.jar"/>
</library>

160 IBM App Connect Enterprise 12.0: User Guide

7. Add the following lines to server.xml to set the context root for the HTTP proxy servlet and link
the HTTP proxy servlet with the IBM MQ shared library. For information about the context root, see
“Importance of the context root when you configure the HTTP proxy servlet” on page 147.

<application id="proxyservlet" location="servlet_file_name.war"

name="proxyservlet" type="war" context-root="context_root">
<classloader privateLibraryRef="wmq"/>
</application>

where:
servlet_file_name
Specifies the name of the HTTP proxy servlet file that you exported from IBM App Connect
Enterprise.
context_root
Specifies the context root you want to assign to the HTTP proxy servlet.
Note: If you want the HTTP proxy servlet to use an empty context root set context-root="/".
8. Save and close server.xml, and start the Liberty server.
9. To test if the HTTP proxy servlet is active, enter the following URL in a web browser:

http://host_name:port/context_root

where:
host_name
Specifies the host name of your Liberty server.
port
Specifies the port number of your Liberty server.
context_root
Specifies the context root that you assigned to the HTTP proxy servlet.
For example: http://localhost:9080/.
If the HTTP proxy servlet can reach the integration node, then you should get an HTTP Status 404
response with the following error message:
URI / does not map to any message flow in integration node integration_node
where integration_node is the name of your integration node.

Results
The HTTP proxy servlet is deployed on the WebSphere Application Server Liberty Profile server.

What to do next
The HTTP proxy servlet is now ready to be tested with an integration node that receives HTTP (not
HTTPS) requests and passes them to a message flow. For information about how to complete this task,
see “Testing the HTTP proxy servlet” on page 164.

Deploying the HTTP proxy servlet on Apache Tomcat

Load and install the HTTP proxy servlet file on Apache Tomcat.

Before you begin

Before you deploy the HTTP proxy servlet, you must complete the following tasks:
• “Configuring the HTTP proxy servlet” on page 149
• Enabling the integration node listener for SOAP nodes

Chapter 4. Configuring IBM App Connect Enterprise 161

 About this task
Install and customize Apache Tomcat, and then deploy the HTTP proxy servlet by completing the
following steps. The instructions assume that IBM App Connect Enterprise is installed and running on the
same machine as Apache Tomcat.

Procedure
1. Download Apache Tomcat from the Apache Tomcat 9 download page.
2. Run the Apache Tomcat installer and follow the instructions to complete the installation.
Note: When prompted for the path to a Java virtual machine (JVM) you can use the JVM that
is deployed with IBM App Connect Enterprise, for example C:\Program Files\IBM\ACE
\12.0.n.0\common\jdk\jre.
3. Find the file catalina.properties.
This can be found at the following location:
Tomcat_installation_path/conf/catalina.properties
where Tomcat_installation_path is the name of your Apache Tomcat installation directory.
4. Edit catalina.properties and locate the following line:

shared.loader=

5. Edit the line so that it includes the following text:

shared.loader=${catalina.home}/shared/lib,${catalina.home}/shared/lib/*.jar

6. Create the directory Tomcat_installation_path/shared/lib.

7. Copy the following IBM MQ JAR files from WebSphere_MQ_installation_path\Java\lib to
Tomcat_installation_path\shared\lib:
• com.ibm.mq.commonservices.jar
• com.ibm.mq.headers.jar
• com.ibm.mq.jar
• com.ibm.mq.jmqi.jar
• com.ibm.mq.pcf.jar
• connector.jar
The HTTP proxy servlet uses IBM MQ to communicate with IBM App Connect Enterprise.
8. Start the Apache Tomcat Windows service.
9. Open a web browser and enter the web address http://localhost:port where port is the HTTP
port number you specified in the Apache Tomcat installation.
The default value for the port is 8080.
The Apache Tomcat home page is displayed.
10. Click Tomcat Manager and enter the admin user ID and password.
11. Scroll down to the section WAR file to deploy and click Browse.
12. Navigate to the HTTP proxy servlet file that you exported from IBM App Connect Enterprise.
For example, myproxyservlet.war.
Note: By default in Apache Tomcat, the context root that is used by the HTTP proxy servlet is the
same as the .war file name. You can rename the .war file before you deploy the HTTP proxy servlet
in order to assign a different context root to the HTTP proxy servlet. For information about the context
root, see “Importance of the context root when you configure the HTTP proxy servlet” on page 147.
If you want the HTTP proxy servlet to use an empty context root (/), then you must rename the .war
file to ROOT.war and uninstall the current default web application (the Tomcat Welcome page).
13. Click Deploy.

162 IBM App Connect Enterprise 12.0: User Guide

14. To test if the HTTP proxy servlet is active, enter the following URL in a web browser:

http://host_name:port/context_root

where:
host_name
Specifies the host name of your Apache Tomcat server.
port
Specifies the port number of your Apache Tomcat server.
context_root
Specifies the context root that you assigned to the HTTP proxy servlet.
For example: http://localhost:8080/.
If the HTTP proxy servlet can reach the integration node, you should get an HTTP Status 404
response with the following error message:
URI / does not map to any message flow in integration node integration_node
where integration_node is the name of your integration node.

Results
The proxy servlet is deployed on your Apache Tomcat server.

What to do next
The HTTP proxy servlet is now ready to be tested with an integration node that receives HTTP (not
HTTPS) requests and passes them to a message flow. For information about how to complete this task,
see “Testing the HTTP proxy servlet” on page 164.

Deploying the HTTP proxy servlet on WebSphere Application Server

Load and install the HTTP proxy servlet file on WebSphere Application Server.

Before you begin

Before you deploy the HTTP proxy servlet, you must complete the following tasks:
• Configure the HTTP proxy servlet, as described in “Configuring the HTTP proxy servlet” on page 149
• Enable the integration node listener, as described in Enabling the integration node listener for SOAP
nodes
• Identify or install a WebSphere Application Server installation that can host the HTTP proxy servlet.

Procedure
To deploy the HTTP proxy servlet on WebSphere Application Server, complete the following steps:
1. Deploy the HTTP proxy servlet file that you exported from IBM App Connect Enterprise, by following
the instructions for deploying a web application in the WebSphere Application Server Version 8.5
product documentation online.
Ensure that you select the correct context root for your HTTP proxy servlet, as described in
“Importance of the context root when you configure the HTTP proxy servlet” on page 147.

Chapter 4. Configuring IBM App Connect Enterprise 163

 2. To test if the HTTP proxy servlet is active, enter the following URL in a web browser:

http://host_name:port/context_root

where:
host_name
Specifies the host name of your WebSphere Application Server
port
Specifies the port number of your WebSphere Application Server
context_root
Specifies the context root that you assigned to the HTTP proxy servlet
For example: http://localhost:9080/.
If the HTTP proxy servlet can reach the integration node, you will see an HTTP Status 404 response
with the following error message:
URI / does not map to any message flow in integration node integration_node
where integration_node is the name of your integration node.

Results
The HTTP proxy servlet is deployed on WebSphere Application Server.

What to do next
The HTTP proxy servlet is now ready to be tested with an integration node that receives HTTP (not
HTTPS) requests and passes them to a message flow. For information about how to complete this task,
see “Testing the HTTP proxy servlet” on page 164.

Testing the HTTP proxy servlet

Test the HTTP proxy servlet with an integration node that receives HTTP requests and passes them to a
message flow.

Before you begin

To test the HTTP proxy servlet, use an existing web services client application or write your own SSL test
client application by using Java.
Before you test the HTTP proxy servlet, you must have completed the following tasks:
• “Configuring the HTTP proxy servlet” on page 149
• Enabling the integration node listener for SOAP nodes for the proxy servlet to access
• “Deploying the HTTP proxy servlet on a servlet container” on page 159

Procedure
To test the HTTP proxy servlet, complete the following steps:
1. Install a client application that can send HTTP or SSL (HTTPS) requests.
For example,:
• An open source tool available from the OpenSSL downloads website that can be used to send HTTPS
requests to the servlet container.
• An integration node message flow that has an HTTPRequest or SOAPRequest node, which can
generate and send HTTP requests to an HTTP listener.
• A web browser, by using web pages or Java Server Pages (JSP), that can send HTTP POST requests.
Most web browsers support HTTP and HTTPS.
• A client application that sends requests by using HTTP, HTTPS, or both HHTP and HTTPS.

164 IBM App Connect Enterprise 12.0: User Guide

 2. Configure a message flow with HTTP and SOAP input and reply nodes. The HTTPInput and SOAPInput
nodes must be configured with a URL that matches the context root of the HTTP proxy servlet; for
more information, see “Importance of the context root when you configure the HTTP proxy servlet” on
page 147.
The message flow receives the messages from the HTTP proxy servlet. If an HTTP or SOAP reply node
is configured, responses are sent back to the HTTP proxy servlet.

Results
You have tested the HTTP proxy servlet.

Deleting an integration node

Delete an integration node by either using the command line on the system where IBM App Connect
Enterprise is installed, or use the IBM App Connect Enterprise Toolkit.

Before you begin

Check that your user ID has the correct authorizations to delete the integration node; for details, see
Security requirements for administrative tasks.
On Windows, Linux, and UNIX systems, you must set up your command-line environment before you
delete an integration node, by running the product profile or console; see “Setting up a command
environment” on page 64.

About this task

On Windows, Linux, and UNIX systems, you can delete an integration node by using the IBM App Connect
Enterprise Toolkit.
You cannot delete a remote integration node by using the IBM App Connect Enterprise Toolkit, but
you can remove the connection to the remote integration node from your workspace. To remove the
connection to a remote integration node in the IBM App Connect Enterprise Toolkit, right-click the
integration node in the Integration Explorer view, and click Remove Connection.
You can delete an integration node in the following ways:
• “Deleting an integration node by using the command line” on page 165
• “Deleting an integration node by using the IBM App Connect Enterprise Toolkit” on page 166.

Deleting an integration node by using the command line

Procedure
1. Stop the integration node by using the mqsistop command.
2. Delete the integration node by doing one of the following, dependent on your operating system:
•
Enter the following command to delete the integration node:

mqsideletebroker INODE

where INODE is the integration node name.

3. If you created integration server profiles for this integration node, delete these profiles if they are no
longer required.
4. Any empty integration server shared-classes directories (under workpath/
config/<my_int_node_name>/<my_int_server_label>) are automatically deleted. Otherwise,
if no longer required, it is left to the user to manually delete the directories and contents.

Chapter 4. Configuring IBM App Connect Enterprise 165

 5. If the integration node level shared-classes directory (under workpath/
config/<my_int_node_name>) is empty, it is automatically deleted. Otherwise, if no longer
required, it is left to the user to manually delete the directory and contents.

Results
On completion of this task:
•
On Linux, and UNIX, the integration node definition is removed.
•
Stopped and deleted the Windows service that runs the integration node.
• Removed any integration server profile scripts that are no longer needed.
• Removed any empty integration server shared-classes directories.
• Removed any empty integration node shared-classes directory.

Deleting an integration node by using the IBM App Connect Enterprise Toolkit

Procedure
1. Open the IBM App Connect Enterprise Toolkit, and switch to the Integration Development perspective.
2. In the Integration Explorer view, right-click the integration node, and click Delete.
If the integration node is a remote integration node, the connection to the integration node is removed
from your workspace.
If the integration node is a local integration node, the Delete Local Broker wizard is displayed.
3. Click Finish to delete the integration node.
If the integration node is running, the wizard stops the integration node.

Results
You have deleted the integration node.

Configuring an integration node as an IBM MQ service

Use these topics to make changes when your integration node is operating as an IBM MQ service.

About this task

The topics in this section describe how to configure your system for high availability.
• “Starting and stopping an integration node as an IBM MQ service” on page 166

Starting and stopping an integration node as an IBM MQ service

Configuring an integration node to start and stop as an IBM MQ service.

Before you begin

Ensure that you make the mqm user ID a member of the mqbrkrs group. On Windows systems, you must
restart your workstation for the change to take effect.

Procedure
To configure an integration node to run as an IBM MQ service, complete the following steps.

166 IBM App Connect Enterprise 12.0: User Guide

 1. Create an integration node to start as an IBM MQ service by using the mqsicreatebroker command
with the -d parameter.
Note: You must be a member of the mqm group to run the mqsicreatebroker command with the -
d parameter.
For example,

mqsicreatebroker MyBroker -q MyQMGR -d defined

where
MyBroker
Is the name of the integration node that you want to start and stop as an IBM MQ service.
MyQMGR
Is the name of the queue manager that is associated with the integration node.
2. Optional: If you want to create an App Connect Enterprise vault to hold the credentials that are used
by the integration node when secured resources are accessed, use the mqsivault command.
For example,

mqsivault MyBroker --create --vault-key 12345678

where
MyBroker
Is the name of the integration node that you want to start and stop as an IBM MQ service.
3. Optional: If you created an IBM App Connect Enterprise vault by running the mqsivault command at
step “2” on page 167, you must configure your environment by running one of the following steps:
a) Set the vault key as an environment variable. For example, on Windows:set
MQSI_VAULT_KEY=12345678
b) Add the vault key to an .mqsivaultrc file and copy the file into the home directory of the user
who starts the IBM MQ queue manager.
For more information about IBM App Connect Enterprise vaults and the .mqsivaultrc file, see
command and command.
4. Stop the queue manager.

Results
When you configure an integration node to start and stop as an IBM MQ service:
• The integration node starts and stops automatically when its associated queue manager starts and
stops. For a multi-instance integration node, this action can occur during failover of the active queue
manager.
• A multi-instance integration node cannot be started in standby mode when its IBM MQ service is
defined as active.
• You can stop the integration node manually by using the mqsistop command, but the integration node
does not restart until the queue manager is stopped and started again.
• On UNIX and Linux systems, the integration node environment is inherited from IBM MQ. Set any
required environment variables (such as ODBCINI) by using a script in the work_path/common/
profiles directory. For more information, see “Setting up a command environment” on page 64.

Configuring integration servers

Create and configure the integration servers that you want to use on the operating system of your choice.

Before you begin

Ensure that the following requirements are met:

Chapter 4. Configuring IBM App Connect Enterprise 167

 • Your user ID has the correct authorizations to perform the task. The authorizations are defined in
Security requirements for administrative tasks.
• You have initialized the command environment on distributed systems; see “Setting up a command
environment” on page 64.

About this task

You can create an integration server by using the IBM App Connect Enterprise Toolkit, the web user
interface, or App Connect Enterprise commands, and you can then configure it by modifying the
server.conf.yaml file.
When you have created and configured your integration servers, you can administer them and their
resources by using the web user interface, the command line, or programmatically by using the App
Connect Enterprise REST API. For more information, see “Managing integration servers” on page 249,
“Managing resources by using the administration REST API” on page 334, and “Accessing the web user
interface” on page 89.

Procedure
1. Create an integration server by following in the instructions in “Creating an integration server” on page
168.
2. Modify the integration server properties by following the instructions in “Configuring an integration
server by modifying the server.conf.yaml file” on page 172.
If you use any App Connect Enterprise commands that modify the integration server, an overrides
directory is created under the working directory for the integration server. This overrides directory
contains an additional server.conf.yaml configuration file, which includes property values that
have been set by commands; for example, <work_directory>/overrides/server.conf.yaml.
The values of properties in this overrides/server.conf.yaml file override any values
that you have set in the integration server's server.conf.yaml file (<work directory>/
server.conf.yaml).
3. Optional: Configure a default application for an integration server, by following the instructions in
“Configuring a default application for an integration server” on page 181.
4. Optional: If you want to delete an integration server, follow the instructions in “Deleting an integration
server” on page 175.

Creating an integration server

You can create integration servers by using the IBM App Connect Enterprise Toolkit, the web user
interface, or commands.

About this task

You must create an integration server before you can deploy integration solutions and related resources.
You can create one or more independent integration servers, each with their own identity, and deploy
them either to containers in the cloud or in an on-premises environment. If you are planning to run App
Connect Enterprise directly on a physical machine or virtual machine image, you are advised to define
integration servers under an integration node, which will manage its associated integration servers.
For information about why you might want to create multiple integration servers, see Integration servers
and integration nodes.
The mode in which IBM App Connect Enterprise is running can affect the number of integration servers
that you can use; see “Restrictions that apply in each operation mode” on page 5.
For an independent integration server, you create the server's work directory and then configure
the server's properties, as described in “Creating an integration server work directory by using the
mqsicreateworkdir command ” on page 169.

168 IBM App Connect Enterprise 12.0: User Guide

You can also create and start a local independent integration server by using the IBM App Connect
Enterprise Toolkit, as described in “Creating and starting a local, independent integration server by using
the Toolkit” on page 170.
To create an integration server under an integration node, first start the integration node, and then use
one of the following methods:
• “Creating an integration server that is managed by an integration node, by using the Toolkit” on page
171
• “Creating an integration server that is managed by an integration node, by using the web user interface”
on page 171
• “Creating an integration server that is managed by an integration node, by using the
mqsicreateexecutiongroup command” on page 172
You can also use the IBM Integration API to create integration servers on all platforms; see “Managing
resources by using the IBM Integration API” on page 444.

Creating an integration server work directory by using the

mqsicreateworkdir command
To create a work directory to be used by an independent integration server, use the
mqsicreateworkdir command.

Procedure
1. Open a command window for your current installation.
2. Create a work directory for your independent integration server, by running the mqsicreateworkdir
command, specifying the full path to the directory that you want to create.
For example:

mqsicreateworkdir c:\myaceworkdir\myserver

This command creates the specified work directory, which contains a default configuration file called
server.conf.yaml. This YAML file contains the default settings for your new integration server. The
command also creates subdirectories, which will be used by the integration server when it is running.
These include a log directory and a run directory. The log directory contains files of log messages,
which can be used to review the status of your integration server. The run directory is where you can
place your BAR files prior to starting your integration server, or while it is running. The resources from
the BAR file are extracted and started by the integration server.
If you have a BAR file with resources that contain graphical data maps, XML schemas, or DFDL
schemas, these resources can be compiled using the command, prior to starting the integration server.
This precompilation reduces the time that it takes for the deployed application to start processing
messages.
See the mqsicreateworkdir command for more information.
3. Configure your integration server by setting properties in the server.conf.yaml file, as described in
“Configuring an integration server by modifying the server.conf.yaml file” on page 172.

Results
The integration server is created and the updated server.conf.yaml configuration file is stored in
integration server's subdirectory in the file system.

What to do next
You can now start the integration server by running the command, as described in “Starting an integration
server” on page 250.

Chapter 4. Configuring IBM App Connect Enterprise 169

 You can deploy resources to your integration server, as described in Chapter 7, “Deploying integration
solutions,” on page 2463.

Creating and starting a local, independent integration server by using the

Toolkit
You can use the IBM App Connect Enterprise Toolkit to create and start a local, independent integration
server.

About this task

You can create and start a local, independent integration server by using a wizard in the IBM App Connect
Enterprise Toolkit. The wizard starts a process on the operating system for the independent integration
server. The Toolkit does not manage the process for an independent integration server in the same
way that an integration node manages the integration servers that are associated with it. When you
stop the Toolkit, any independent integration server processes that were started from the Toolkit are
stopped. However, if the Toolkit stops unexpectedly, or if its Eclipse process is stopped, the independent
integration server processes continue to run on your operating system, and you will need to use an
operating system process management tool to stop them.

Procedure
Create and start a local, independent integration server by completing the following steps:
1. In the Integration Explorer view, right-click Integration servers and then click Create a local
integration server.
2. In the Connection details wizard, enter the following information:
• Name
Enter the name of the local independent integration server that you want to create and start. When
you run the wizard for the first time, the default name for the integration server is TEST_SERVER.
If you run the wizard again, the TEST_SERVER will already exist so you must specify an alternative
name for the new integration server.
• REST Administration Port
Specify the port to be used for REST administration. By default, you can allow the wizard to find a
port that is available to use. If you want to specify a different port, first ensure that it is not being
used by another process, then deselect the checkbox and enter the required port number. The port
that you specify cannot be used by the integration server if it is already in use by another process.
• HTTP Port
Specify the port that is used by the HTTPConnector resource manager when an HTTP-based
message flow is deployed as part of an application. By default, you can allow the wizard to find a
port that is available to use. If you want to specify a different port, first ensure that it is not being
used by another process, then deselect the checkbox and enter the required port number. The
port is then used when the message flow is deployed. The wizard finds an available port when the
integration server is started. If the message flow is deployed at a much later date, the port might no
longer be available, in which case an error message is shown at deployment time to indicate that the
HTTP listener could not be started for that port. If this happens, specify the correct port used by the
HTTPConnector in the server.conf.yaml file in the overrides directory, and then stop and start
the integration server.
• JVM Debug Port
Specify the port to be used for debugging a message flow. By default, you can allow the wizard find
a port that is available to use. If you want to specify a different port, first ensure that it is not being
used by another process, then deselect the checkbox and enter the required port number. This sets
the jvmDebugPort property in the server.conf.yaml file for the JVM resource manager to use.

170 IBM App Connect Enterprise 12.0: User Guide

 If you do not want to debug a message flow, you can disable the JVM debug port by deselecting the
checkbox and entering the value 0 in the field.
• Click Finish.
A confirmation message shows that a configuration directory has been created in the workspace
and that the integration server has been started using the details in the configuration directory.
The configuration directory that is created in your workspace has the same name as the integration
server that has been created and started. This is the same configuration directory that is created by
the mqsicreateworkdir command. The configuration directory is shown under Independent
Resources in your workspace. The wizard creates an override file for the server.conf.yaml that
is used by the integration server. This override file contains the values of the ports that will be used
by the integration server.
3. Optional: When you have created and started the integration server, you can deploy an application or
library to it.
4. Optional: You can view the console.log file for the integration server. The location of the
console.log file is under the main configuration directory.
5. Optional: You can stop the integration server by right-clicking it and then clicking Stop, which stops the
integration server process. You can restart the integration server by right-clicking it and then clicking
Start to start the integration server process.
6. Optional: You can remove the connection for the integration server when it has been stopped, but the
configuration directory is not deleted from your workspace automatically; however, you can delete the
directory manually.
If you have previously stopped the integration server and removed the connection for it, you can create
it again and it will use the configuration directory in your workspace, if it exists. In this case, a message
informs you that the existing configuration directory in your workspace will be used.

Creating an integration server that is managed by an integration node, by

using the Toolkit

Procedure
To create an integration server under an integration node, you can use the IBM App Connect Enterprise
Toolkit:
1. Optional: If you are working with a remote integration node, connect to the integration node; see
Connect to a remote integration node.
2. Make sure that the integration node is running.
3. In the Integration Explorer view, right-click the integration node, and then select New Integration
Server.
4. In the New Integration Server dialog, enter the integration server name.
5. Click OK to create the integration server.

Results
The integration server is added to the selected integration node.

Creating an integration server that is managed by an integration node, by

using the web user interface

Procedure
To create an integration server under an integration node, you can use the web user interface:
1. Make sure that the integration node is running.
2. Start the web user interface, as described in “Accessing the web user interface” on page 89.

Chapter 4. Configuring IBM App Connect Enterprise 171

 3. Select the Servers tab, and then click Create.
4. In the New Integration Server dialog, enter the integration server name.
5. Click OK to add the integration server.
6. Optional: Configure your integration server by setting properties in the server.conf.yaml file, as
described in “Configuring an integration server by modifying the server.conf.yaml file” on page 172.

Results
The integration server is created.

Creating an integration server that is managed by an integration node, by

using the mqsicreateexecutiongroup command
To create integration server under an integration node, you can use the mqsicreateexecutiongroup
command.

Procedure
1. If you are creating an integration server on Linux or Windows systems:
a) Open a command window for your current installation.
b) Enter the mqsicreateexecutiongroup command, and specify the parameters for the integration
server that you want to create.
• If the integration node is local, specify the integration node name. For example:

mqsicreateexecutiongroup INODE -e IServer_2

• If the integration node is remote, you can specify a configuration file. For example:

mqsicreateexecutiongroup -n INODE.broker -e IServer_2

• If the integration node is remote, you can alternatively specify the connection parameters -i and
-p. For example:

mqsicreateexecutiongroup -n INODE -e IServer_2 -p 4414 -i host

See the mqsicreateexecutiongroup command description for more details about these
options.
2. If you are creating an integration server on z/OS:
a) Configure the BIPCREG job to specify the properties for the integration server that you want to
create.
b) Run the BIPCREG job.
3. Optional: Configure your integration server by setting properties in the server.conf.yaml file, as
described in “Configuring an integration server by modifying the server.conf.yaml file” on page 172.

Results
The integration server has been created under the specified integration node.

What to do next
Deploy resources to your integration server; see Chapter 7, “Deploying integration solutions,” on page
2463.

Configuring an integration server by modifying the server.conf.yaml file

You can configure your IBM App Connect Enterprise integration server by modifying properties in a
server.conf.yaml configuration file. The location of the server.conf.yaml file that you need to

172 IBM App Connect Enterprise 12.0: User Guide

modify depends on whether you are configuring an independent integration server or an integration server
that is managed by an integration node.

Before you begin

Ensure that you set up your command environment, as described in “Setting up a command environment”
on page 64.

About this task

When you have created an integration server, you set properties in the server.conf.yaml file to
configure the operation of the integration server and associated resources. For example, you can set
a REST administration port and an HTTPS port, and you can configure the trace level, activity logging,
JVM, and the reporting of statistics data for your integration server. You can also configure the integration
server to record all messages that pass through a message flow, and then use these recorded messages
to generate unit tests.
For an independent integration server, the server.conf.yaml configuration file is created for you
automatically when you use the mqsicreateworkdir command to create an integration server work
directory. The server.conf.yaml file is created in the root of the specified work directory: <work
directory>/server.conf.yaml.
If you use any commands that modify the integration server, an overrides directory is created under
the working directory for the integration server. This overrides directory contains an additional
server.conf.yaml configuration file, which contains property values that are set by commands; for
example, <work directory>/overrides/server.conf.yaml. The values of properties in this
overrides/server.conf.yaml file override any values that you have set in the integration server's
server.conf.yaml file (<work directory>/server.conf.yaml).
If a property has been set in the integration server's server.conf.yaml file, and also in the overrides
directory (/overrides/server.conf.yaml), the property value that has been set in the overrides
directory is used. Therefore, if an integration server does not appear to be using the settings that you
would expect, check the server.conf.yaml file in the overrides directory to see if your expected
property value has been overridden by a command. If you want to manually override the settings that
have resulted from a command, you can either edit the property in the server.conf.yaml file in
the overrides directory, or you can remove the entry from the overrides directory and modify the base
server.conf.yaml file instead.
For integration servers that are managed by an integration node, each server has its own
server.conf.yaml configuration file that overrides common settings from the integration node's
node.conf.yaml configuration file. When you create an integration node, the node.conf.yaml file is
located at: $MQSI_WORKPATH/components/<Node name>/node.conf.yaml.
If you use commands to modify the integration node, the changes are saved in the integration node's
override node.conf.yaml file. This file is located at: $MQSI_WORKPATH/components/<Node name>/
overrides/node.conf.yaml, as described in “Creating an integration node by using the command
line” on page 115. When you create a managed integration server for an integration node, server-
specific settings are created for it in its own server.conf.yaml file. The server-specific file is located
at: $MQSI_WORKPATH/components/<Node name>/servers/<Server name>/server.conf.yaml.
If you use commands to modify this integration server, the changes are saved in: $MQSI_WORKPATH/
components/<Node name>/servers/<Server name>/overrides/server.conf.yaml. The
values of properties in this overrides/server.conf.yaml file override any values that you have set in
the <Node name>/servers/<Server name>/server.conf.yaml file.

Procedure
1. If the integration server does not exist already, you can create it by following the instructions in
“Creating an integration server” on page 168.

Chapter 4. Configuring IBM App Connect Enterprise 173

 2. Use a YAML editor to open the server.conf.yaml file.
If you do not have access to a YAML editor, you can edit the file by using a plain text editor. However,
you must ensure that you do not include any tab characters, which are not accepted in YAML and
would cause your integration server configuration to fail. If you choose to use a plain text editor,
ensure that you use a YAML validation tool to validate the content of your file.
For more information about working with YAML, see http://www.yaml.org/start.html.
3. Modify the properties that you want to change in the file.
For example:
• In the RestAdminListener section, set a value for the Port property to be used by the REST
administration port, which is the primary method of communicating with the integration server.
(Default value of 7600.)
• In the ResourceManagers / HTTPConnector section, set a value for the ListenerPort so that you
can send messages to a flow that is using a HTTPInput node. (Default value of 7800.)
• In the ResourceManagers / JVM section, set a value for the jvmDebugPort so that you can use the
Flow Debugger. For example, set this property to 6511.
You can also configure the integration server to record all messages that pass through a message flow,
by setting properties in the RecordedMessageManager section of the server.conf.yaml file. You
can then use these recorded messages to generate unit tests for the flow, as described in “Generating
tests from recorded messages in a message flow” on page 1908.
4. Save your changes to the server.conf.yaml file.
If you run any commands that modify the integration server at any time after you set properties
in the server.conf.yaml file, an overrides directory is created under the working directory
for the integration server. This overrides directory contains another server.conf.yaml
configuration file, which contains property values that are set by commands; for example, <work
directory>/overrides/server.conf.yaml. The values of properties in this overrides/
server.conf.yaml file override any values that you have set in the integration server's
server.conf.yaml file (<work directory>/server.conf.yaml). If you want to manually
override the settings that have resulted from a command, you can either edit the property in the
server.conf.yaml file in the overrides directory, or you can remove the entry from the overrides
directory and modify the base server.conf.yaml file instead.
5. Specify the security credentials to be used by the integration server when you connect to a secured
resource (such as a database) by using the mqsisetdbparms command. Use the -w parameter to
specify the integration server's work directory that you created in step 1:
For example:

mqsisetdbparms -w c:\myaceworkdir -n jdbc::secID -u iibuser -p password

When you run this command, the user ID and password are stored securely in the IBM App Connect
Enterprise credentials store. For more information about using the mqsisetdbparms command, see
command.
Alternatively, you can configure an independent integration server to connect to secured resources
by using credentials that are stored in encrypted form in an App Connect Enterprise vault. You can
configure security credentials by using the command or the administrative REST API. These encrypted
credentials are stored in the integration server's vault, which you configure by using the command. For
more information, see “Configuring encrypted security credentials” on page 177.
6. Optional: You can configure applications to run when the integration server starts, by pre-loading the
BAR file into the run folder of the integration server's work directory. For information, see command.
7. Restart the integration server. The properties that you set in the server.conf.yaml file take effect
when the integration server is started. If you modify these properties again, you must start the
integration server again for the subsequent changes to take effect. For more information, see “Starting
an integration server” on page 250.
If the integration server fails to restart, check to see whether the failure was caused by a YAML parsing
error. For an independent integration server, parsing errors are reported to the stderr log. For an

174 IBM App Connect Enterprise 12.0: User Guide

 integration server that is managed by an integration node, YAML parsing errors are reported to the
integration server's console.txt file. For more information, see Standard system logs.

Deleting an integration server

Delete integration servers by using IBM App Connect Enterprise Toolkit, the web user interface, or a
command.

Before you begin

Check that the integration server is running; you cannot delete an integration server that is stopped.

About this task

Use one of the following methods to complete this task:
• “Deleting an integration server by using the IBM App Connect Enterprise Toolkit” on page 175
• “Deleting an integration server by using the web user interface” on page 175
• “Deleting an integration server by using the mqsideleteexecutiongroup command” on page 176
You can also use the IBM Integration API to delete integration servers on all platforms; see “Managing
resources by using the IBM Integration API” on page 444.

Deleting an integration server by using the IBM App Connect Enterprise

Toolkit

Procedure
Complete the following steps to delete an integration server:
1. Open the IBM App Connect Enterprise Toolkit, and switch to the Integration Development perspective.
2. In the Integration Explorer view, expand your integration node.
3. Right-click the integration server that you want to delete, and click Delete > Integration Server.

Results
Your integration server and all resources that are deployed to it are deleted.
• If you created any integration server profiles for this integration server, delete them manually if they are
no longer required.
• If the shared-classes directory (under workpath/
config/<my_int_node_name>/<my_int_server_label>) is empty, this directory is automatically
deleted.
Note: If the shared-classes directory is not empty but is no longer required, the directory can be
deleted manually.

Deleting an integration server by using the web user interface

Procedure
Complete the following steps to delete an integration server:
1. Start the web user interface for your integration node; see “Accessing the web user interface” on page
89.
The navigator is displayed on the left side of the pane, showing the servers (integration servers),
message flows, and other resources that are owned by your integration node.
2. Expand the Servers folder, click the down arrow beside the integration server you want to delete to
display the menu, and then click Delete.

Chapter 4. Configuring IBM App Connect Enterprise 175

 3. Click Yes to confirm that you want to delete the integration server.

Results
Your integration server and all resources that are deployed to it are deleted.
• If you created any integration server profiles for this integration server, delete them manually if they are
no longer required.
• If the shared-classes directory (under workpath/
config/<my_int_node_name>/<my_int_server_label>) is empty, this directory is automatically
deleted.
Note: If the shared-classes directory is not empty but is no longer required, the directory can be
deleted manually.

Deleting an integration server by using the mqsideleteexecutiongroup

command

Procedure
Complete the following steps to delete an integration server:
1. If you are deleting an integration server on Linux, UNIX, and Windows systems:
a) Open a command window for your installation.
b) Enter the mqsideleteexecutiongroup command, and specify the parameters for the integration
server that you want to delete.
• If the integration node is local, specify the integration node name; for example:

mqsideleteexecutiongroup -n INODE -e IServer_2

• If the integration node is remote, you can specify a configuration file; for example:

mqsideleteexecutiongroup -n INODE.broker -e EGroup_2

• If the integration node is remote, you can alternatively specify the connection parameters -i and
-p; for example:

mqsideleteexecutiongroup -e IServer_2 -n INODE -e IServer_2 -p 4414 -i

See the mqsideleteexecutiongroup command description for more details about these
options.
2. If you are deleting an integration server on z/OS:
a) Configure the BIPDLEG job to specify the properties for the integration server that you want to
delete.
b) Run the BIPDLEG job.

Results
Your integration server and all resources that are deployed to it are deleted.
• If you created any integration server profiles for this integration server, delete them manually if they are
no longer required.
• If the shared-classes directory (under workpath/
config/<my_int_node_name>/<my_int_server_label>) is empty, this directory is automatically
deleted.
Note: If the shared-classes directory is not empty but is no longer required, the directory can be
deleted manually.

176 IBM App Connect Enterprise 12.0: User Guide

Configuring encrypted security credentials
You can configure integration nodes and integration servers to connect to secured resources by using
credentials that are stored in encrypted form in an IBM App Connect Enterprise vault.
You can configure security credentials by using the command or the administrative REST API, and you can
view credentials by using the web user interface. The encrypted credentials are stored in a vault, which
you can configure by using the command, or by specifying a vault key on the command.
Alternatively, you can use the mqsisetdbparms command to associate credentials with resources that
are accessed by an integration server or an integration node. For more information, see command.
Video: Storing encrypted security credentials in a vault using App Connect Enterprise
This video demonstrates create a vault in App Connect Enterprise and then store credentials in it in
encrypted form.
Note:
This video was created for App Connect Enterprise 11.0, but also applies to App Connect Enterprise 12.0.

Creating a vault by using the mqsivault command

Before you can store encrypted credentials for an integration node or integration server, you must
configure an App Connect Enterprise vault. You create a separate vault for each independent integration
server, and for each integration node. Each independent integration server has its own vault, with its
own vault key. Each integration node has its own vault, with its own vault key, which is shared by all the
integration servers that it manages. Each integration server that is managed by an integration node has its
own credentials stored in the vault, but all the credentials in the vault are accessed by the same vault key.
You can use the mqsivault command to create or destroy a vault, to change or verify a vault key, or
to retrieve credentials from the vault. The vault stores the credentials (in encrypted form), and the
integration node or server uses them to access secured resources.
For more information about how to use the command, see command.

Creating a vault by using the mqsicreatebroker command

If you create an integration node by running the mqsicreatebroker command, you can create a vault
for that integration node by specifying either the --vault-key or --vaultrc-location parameter on
the command. For more information about how to use the command, see command.

Configuring encrypted credentials by using the mqsicredentials command

You can use the mqsicredentials command to configure an integration node or integration server to
use encrypted credentials for connecting to a secured resource.
You use the mqsicredentials command to create, update, report, and delete credentials for an
independent integration server or for an integration node and the integration servers that it manages. You
can use the command to create and report credentials when the integration server is running or stopped,
but you must stop the integration server before you can update or delete credentials.
For information about how to use the command, see command.

Creating and viewing credentials by using the administration REST API

You can use the IBM App Connect Enterprise administration REST API to create or report security
credentials for an integration node or server. For information about using the administration REST API,
see REST API for administering integration servers.

Chapter 4. Configuring IBM App Connect Enterprise 177

 Viewing credentials by using the web user interface
You can use the IBM App Connect Enterprise web user interface to view credentials for an integration
node or server.
To display information about the credential, start the web user interface to view the relevant integration
server, and then click the tile for the credential that you want to view. The properties for that credential
are displayed, including the user name, authentication type, credentials provider, whether the credential
is read-only, and whether a password has been set. For information about how to start the web user
interface, see “Accessing the web user interface” on page 89.

Configuring security credentials for an independent integration

server in the server.conf.yaml file
You can configure an independent integration server to connect to secured resources by using credentials
that are defined in the integration server's server.conf.yaml configuration file.
You can configure credentials for each credential type by setting properties in the ServerCredentials
section of the server.conf.yaml file. You can specify the credential type, name, and each of the
properties that you want to set; for example:

ServerCredentials:
odbc:
USERDB:
username: "user1"
password: "pass"
DATAFLOW:
username: "usr2"
password: "myLongPassword"
salesforce:
mysf1:
username: "aName"
password: "passw0rd"
clientId: "clientEye"
clientSecret: "worldsBiggestSecret"
jdbc:
db:
username: "myusername"

If you want to change the credentials when they have been set, you must update the properties in the
server.conf.yaml file and then restart the integration server. The credentials are read when the
integration server starts, and can be used by the message flows that are running on the integration server.
The credentials are accessible through the web user interface, the REST API, and the mqsicredentials
command (when the integration server is running). The credentialProvider field for credentials that
are defined in this way is shown as servercredentials.
You can specify the following credential types and properties in the server.conf.yaml file:
• cd:
Specify this type to set credentials for connecting an IBM Sterling Connect:Direct® CDOutput node to its
Connect:Direct server.
You can set the username and password properties for connecting to a Connect:Direct server.
• cics:
Specify this type to set credentials for connecting a CICSRequest node to a CICS® Transaction Server for
z/OS server.
You can set the username and password properties for connecting to a CICS Transaction Server for z/
OS server. Password is optional.

178 IBM App Connect Enterprise 12.0: User Guide

• eis:
Specify this type to set credentials for connecting to an external Enterprise Information System (EIS),
such as SAP, Siebel, JD Edwards, or PeopleSoft.
You can set the username and password properties for connecting to an EIS.
• email:
Specify this type to set credentials for connecting to an email server.
You can set the username and password properties for connecting to an email server.
• ftp:
Specify this type to set credentials for connecting to an FTP server.
You can set the username and password properties for connecting to an FTP server.
• http:
Specify this type to set credentials for static ID identity propagation with SOAP or HTTP request nodes
when using basic authentication (basicAuth).
You can set the username and password properties for SOAP or HTTP request nodes (SOAPRequest,
SOAPAsyncRequest, HTTPRequest, and HTTPAsyncRequest nodes).
• httpproxy:
Specify this type to set credentials for connecting to a secured HTTP proxy server.
You can set the username and password properties for connecting to an HTTP server.
• ims:
Specify this type to set credentials for connecting from an IMSRequest node to the IMS server.
You can set the username and password properties for connecting to an IMS server.
• jdbc:
Specify this type to set credentials for a JDBC type 4 connection.
You can set the username and password properties for connecting to a JDBC resource.
• jms:
Specify this type to set credentials for connecting to JMS resource.
You can set the username and password properties for connecting to a JMS resource.
• jndi:
Specify this type to set credentials for connecting to a JNDI resource.
You can set the username and password properties for connecting to a JNDI resource.
• kafka:
Specify this type to set credentials for connecting to a secured Kafka cluster.
You can set the username and password properties for connecting to a Kafka cluster.
• kerberos:
Specify this type to set credentials for connecting to the Kerberos Key Distribution Center (KDC).
You can set the username and password properties for connecting to a Kerberos KDC.
• keystore:
Specify this type to set credentials for opening the web user interface keystore.
You can set the password property for opening the web user interface keystore.

Chapter 4. Configuring IBM App Connect Enterprise 179

 • keystorekey:
Specify this type to set credentials for opening a key inside the web user interface keystore.
You can set the password property for opening the key inside the keystore (for use when the key inside
the keystore is protected by a password that is different from the password used to open the keystore).
• ldap:
Specify this type to set Lightweight Directory Access Protocol (LDAP) bind credentials.
You can set the username and password properties for binding to an LDAP server.
• loopback:
Specify this type to set credentials for a connection that is made through a LoopBack® connector.
You can set either the username and password or the username, password, clientId, and
clientSecret properties for connecting through a LoopBack connector.
• mq:
Specify this type to set credentials for connecting to a secured IBM MQ queue manager.
You can set the username and password properties for connecting to an IBM MQ queue manager.
• mqtt:
Specify this type to set credentials for connecting to a secured external MQTT server, which the
integration server uses to publish its event messages.
You can set the username and password properties for connecting to an external MQTT server.
• odbc:
Specify this type to set credentials for an Open Database Connectivity (ODBC) data source name (DSN)
that is accessed from a message flow.
You can set the username and password properties for accessing an ODBC DSN from a message flow.
• odm:
Specify this type to set credentials for an Operational Decision Manager (ODM) Rule Execution Server
that is accessed from a message flow.
You can set the username and password properties for accessing an ODM Rule Execution Server from
a message flow.
• rest:
Specify this type to set credentials for authenticating a connection to an external REST API.
You can set the following properties for connecting to an external REST API:
– apiKey
– username and password
– username, password, and apiKey
• salesforce:
Specify this type to set credentials for authenticating a connection to a Salesforce system.
You can set the username, password, clientId, and clientSecret properties for accessing a
Salesforce system.
• sftp:
Specify this type to set credentials for authenticating a connection to an SFTP server.
To access an SFTP server, you must specify either the password or sshIdentityFile property,
but not both. If you specify an identity file, you can also specify a passphrase with the passphrase
property.

180 IBM App Connect Enterprise 12.0: User Guide

 • smtp:
Specify this type to set credentials for authenticating a connection to an SMTP server.
You can set the username and password properties for connecting to an SMTP server.
• soap:
Specify this type to set credentials for static ID identity propagation with SOAP request and reply
nodes when using WS-Security while connecting to or replying from a web service (SOAPRequest,
SOAPAsyncRequest, and SOAPReply nodes).
You can set the username and password properties to specify the credentials for these connections.
• truststore:
Specify this type to set credentials for connecting to an integration server truststore.
You can set the password property for connecting to a truststore.
• truststorekey:
Specify this type to set credentials for opening a key inside the integration server truststore.
You can set the password property for opening the key inside the truststore (for use when the key
inside the truststore is protected by a password that is different from the password used to open the
truststore).
• wsrr:
Specify this type to set credentials for connecting to a WebSphere Service Registry and Repository
You can set the username and password properties for accessing a WebSphere Service Registry and
Repository.
• wxs:
Specify this type to set credentials for connecting to a secure WebSphere eXtreme Scale grid.
You can set the username and password properties for accessing a WebSphere eXtreme Scale grid.
For more information about configuring an integration server, see “Configuring an integration server by
modifying the server.conf.yaml file” on page 172.

Configuring a default application for an integration server

You can configure a default application for an integration server by setting the application name in the
integration server's server.conf.yaml configuration file.

Before you begin

• Create an integration server, as described in “Creating an integration server” on page 168.
• Configure the integration server, by following the instructions in “Configuring an integration server by
modifying the server.conf.yaml file” on page 172.

About this task

All resources that are run by the IBM App Connect Enterprise run time must be located in an application.
Any independent resources (located in an independent resource project), are automatically placed in
the integration server's default application. You can specify the default application when you create the
integration server, by specifying the --default-application-name parameter on the command.
Alternatively, you can specify a default application for an existing integration server, by setting the
defaultApplication property in the integration server's server.conf.yaml configuration file. When
an integration server has been configured to use a default application, independent resources are placed
under the specified default application so that they can be accessed.

Chapter 4. Configuring IBM App Connect Enterprise 181

 Procedure
To configure a default application for an integration server, complete the following steps:
1. Use a YAML editor to open the server.conf.yaml file.
If you do not have access to a YAML editor, you can edit the file by using a plain text editor. However,
you must ensure that you do not include any tab characters, which are not accepted in YAML and
would cause your integration server configuration to fail. If you choose to use a plain text editor,
ensure that you use a YAML validation tool to validate the content of your file.
For more information about working with YAML, see http://www.yaml.org/start.html.
2. Set the defaultApplication property in the Defaults section of the server.conf.yaml file, by
removing the comment (#) from the start of the defaultApplication line and specifying a name for
the default application that will be used by the integration server:

Defaults:
defaultApplication: 'myDefaultApp' # Name a default application under which independent
resources will be placed

3. Restart the integration server. The properties that you set in the server.conf.yaml file take effect
when the integration server is started. If you modify these properties again, you must also start the
integration server again for the subsequent changes to take effect. For more information, see “Starting
an integration server” on page 250.

Configuring the environment to access external applications and

resources
If you are developing message flows that access external resources such as databases, Enterprise
Information Systems, IMS, or email servers, you must set up your environment to support these
applications.

About this task

The topics in this section describe how to configure your environment to support specific applications.
Note: You can also use policies to control certain aspects of message flow and message flow node
behavior at run time. For more information, see “Overriding properties at run time with policies” on page
324.

Configuring databases
Configure databases to hold application or business data that you can access from your message flows.

About this task

Databases that hold application or business data can be read from and written to by nodes within the
message flows that you deploy to one or more integration nodes in your domain.
For more information about the requirement for, and set up of, databases, and the restrictions that apply,
see “Databases overview” on page 1131.
To make databases available, complete the following steps:

Procedure
1. If you want to access databases from your deployed message flows, create and configure the
databases and the connections to them.

182 IBM App Connect Enterprise 12.0: User Guide

2. On distributed platforms, create and configure connections to the databases that you have created:
a) If your message flows use an ODBC connection to a database, enable an ODBC connection for that
database.
Repeat this step for each database that you want to access in this way.
Note that you can use the mqsicvp command as an ODBC test tool; see “Enabling ODBC
connections to the databases” on page 184 for further information.
b) If your message flows use a JDBC connection to a database, enable a JDBC connection for that
database.
Repeat this step for each database that you want to access in this way.

Securing database connections

Set up security for a database connection, whether it is required by the database provider or optional.

Before you begin

• If you are using a JDBC provider, you must first set up the JDBC provider. See Set up your JDBC provider
definition.
• If you are using an ODBC connection, you must first connect to the database. See “Enabling ODBC
connections to the databases” on page 184.

About this task

Some databases require that all access is associated with a known user ID, for others this association is
optional. For example, DB2 requires a data source login name and password on all connections.
Use the mqsisetdbparms command to specify a user ID and password that the integration node can use
to access each database. If a user ID and password have not been specified for database access using the
mqsisetdbparms command, default values for user ID and password are used which are platform specific:
1.
On Windows: The integration node service ID and password that you specified on the
mqsicreatebroker command.
2.
On Linux and UNIX: The user ID mqsiUser and password ******** (these
values are fixed).
Steps for setting up security are specific to the type of database connection that you are using. Choose
your database connection type to see the steps:
• “ODBC connections” on page 183
• “JDBC connections” on page 184

ODBC connections

About this task

If your ODBC data source requires you to define secure access, or if you want to implement security
where this is optional, complete the following steps:

Procedure
1. Identify the user IDs that you want to associate with the database connection, or create a user ID with
a password, following the appropriate instructions for your operating system and database.
2. Define the user IDs and passwords that the integration node can use to access a particular data
source.

Chapter 4. Configuring IBM App Connect Enterprise 183

 3. Run the mqsisetdbparms command to create user IDs and passwords that can be used to access the
data source from an integration node.
Use the following format:

mqsisetdbparms broker_name -n data_source_name -u database_userID -p database_userID_password

4. Optional: If you want to use the same user ID and password for more than one database as a default
set of credentials, you can specify dsn::DSN in the -n parameter, as shown in the following example:

mqsisetdbparms broker_name -n dsn::DSN -u default_userID -p default_password

Results
You have secured access to your ODBC data source.

JDBC connections

About this task

If your database requires you to define secure access, or if you want to implement security where this is
optional, complete the following steps:

Procedure
1. Identify the user ID that you want to associate with the database connection, or create a user ID with a
password, following the appropriate instructions for your operating system and database.
2. Define the user IDs and passwords that the integration node can use for the JDBC connections:
• Use the following command format:

mqsisetdbparms broker_name -n jdbc::security_identity -u userID -p password

For example, if you want a user ID myuserid with a password of secretpw to access a database on
integration node INODE1, run the following command:

mqsisetdbparms INODE1 -n jdbc::mySecurityIdentity -u myuserid -p secretpw

The jdbc:: prefix indicates that the security_identity is to be used for JDBC connections.
• If you want to use the same user ID and password for more than one database as a default set of
credentials, you can specify dsn::DSN in the -n parameter, as shown in the following example:

mqsisetdbparms INODE1 -n jdbc::JDBC -u default_userID -p default default_password

• Update the corresponding Security identity property for the JDBC Providers policy to
associate the connection with the security identity that you have defined (see JDBC Providers policy
(JDBCProviders)).

Results
You have secured access to your JDBC databases. If you need to define user credentials that can be
shared across a business area or account, you can reuse the same security identity that you defined in the
previous steps in different JDBC Providers policies.

Enabling ODBC connections to the databases

Set up the resources and environment that the integration node requires for Open Database Connectivity
(ODBC) connections to databases on distributed systems.

Before you begin

Read the following topic: “Configuring databases” on page 182.

184 IBM App Connect Enterprise 12.0: User Guide

Note: In IBM App Connect Enterprise, you do not need to install the IBM Integration ODBC Database
Extender program to use database nodes in your applications. The program code is installed as part of the
IBM App Connect Enterprise installation.

About this task

You can configure both ODBC and Java Database Connectivity (JDBC) connections for access to
databases:
• To set up ODBC connections to databases, follow the instructions in this section.
Optionally, after configuring the ODBC connection parameters, run the command to verify that the
integration node can connect to the data source, and to provide useful information about the data
source and its interface.On Linux and UNIX systems, this command also checks that the ODBC
environment is set up correctly.
• On Linux and UNIX systems, IBM Integration ODBC Database Extender, which encapsulates unixODBC,
is provided as the driver manager. IBM App Connect Enterprise provides DataDirect ODBC drivers for
interfacing with Oracle, Sybase, and SQLServer databases. For other databases, you must provide the
appropriate ODBC driver.
On Windows, the ODBC driver manager is provided by the operating system. IBM App Connect
Enterprise provides DataDirect ODBC drivers for interfacing with Oracle and Sybase. For other
databases, you must provide the appropriate ODBC driver.
• To set up JDBC connections to databases, see “Enabling JDBC connections to the databases” on page
200.
• On Linux and UNIX systems, delete the ODBCINI64 environment variable if it exists; it is not required
by IBM Integration Bus 10.0. For more information, see “Database connections” on page 1131. The
sample odbc.ini and odbcinst.ini files that are supplied, and the information that is contained in
these configuration topics, include all the connection parameters that are supported for connections
to your databases. Any additional parameters that are provided by your chosen database drivers are
not tested or supported in an IBM App Connect Enterprise environment; consider your requirements
carefully before specifying other parameters in your tailored ODBC .ini files.
To enable connections on distributed systems:

Procedure
Define the ODBC DSNs according to your platform:

On Windows:
Follow the instructions in “Connecting to a database from Windows systems” on page 185.

On Linux and UNIX systems:

For all supported databases, follow the instructions in “Connecting to a database from Linux and UNIX
systems by using the IBM Integration ODBC Database Extender” on page 189.
You have now configured the ODBC DSNs for your databases.

Results
You have now enabled the integration node to make connections to your databases.

Connecting to a database from Windows systems

To enable an integration node to connect to a database, define the ODBC data source name (DSN) for the
database.

Before you begin

Check that you have set up your environment so that the integration node can connect to the database.
Most database managers set up the required environment when you install, but others supply a database

Chapter 4. Configuring IBM App Connect Enterprise 185

 profile that you must run. For information about environments and running database profiles, see
“Running database setup scripts before starting an integration node” on page 83.

About this task

Configure an ODBC data source by using the ODBC Data Source Administrator:
1. Click Start > Control Panel > Administrative Tools > Data Sources (ODBC).
2. Click the System DSN tab and click Add.
3. Complete the steps in the following sections for the databases that you are working with.
If you need more information about a particular database product, see the product-specific
documentation.
DB2 UDB
Define a data source for DB2 UDB:
1. Select the driver IBM DB2 ODBC DRIVER.
2. Enter the data source name (DSN) and description.
3. Select the correct database alias from the list.
4. Click Finish to save your definition.
5. Click OK to close the ODBC Data Source Administrator.
6. If you need to use Global Coordination with your database from IBM App Connect Enterprise on
Windows systems, the next task is to set up the 32-bit environment that is needed by IBM MQ, see
“Setting your environment to support access to databases” on page 200.
You must register the data source as a system data source.
If you prefer, you can use the Configuration Assistant instead of the ODBC Data Source Administrator:
1. Open the DB2 Configuration Assistant.
2. Right-click the database and select Change Database.
3. Select Data Source.
4. Select Register this database for ODBC. Select the system data source option.
5. Click Finish.
6. The Test Connection dialog opens automatically and you can test the various connections.
Informix® Dynamic Server
Define a data source for Informix Dynamic Server:
1. Select the driver IBM INFORMIX ODBC DRIVER.
2. On the Connection tab, specify:
• The Informix server name.
• The server host name.
• The Informix network service name (as defined in the services file).
• The network protocol (for example, olsoctcp).
• The Informix data source name.
• The user identifier to access the data source within.
• The password for that user identifier.
3. Click Apply.
4. Click Test Connection to check your supplied values.
5. Click OK to close the ODBC Data Source Administrator.
Microsoft SQL Server
Define a data source for Microsoft SQL Server:

186 IBM App Connect Enterprise 12.0: User Guide

 1. Select the driver for the version of SQL Server that you are using:
• SQL Native Client 10.0 for SQL Server 2008.
• SQL Native Client 11.0 for SQL Server 2012, 2014, and 2016.
2. Specify a name and description.
3. Select the correct server from the list.
4. To specify the authentication mode that is used by the server:
a. Click Next.
b. Select the authentication mode.
c. Click Back to move back to the first panel.
5. Click Finish to save your definition.
6. Click OK to close the ODBC Data Source Administrator.
Oracle
Define a data source for Oracle:
1. • Select the driver IBM App Connect Enterprise (10.0.0.n) DataDirect
Technologies 64-BIT Oracle Wire Protocol where n is the level of the installed fix
pack.
The ODBC Oracle Driver Setup dialog box opens.
2. On the General tab:
a. Enter the DSN name, description, and host name of the machine where Oracle is running,
the port number on which Oracle is listening, and the Oracle Service Name that you want to
connect to.
3. On the Advanced tab:
a. Select Enable SQLDescribeParam.
b. Select Procedure Returns Results. The resultant ODBC definition in the Windows registry has a
string value that is called ProcedureRetResults with the value 1.
c. Select Login Timeout and set the value to 0.
d. Ensure that Enable N-CHAR is not selected.
e. If you are using TIMESTAMP WITH TIMEZONE columns, select Enable Timestamp With
Timezone.
f. In Extended Options, enter:

WorkArounds=536870912;

Oracle using Secure Socket Layer (SSL) authentication

Complete the steps for Oracle above.
Then, complete these additional steps:
1. Reopen the ODBC Oracle Driver Setup dialog box, see Step 1 for Oracle above.

Chapter 4. Configuring IBM App Connect Enterprise 187

 2. On the Security tab:
a. In the Authentication section, set the Authentication Method to Encrypt Password.
b. In the Encryption Section, set the Encryption Method to SSL Auto.
c. Select the check box if you want to validate the Server certificate.
d. Enter a fully qualified path for your Trust Store.
e. Enter your Trust Store Password.
f. Enter a fully qualified path for your Key Store.
g. Enter your Key Store Password.
h. Enter your SSL Key Password.
3. Click OK to close the ODBC Data Source Administrator.
Oracle using Advanced Security (OAS)
Complete the steps for Oracle above.
Then, complete these additional steps:
1. Reopen the ODBC Oracle Driver Setup dialog box, see Step 1 for Oracle above.
2. On the Advanced Security tab:
a. Select the Encryption Level that you want to use. Choose from the following options:
• 0 - Rejected. If rejected, or no match is found between the driver and server encryption types,
data that is sent between the driver and the database server is not encrypted or decrypted. If
the Oracle server has its sqlnet.encryption_server setting set to "REQUIRED" and this
option is selected, then the connection to the Oracle database fails.
• 1 - Accepted. Encryption is used on data that is sent between the driver and the database
server if the database server requests or requires it.
• 2 - Requested. Data that is sent between the driver and the database server is encrypted and
decrypted if the database server permits it.
• 3 - Required. Data that is sent between the driver and the database server must be encrypted
and decrypted. If the Oracle server has its sqlnet.encryption_server setting set to
"REJECTED" and this option is selected, then the connection to the Oracle database fails.
b. Select the Encryption Types that you want to use.
c. Select the Data Integrity Level you want to use. Choose from the following options:
• 0 - Rejected. A data integrity check on data that is sent between the driver and the database
server is refused. If the Oracle server has its sqlnet.crypto_checksum setting set to
"REQUIRED" and this option is selected, then the connection to the Oracle database fails.
• 1 - Accepted. A data integrity check can be made on data that is sent between the driver and
the database server. Data integrity is used if the database server requests or requires it.
• 2 - Requested. The driver enables a data integrity check on data that is sent between the
driver and the database server if the database server permits it.
• 3 - Required. A data integrity check must be performed on data that is sent between the
driver and the database server. If the Oracle server has its sqlnet.crypto_checksum
setting set to "REJECTED" and this option is selected, then the connection to the Oracle
database fails.
d. Select the Data Integrity Types that you want to use.
3. Click OK to close the ODBC Data Source Administrator.
Sybase Adaptive Server Enterprise
Define a data source for Sybase Adaptive Server Enterprise:

188 IBM App Connect Enterprise 12.0: User Guide

 1. • Select the driver IBM App Connect Enterprise (10.0.0.n) DataDirect
Technologies 64-BIT Sybase Wire Protocol where n is the level of the installed fix
pack.
2. Enter the DSN name, description, and network address of the server, where the network address is
made up of MyHostMachineName,MyHostMachinePortNumber.
3. On the Advanced tab:
• Select Enable Describe Parameter.
• Select Login Timeout and set the value to 0.
• In Extended Options, enter:

TimestampTruncationBehavior=1;EnableSPColumnTypes=2;XAConnOptBehavior=3;

4. On the Performance tab:

• Ensure that the Prepare Method setting is 1 - Partial.
solidDB
Define a data source for solidDB:
1. Select the driver IBM solidDB - (Unicode) DRIVER.
2. Enter the description.
3. Enter the communication port in the network location field, for example, tcp 2315.
4. Click Finish to save your definition.
5. Click OK to close the ODBC Data Source Administrator.

Results
You have now configured your ODBC data source names on Windows.

Connecting to a database from Linux and UNIX systems by using the IBM Integration
ODBC Database Extender
IBM Integration ODBC Database Extender encapsulates the unixODBC driver manager. You must set up
and configure the integration node to use it.

Before you begin

The following information applies to all supported databases.
• Read the information about the unixODBC Project.
• Create the database.
• Ensure that your database is set up so that the integration node is authorized to access the database.
• Check that you have set up your environment so that the integration node can access the database. You
might have to run a database profile that is supplied by the database vendor. For more information, see
“Running database setup scripts before starting an integration node” on page 83.
You do not need to install the IBM Integration ODBC Database Extender program to use database nodes
in your applications. The program code is installed as part of the IBM App Connect Enterprise installation.

Procedure
1. Copy the odbc.ini sample file that is supplied in the install_dir/server/ODBC/unixodbc/
directory to a location of your choice.
Each integration node service user ID on the system can therefore use its own data source name
(DSN) definitions.
Note: To prevent problems with the backup and restore procedures, store the copy of the sample file
in the /var/mqsi directory, rather than the home directory for your user ID.

Chapter 4. Configuring IBM App Connect Enterprise 189

 2. Ensure that your copy of the odbc.ini file is owned by the mqbrkrs group, and has 664
permissions.
3. Set the ODBCINI environment variable to point to your copy of the odbc.ini file, specifying a full
path and file name. Ensure that you point to the copy of the file; do not point to the odbc.ini file in
the installation directory.
4. Copy the odbcinst.ini sample file that is supplied in the install_dir/server/ODBC/
unixodbc/ directory to a location of your choice. See the Note in step 1.
5. Ensure that your copy of the odbcinst.ini file is owned by the mqbrkrs group and has 664
permissions.
6. Set the ODBCSYSINI environment variable to point to the directory that contains your copy of the
odbcinst.ini file, specifying a full path name. Ensure that you point to the directory containing the
copy; do not point to the directory containing the odbcinst.ini file in the installation directory.
7. If you are using the Data Server driver for ODBC that is supplied as part of App Connect Enterprise:
a) Copy the db2cli.ini sample file that is supplied in the install_dir/server/ODBC/
unixodbc/ directory to a location of your choice.
b) Ensure that your copy of the db2cli.ini file is owned by the mqbrkrs group, and that it has 664
permissions.
c) Set the DB2CLIINIPATH environment variable to point to the directory that contains your
copy of the db2cli.ini file, specifying a full path name. Ensure that you point to the
directory containing the copy; do not point to the directory containing the db2cli.ini file in the
installation directory.
8. If you are connecting directly to DB2 server, solidDB, or Informix databases, set the library search
path environment variable to show the location of the libraries for the database manager that you are
using. This step is not required if you are using the Data Server driver for ODBC that is supplied as
part of App Connect Enterprise.
For more information about the library search path, ask your database administrator (DBA), or see
the documentation for your database manager.
The library search path environment variable depends on your platform:
•
On Linux, set LD_LIBRARY_PATH.
•
On AIX, set LIBPATH.
Updates to the library search path are not required for other supported databases.
9. If you are using a DB2 database instance that is installed on AIX, a single process can make a
maximum of 10 connections that use shared memory to a DB2 database. Use TCP/IP mode to
connect to the database instance.
10. Edit the final stanza in the odbc.ini file (the [ODBC] stanza), to specify the location of the installed
DataDirect ODBC drivers.
To ensure that you edit the correct odbc.ini file, you can open the file in the vi text editor by using
the following command:

vi $ODBCINI

a) In the InstallDir field, add the IBM App Connect Enterprise installation location to complete
the fully qualified path to the ODBC directory.
Ensure that the path points to the ODBC directory in the IBM App Connect Enterprise installation
location. If you do not specify this value correctly, the ODBC definition will not work.
b) Accept the default values shown in the sample odbc.ini file for all the other entries in the
stanza.
For example, on AIX:

;##########################################
;###### Mandatory information stanza ######

190 IBM App Connect Enterprise 12.0: User Guide

 ;##########################################

[ODBC]
InstallDir=/usr/opt/IBM/mqsi/11.0.0.2/server/ODBC/drivers
UseCursorLib=0
IANAAppCodePage=4
UNICODE=UTF-8

11. Edit the first stanza in the odbc.ini file (the [ODBC Data Sources] stanza) to list the DSN of each
database.
For example, on AIX:

;##########################################
;###### List of data sources stanza #######
;##########################################
[ODBC Data Sources]
DB2DB=IBM DB2 ODBC Driver
DB2DSDB=IBM DB2 using the Data Server driver included in ACE
ORACLEDB=DataDirect ODBC Oracle Wire Protocol
ORACLERACDB=DataDirect ODBC Oracle RAC Wire Protocol
ORACLESSLDB=DataDirect ODBC Oracle SSL Wire Protocol
SYBASEDB=DataDirect ODBC Sybase Wire Protocol
SYBASEDBUTF8=DataDirect ODBC Sybase UTF8 Wire Protocol
SQLSERVERDB=DataDirect ODBC SQL Server Wire Protocol
INFORMIXDB=IBM Informix ODBC Driver
SOLIDDB_DB=IBM Solid DB ODBC Driver

List all your DSNs in your odbc.ini file, regardless of the database manager. You can define multiple
DSNs to resolve to the same database; however, if you are using global coordination of transactions
with an Oracle database, do not use this option because it might cause data integrity problems.
12. For each database that you listed in the [ODBC Data Sources] stanza in the odbc.ini file, create a
data source stanza in the odbc.ini file. The entries in the stanza depend on the database manager.
For a DB2 database instance:
a. In the Driver field:
• If you are directly connecting to a DB2 server, add the full path of your DB2 installation.
• If you are using the Data Server driver for ODBC supplied with App Connect Enterprise,
ensure that the path points to the driver file in the App Connect Enterprise installation
location.
b. In the Description field, type a meaningful description of the database. This field is for
information only and does not affect the connection.
c. In the Database field, type the DB2 alias. The data source name must be the same as the
database alias name. If you are using a remote DB2 database, you must set up your client/
server connection to resolve this alias to the correct database. For more information, see the
DB2 documentation.
If the requirement is to have multiple stanzas that refer to the same DB2 database, aliases
must be created in DB2 by using the DB2 CATALOG command. These aliases can then have
their own stanza in the odbc.ini file.
The odbc.ini file cannot be used to set up aliases for DB2.
For example, connecting directly to a DB2 server on AIX:

;# DB2 stanza
[MYDB2DB]
DRIVER=/opt/IBM/db2/V11.1/lib64/db2o.o
Description=IBM DB2 ODBC Database
Database=MYDB2DB

Connecting directly to a DB2 server on Linux systems:

;# DB2 stanza
[MYDB2DB]
DRIVER=/opt/IBM/db2/V11.1/lib64/libdb2o.so
Description=IBM DB2 ODBC Database

Chapter 4. Configuring IBM App Connect Enterprise 191

 Database=MYDB2DB

Connecting to DB2 using the Data Server Driver on Linux Systems:

;# DB2 using DataServer driver included in ACE

[MYDB2DB]
DRIVER=/usr/opt/IBM/mqsi/11.0.0.11/server/ODBC/dsdriver/odbc_cli/clidriver/lib/
libdb2o.so
Description=IBM DB2 ODBC Database
Database=MYDB2DB

For an Oracle database:

For all platforms:
a. In the Driver field, ensure that the path points to the driver file in the IBM App Connect
Enterprise installation location, as shown in the following example.
b. In the Description field, type a meaningful description of the database. This field is for
information only and does not affect the connection.
c. In the HostName field, type the name or IP address of the machine that is hosting your Oracle
system.
d. In the PortNumber field, type the number of the port on which your Oracle server is listening
on the machine that you specified in the HostName field.
e. In the ServiceNamefield, type the Oracle service name that you want to connect to on the
system you specified in the HostName field.
f. If you are using TIMESTAMP WITH TIMEZONE columns, uncomment the
EnableTimestampwithTimezone setting.
g. Accept the default values shown in the sample odbc.ini file for all the other entries in the
stanza.
For example, on AIX:

;# Oracle stanza
[MYORACLEDB]
Driver=/usr/opt/IBM/mqsi/11.0.0.2/server/ODBC/drivers/lib/UKora95.so
Description=DataDirect ODBC Oracle Wire Protocol
HostName=my-machine.hursley.ibm.com
PortNumber=1521
ServiceName=my-oracle-service
CatalogOptions=0
EnableStaticCursorsForLongData=0
ApplicationUsingThreads=1
EnableDescribeParam=1
OptimizePrepare=1
WorkArounds=536870912
ProcedureRetResults=1
ColumnSizeAsCharacter=1
LoginTimeout=0
EnableNcharSupport=0
;# Un-comment the next setting if you wish to use Oracle TIMESTAMP WITH TIMEZONE
columns

192 IBM App Connect Enterprise 12.0: User Guide

 ;# EnableTimestampwithTimezone=1

For an Oracle database that uses Real Application Clusters:

For all platforms:
a. In the Driver field, ensure that the path points to the driver file in the IBM App Connect
Enterprise installation location, as shown in the following example.
b. In the Description field, type a meaningful description of the database. This field is for
information only and does not affect the connection.
c. In the HostName field, type the name or IP address of the machine that is hosting your
primary (preferred) Oracle instance.
d. In the PortNumber field, type the number of the port on which your Oracle server is listening
on the machine that you specified in the HostName field.
e. In the ServiceName field, type the Oracle Real Application Cluster service name that you
want to connect to on the system that you specified in the HostName field.
f. If you are using TIMESTAMP WITH TIMEZONE columns, uncomment the
EnableTimestampwithTimezone setting.
g. In the AlternateServers field, provide a list of alternative locations for this service for
situations when the primary location, which is defined in HostName, is unavailable. Each
location specification consists of three parts, which are separated by colons. Enter these
values as one continuous string; the text in this example has been split to improve readability.

HostName=<Alternative host name>

:PortNumber=<Oracle listner port on alternative server>
:ServiceName=<Service name on the alternative server>

If you want to specify more than one AlternateServer, separate each additional location
specification with a comma. Whenever a new database connection is required, for example
after an Oracle instance failover, the primary location will be tried first. However, if the primary
location is unavailable, the driver will try the list of alternative locations in turn.
h. Accept the default values shown in the sample odbc.ini file for all the other entries in the
stanza.
For example, on AIX:

;# Oracle Real Application Clusters stanza

[MYORACLERACDB]
Driver=/usr/opt/IBM/mqsi/11.0.0.2/server/ODBC/drivers/lib/UKora95.so
Description=DataDirect ODBC Oracle RAC Wire Protocol
HostName=my-primary-machine.hursley.ibm.com
PortNumber=1521
ServiceName=my-oracle-rac-service
;#This shows one alternate server definition. Add extra ones using a ',' to seperate
each definition.
AlternateServers=(HostName=my-first-backup-
machine.hursley.ibm.com:PortNumber=1521:ServiceName=my-
oracle-rac-first-backup-service,HostName=my-second-backup-
machine.hursley.ibm.com:PortNumber=1521:ServiceName=my-oracle-rac-second-backup-
service)
CatalogOptions=0
EnableStaticCursorsForLongData=0
ApplicationUsingThreads=1
EnableDescribeParam=1
OptimizePrepare=1
WorkArounds=536870912
ProcedureRetResults=1
ColumnSizeAsCharacter=1
LoginTimeout=0
EnableNcharSupport=0
;# Un-comment the next setting if you wish to use Oracle TIMESTAMP WITH TIMEZONE
columns

Chapter 4. Configuring IBM App Connect Enterprise 193

 ;# EnableTimestampwithTimezone=1

For an Oracle database that uses Secure Socket Layer (SSL):

For all platforms:
a. In the Driver field, ensure that the path points to the driver file in the IBM App Connect
Enterprise installation location, as shown in the following example.
b. In the Description field, type a meaningful description of the database. This field is for
information only and does not affect the connection.
c. In the HostName field, type the name or IP address of the machine that is hosting your
primary (preferred) Oracle instance.
d. In the PortNumber field, type the number of the port on which your Oracle server is listening
for SSL connections on the machine you specified in HostName.
e. In the ServiceName field, type the Oracle SSL service name that you want to connect to on
the system you specified in the HostName field.
f. If you are using TIMESTAMP WITH TIMEZONE columns, uncomment the
EnableTimestampwithTimezone setting.
g. In the KeyPassword field, type your SSL key password.
h. In the KeyStore field, type the fully qualified name of your SSL key store.
i. In the KeyStorePassword field, type your SSL key store password.
j. In the TrustStore field, type the fully qualified name of your SSL trust store.
k. In the TrustStorePassword field, type your SSL trust store password.
l. In the EncryptionMethod field, type the method to use to encrypt data sent between the
driver and the database server. Valid values are as follows:
• 0 No encryption. This value is the default.
• 1 SSL. If the server supports protocol negotiation, the driver and server negotiate the use
of the SSL protocols specified in the CryptoProtocolVersion connection option.
• 3 SSL3.
• 4 SSL2.
• 5 TLS1.
m. If the EncryptionMethod has been set to 1, use CryptoProtocolVersion to specify
a comma-separated list of the cryptographic protocols to use. Valid protocols are TLSv1.2,
TLSv1.1, TLSv1, SSLv3 and SSLv2. When multiple protocols are specified, the driver uses the
highest version supported by the server. The default value is TLSv1.2, TLSv1.1, TLSv1.
n. In the ValidateServerCertificate field, type 1 to enable validation of the certificate
that is sent by the database server when SSL encryption is enabled.
o. Accept the default values shown in the sample odbc.ini file for all the other entries in the
stanza.
For example, on AIX:

;# Oracle using SSL stanza

[MYORACLESSLDB]
Driver=/usr/opt/IBM/mqsi/11.0.0.2/server/ODBC/drivers/lib/UKora95.so
Description=DataDirect ODBC Oracle Wire Protocol
HostName=my-machine.hursley.ibm.com
PortNumber=2484
ServiceName=my-oracle-ssl-service
CatalogOptions=0
EnableStaticCursorsForLongData=0
ApplicationUsingThreads=1
EnableDescribeParam=1
OptimizePrepare=1
WorkArounds=536870912
ProcedureRetResults=1
ColumnSizeAsCharacter=1
LoginTimeout=0

194 IBM App Connect Enterprise 12.0: User Guide

 AuthenticationMethod=1
KeyPassword=my-password
KeyStore=/Development/ssl/my-store.p12
KeyStorePassword=my-password
TrustStore=/Development/ssl/my-store.p12
TrustStorePassword=my-password
EncryptionMethod=1
CryptoProtocolVersion=TLSv1.2
ValidateServerCertificate=1
EnableNcharSupport=0
;# Un-comment the next setting if you wish to use Oracle TIMESTAMP WITH TIMEZONE
columns
;# EnableTimestampwithTimezone=1

For an Oracle database that uses Advanced Security (OAS):

For all platforms:
a. In the Driver field, ensure that the path points to the driver file in the IBM App Connect
Enterprise installation location, as shown in the following example.
b. In the Description field, type a meaningful description of the database. This field is for
information only and does not affect the connection.
c. In the HostName field, type the name or IP address of the machine that is hosting your Oracle
system.
d. In the PortNumber field, type the number of the port on which your Oracle server is listening
on the machine you specified in HostName.
e. In the ServiceName field, type the Oracle service name that you want to connect to on the
system that you specified in the HostName field.
f. If you are using TIMESTAMP WITH TIMEZONE columns, uncomment the
EnableTimestampwithTimezone setting.
g. In the EncryptionLevel field, enter the level of encryption that you are using. Choose one
value from the following options:
• 0 - Rejected. If rejected, or no match is found between the driver and server encryption
types, data that is sent between the driver and the database server is not encrypted or
decrypted. If the Oracle server has its sqlnet.encryption_server setting set to
"REQUIRED" and this option is selected, then the connection to the Oracle database fails.
• 1 - Accepted. Encryption is used on data that is sent between the driver and the database
server if the database server requests or requires it.
• 2 - Requested. Data that is sent between the driver and the database server is encrypted
and decrypted if the database server permits it.
• 3 - Required. Data that is sent between the driver and the database server must be
encrypted and decrypted. If the Oracle server has its sqlnet.encryption_server
setting set to "REJECTED" and this option is selected, then the connection to the Oracle
database fails.
h. In the DataIntegrityLevel field, choose one value from the following options:
• 0 - Rejected. A data integrity check on data that is sent between the driver and the database
server is refused. If the Oracle server has its sqlnet.crypto_checksum setting set to
"REQUIRED" and this option is selected, then the connection to the Oracle database fails.
• 1 - Accepted. A data integrity check can be made on data that is sent between the driver and
the database server. Data integrity is used if the database server requests or requires it.
• 2 - Requested. The driver enables a data integrity check on data that is sent between the
driver and the database server if the database server permits it.
• 3 - Required. A data integrity check must be performed on data that is sent between the
driver and the database server. If the Oracle server has its sqlnet.crypto_checksum

Chapter 4. Configuring IBM App Connect Enterprise 195

 setting set to "REJECTED" and this option is selected, then the connection to the Oracle
database fails.
i. Accept the default values shown in the sample odbc.ini file for all the other entries in the
stanza.
For example, on AIX:

;# Oracle using SSL stanza

[MYORACLEOASDB]
Driver=/usr/opt/IBM/mqsi/11.0.0.2/server/ODBC/drivers/lib/UKora95.so
Description=DataDirect ODBC Oracle Wire Protocol
HostName=my-machine.hursley.ibm.com
PortNumber=1586
ServiceName=my-oracle-oas-service
CatalogOptions=0
EnableStaticCursorsForLongData=0
ApplicationUsingThreads=1
EnableDescribeParam=1
OptimizePrepare=1
WorkArounds=536870912
ProcedureRetResults=1
ColumnSizeAsCharacter=1
LoginTimeout=0
EncryptionTypes=AES128,AES192,AES256,RC4_40,RC4_56,RC4_128,RC4_256,DES,3DES112,3DES168
EncryptionLevel=3
DataIntegrityTypes=SHA1,MD5
DataIntegrityLevel=3
EnableNcharSupport=0
;# Un-comment the next setting if you wish to use Oracle TIMESTAMP WITH TIMEZONE
columns
;# EnableTimestampwithTimezone=1

For a Sybase database:

For all platforms except Linux on Z:
a. In the Driver field, ensure that the path points to the driver file in the IBM App Connect
Enterprise installation location, as shown in the following example.
b. In the Description field, type a meaningful description of the database. This field is for
information only and does not affect the connection.
c. In the Database field, type the name of the database to which you want to connect by
default. If you do not specify a value, the default value is the database that is defined by your
system administrator for each user.
d. In the NetworkAddress field, type the network address of your Sybase ASE server (this
address is required for local and remote databases). Specify an IP address or server name, in
the following format:

Your Sybase server name or IP address,Your Sybase port number

For example:

Sybaseserver,5000

You can also specify the IP address directly; for example:

199.226.224.34,5000

You can find the port number in the Sybase interfaces file, which is named interfaces.
e. Accept the default values shown in the sample odbc.ini file for all the other entries in the
stanza.
For example, on AIX:

;# Sybase Stanza
[MYSYBASEDB]
Driver=/usr/opt/IBM/mqsi/11.0.0.2/server/ODBC/drivers/lib/UKase95.so
Description=DataDirect ODBC Sybase Wire Protocol
Database=SYBASEDB1
ApplicationUsingThreads=1

196 IBM App Connect Enterprise 12.0: User Guide

 EnableDescribeParam=1
OptimizePrepare=1
SelectMethod=0
NetworkAddress=my-machine.hursley.ibm.com:4100
SelectUserName=1
ColumnSizeAsCharacter=1
EnableSPColumnTypes=2
LoginTimeout=0
TimestampTruncationBehavior=1
XAConnOptBehavior=3

If you want to use a UNICODE UTF8 Sybase data source, add the following line to the end of
your Sybase stanza:

Charset=UTF8

For remote access to an SQL Server database

For all platforms:
a. In the Driver field, add the IBM App Connect Enterprise installation location to complete the
fully qualified path to the driver shown in the sample odbc.ini file.
b. In the Description field, type a meaningful description of the database. This field is for
information only and does not affect the connection.
c. In the Database field, type the name of the database to which you want to connect by
default. If you do not specify a value, the default value is the database that is defined by your
system administrator for each user.
d. In the HostName field, type the name or IP address of the server to which you want to
connect.
e. In the PortNumber field, type the number of the port of the server listener.
f. To specify a named instance of SQL Server, replace the HostName and PortNumber lines with
HostName=Your SQLServer Machine Name\Your SQLServer Instance Name
g. Accept the default values shown in the sample odbc.ini file for all the other entries in the
stanza.
For example, on AIX:

;# UNIX to SQLServer stanza

[MYSQLSERVERDB]
Driver=/usr/opt/IBM/mqsi/11.0.0.2/server/ODBC/drivers/lib/UKsqls95.so
Description=DataDirect ODBC SQL Server Wire Protocol
Database=SQLSERVERDB
HostName=my-machine.hursley.ibm.com
PortNumber=1433
AnsiNPW=1
LoginTimeout=0
QueryTimeout=0
;# To specify a named instance of SQL Server replace the HostName and PortNumber
lines with
;# HostName=<Your SQLServer Machine Name>\<Your SQLServer Instance Name>

;# To use Integrated Windows Authentication, reinstate the following line:

;# AuthenticationMethod=9

Chapter 4. Configuring IBM App Connect Enterprise 197

 ;# Domain=<Your Windows Domain Name>

h. If you want to use Integrated Windows Authentication (IWA) for access to the remote SQL
Server database, reinstate and complete the lines at the end of the stanza.
For an Informix database:
a. In the Driver field, add the full path of your Informix Client library.
b. In the Description field, type a meaningful description of the database. This field is for
information only and does not affect the connection.
c. In the ServerName field, type the name of the Informix IDS server.
d. In the Database field, type the name of the database to which you want to connect by
default. If you do not specify a value, the default value is the database that is defined by your
system administrator for each user.
For example, on AIX:

;# Informix Stanza
[MYINFORMIXDB]
Driver=/opt/IBM/informix/lib/cli/iclit09b.so
Description=IBM Informix ODBC Database
ServerName=my-machine
Database=MYDB

For a solidDB database:

For all platforms except Linux on POWER and Linux on Z:
Client side
odbc.ini file
a. In Driver, add the full path of your solidDB Client library.
b. In Description, type a meaningful description of the database. This field is for information
only and does not affect the connection.
c. In Database, type the name of the database to which you want to connect by default. If
you do not specify a value, the default value is the database that is defined by your system
administrator for each user.
For example, on AIX:

;# SolidDB Stanza
[SOLID_DB]
Driver=/opt/solidDB/bin/soca5x6465.so
Description=IBM Solid DB ODBC database

198 IBM App Connect Enterprise 12.0: User Guide

 Database=SOLIDDB_DB

Note: all additional information is ignored.

solid.ini file
a. This configuration file is located in the directory that is referenced by the environment variable
SOLIDDIR.
b. The solid.ini mapping is from the data source name (as defined in ODBCINI) to the
solidDB connection string.
c. The connection string takes the form <logical name of the driver> = <physical solidDB connect
string>.
d. The Physical connection string specifies the:
• Protocol
• Machine name or IP address
• Port number to use
For example, on AIX:

[Data Sources]
SOLIDDB_DB=tcp my_aix_system 1964

Server side
solid.ini file
a. This configuration file is located in the installation directory for solidDB.
b. Set the Data Source as for the Client side solid.ini file.
c. Set Listen to where the listener for the server is located.
d. Set CharPadding=yes and NumericPadding=yes to turn on padding.
For example, on AIX:

[Data Sources]
SOLIDDB_DB=tcp my_aix_system 1964

[COM]
Listen=tcpip 1964

[SQL]
CharPadding=yes
NumericPadding=yes

13. Ensure that you have edited all necessary parts of all of the relevant .ini files:
• The [ODBC Data Source] stanza at the top of the odbc.ini file.
• A stanza for each data source in the odbc.ini file.
• The [ODBC] stanza at the end of the odbc.ini file.
• Additionally, for solidDB, both the client and server-side solid.ini files.
If you do not configure all parts correctly, the ODBC DSNs do not work and the integration node is
unable to connect to the database.
14. Optional: On AIX, database connect times can sometimes take marginally longer than on Linux
platforms due to the IBM Integration ODBC Database Extender searching for unicode conversion
libraries that do not typically exist on AIX. To prevent this automatic search, you can set the following
property in the [ODBC] stanza of the odbcinst.ini file:

IconvEncoding=UCS-2

Chapter 4. Configuring IBM App Connect Enterprise 199

 Results
You have now configured database connections on Linux and AIX. You can check that the ODBC
environment is configured correctly by running the mqsicvp command. For more information, see
command.

Setting your environment to support access to databases

When you have configured your ODBC data source names (DSNs), you must also configure the
environment so that you can issue console commands, and the integration node that you start can access
the required database libraries. For example, if you have a DB2 database, you must add the DB2 client
libraries to your library search path.

About this task

1. On Windows platforms, the environment is typically set up for you when you install the database
product, and no further action is required. However, some database managers provide a database
profile that you must run to enable the connection from the integration node; for further information,
see “Running database setup scripts before starting an integration node” on page 83.

1. On Linux and UNIX systems, run a profile for each database you want to access. For example, on DB2
you must run db2profile; other database vendors have similar profiles. For further information, see
“Running database setup scripts before starting an integration node” on page 83.

Enabling JDBC connections to the databases

Configure connections to a database through a JDBC Providers policy.

About this task

Use a JDBC connection from Java programs that are associated with a JavaCompute node or a user-
defined node that is written in Java.
You must also set up JDBC connections if your message flows include graphical data maps with one
or more database transforms to be run from a Mapping node, or if they include DatabaseRetrieve or
DatabaseRoute nodes.
If you configure a JDBC type 4 connection from an application running on a Linux, UNIX, or Windows
system, you can configure your integration node and queue manager to include interactions with the
databases in globally-coordinated transactions. On z/OS, JDBC connections can be coordinated only by
the integration node.
The information provided in this section is independent of whether your operating systems, integration
nodes, integration servers, queue managers, and databases operate in 32-bit or 64-bit mode, except
where stated.
When you write Java classes for a JavaCompute node or a user-defined node, your code must comply
with the following restrictions:
• Do not include any code that performs a COMMIT or a ROLLBACK function.
• Do not close the connection to the database. The integration node manages all connections, and closes
a connection if it is idle for approximately one minute, or if the message flow completes.
To configure JDBC type 4 connections:

Procedure
1. Set up your JDBC provider definition.
2. Optional: Set up security.

200 IBM App Connect Enterprise 12.0: User Guide

3. Optional: If your integration node is running on a Windows system, authorize access to JDBCProvider
resources.

What to do next
If you have been following the instructions in “Working with databases” on page 1130 or Mapping
database content, the next task is “Setting up a JDBC provider for type 4 connections” on page 201.
When you have completed configuration of the databases, add or modify Java code in your JavaCompute
or user-defined nodes to access the database that is identified in the JDBC Providers policy.

Setting up a JDBC provider for type 4 connections

Use a JDBC Providers policy to configure a JDBC provider service.

Before you begin

• See the following information: “Creating an integration node” on page 114.
• Create the database by following the database documentation.

About this task

When you include a DatabaseRetrieve, DatabaseRoute, JavaCompute, Mapping, or Java user-defined
node in a message flow, and interact with a database in that node, the integration server must establish a
connection with the database to fulfill the operations that are performed by the node. You must define a
JDBC Providers policy to provide the integration server with the information that it needs to complete the
connection.
Important: When naming your JDBC Providers policy, consider the following requirements:
• If you want to use your JDBC Providers policy with a JavaCompute node, or with a Java user-
defined node, the name of your policy must match the datasourceName parameter in the
getJDBCType4Connection(), provided that the policy is in the default policy project. If the policy
is not in the default policy project, you must specify the policy and policy project name in the format
{policyProjectName}:PolicyName.
• If you want to use your JDBC Providers policy with a Mapping node, the name of your policy must
match the database name that is used by the database transforms in your Graphical Data Map. For each
database transform, the database name is determined by the database definition (.dbm file) in the Data
Design project that was used to create the map. The JDBC Providers policy must be deployed in the
default policy project; for more information, see “Configuring a default policy project” on page 329.
• If you want to use your JDBC Providers policy with a DatabaseRetrieve node, or with a DatabaseRoute
node, the name of your policy must match the value of the Data source name property of the node.
The JDBC Providers policy must be deployed in the default policy project; for more information, see
“Configuring a default policy project” on page 329.
A JDBC Providers policy supports connections to one database only; you must create a policy for each
database that your nodes or Java applications connect to.
To set up a JDBC provider for type 4 connections, complete the following steps.

Procedure
1. Identify the type of database for which you require a JDBC Providers policy.
Supported JDBC drivers and databases are shown in IBM App Connect Enterprise system
requirements; support for globally coordinated (XA) transactions is restricted on some platforms and
for some databases.
2. Use the Policy editor in the IBM App Connect Enterprise Toolkit to create a JDBC Providers policy and
choose the template for your chosen database type (see “Creating policies with the IBM App Connect
Enterprise Toolkit” on page 327).

Chapter 4. Configuring IBM App Connect Enterprise 201

 3. The template provides some default values, but you must change some of them to create a viable
definition.
For example, the Database name property is mandatory, but is initially empty (see JDBC Providers
policy (JDBCProviders)).
The following values and order of preference are used by the integration server to substitute the user
ID and password in the pattern:
a. First, on all platforms: The user ID and password that you have set for the specific database, by
using the mqsisetdbparms and specifying the database in the -n parameter.
b. Second, on all platforms: The user ID and password that you have set for all other databases, by
using the mqsisetdbparms and specifying jdbc::JDBC in the -n parameter.
c. Third, the values are platform-specific:
i)
On Windows: The integration node service ID and password that you specified on the
mqsicreatebroker command.
ii)
On Linux and UNIX: The user ID mqsiUser and password ********
(these values are fixed).
4. When you have created your JDBC Providers policy, you must deploy it to any integration server where
you will deploy the message flows that will use this policy. You can deploy the policy project directly to
an integration server.

What to do next
If required, set up security for the JDBC connection, set up the environment to include the JDBC Providers
policy in globally coordinated transactions, or both.

Configuring a JDBC type 4 connection for globally coordinated transactions

If you want the database that you access through a JDBC type 4 connection to participate in globally
coordinated transactions, set up the appropriate environment.

Before you begin

Set up your JDBC provider definition.

About this task

On distributed systems, an IBM MQ queue manager associated with the integration node performs the
transaction manager role, which means that IBM App Connect Enterprise requires access to IBM MQ
when processing messages. For more information about using IBM MQ with IBM App Connect Enterprise,
see “Installing IBM MQ” on page 96.
Updates that you make to a database across a JDBC type 4 connection can be coordinated with other
actions taken within the message flow, if you set up the resources to support coordination.
Complete the following steps:

202 IBM App Connect Enterprise 12.0: User Guide

Procedure
1. Check that the definition of your JDBC Providers policy is appropriate for coordinated transactions.
For example, to set up the required JDBC classes:
• For DB2, set JDBC type 4 data source class name to
com.ibm.db2.jcc.DB2XADataSource and JDBC driver class name to
com.ibm.db2.jcc.DB2Driver.
• For Oracle, set JDBC type 4 data source class name to
oracle.jdbc.xa.client.OracleXADataSource and JDBC driver class name to
oracle.jdbc.OracleDriver.
Consult your database administrator or the documentation provided by your database supplier, to
confirm that all the JDBC Providers policy properties are set appropriately. For example, a database
supplier might require secure access if it is participating in coordinated transactions.
2. Define the switch file and the database properties:
a) The JDBC switch file is supplied by IBM App Connect Enterprise, and uses static XA registration
(see “Configuring databases for global coordination of transactions” on page 704).
b)
On Linux and UNIX systems, open the qm.ini file for the integration node queue manager with a
text editor. Add the following stanza for each database:

XAResourceManager:
Name=Database_Name
SwitchFile=JDBCSwitch
XAOpenString=JDBC_DataSource
ThreadOfControl=THREAD

Database_Name is the database name (DSN) of the database defined to the JDBC Providers policy.
JDBCSwitch is a fixed generic name that represents the switch file for XA coordination. Use this
value, or another single fixed value, in each stanza; the specific switch file that the queue manager
uses is defined by the symbolic links you create in the next step.
JDBC_DataSource is the identifier of the JDBC Providers policy.
Define a stanza for each database (DSN) that you connect to from this integration server. You must
create separate definitions even if the DSNs resolve to the same physical database. Therefore, you
must have a stanza for each JDBC Providers policy that you have defined, because each service can
define the properties for a single database.
c)
On Windows, open IBM MQ Explorer and select the queue manager, for example BROKERQM.
Open the XA resource manager page, and modify the attributes to create the definition of the
database. The attributes are the same as those shown for Linux and UNIX; Name, SwitchFile,
XAOpenString, and ThreadofControl. Leave the additional attribute, XACloseString, blank.
Enter JDBCSwitch in SwitchFile.
3. Set up queue manager access to the switch file:
a)
On Linux and UNIX systems, create a symbolic link to the switch files that are supplied in your
install_dir/server/lib directory.
install_dir is the directory to which you installed IBM App Connect Enterprise. The default
location for this directory is install_dir/ace-12.0.n.0/server on Linux, or /opt/IBM/

Chapter 4. Configuring IBM App Connect Enterprise 203

 mqsi/12.0.n.0/server on UNIX systems. The default directory includes the version, release,
modification, and fix of the product, in the format v.r.m.f (version.release.modification.fix).
Set up links in the /var/mqm/exits64 directory. The file name for all platforms is
libJDBCSwitch.so.
Specify the same name of the switch file, JDBCSwitch or your own value, in the /exits64
directory. For example, on AIX:

ln -s install_dir/server/lib/libJDBCSwitch.so /var/mqm/exits64/JDBCSwitch

b)
On Windows, copy the JDBCSwitch32.dll file from the install_dir\server\bin
directory to the \exits subdirectory in the IBM MQ installation directory, and rename the file to
JDBCSwitch.dll. Then, copy the JDBCSwitch.dll file from the install_dir\server\bin
directory to the \exits64 subdirectory in the IBM MQ installation directory.
4. Configure the message flow that includes one or more nodes that access databases that are to
participate in a globally coordinated transaction.
a) Open an IBM App Connect Enterprise Toolkit session.
b) Switch to the Integration Development perspective.
c) Add the message flow that includes the node or nodes that connect to the database that is to
participate in a globally coordinated transaction to a new or existing BAR file.
d) Build the BAR file.
e) Click the Configure tab, select the message flow that you have added, and select the Coordinated
Transaction check box.

What to do next
If your integration node is running on Windows, authorize the queue manager to access resources that
are associated with the JDBC Providers policy (see “Authorizing access to JDBC type 4 JDBCProvider
resources on Windows” on page 204).
If you have been following the instructions in “Working with databases” on page 1130, the next task is
“Configuring ODBC connections for globally coordinated transactions” on page 708 (optional).

Authorizing access to JDBC type 4 JDBCProvider resources on Windows

Authorize the integration node and queue manager to access shared resources that are associated with
the JDBCProvider. This task is required only if you want the database updates to be included in globally
coordinated transactions on Windows systems.

Before you begin

Set up your JDBC provider definition.

About this task

On distributed systems, an IBM MQ queue manager provides the coordinated transaction support, which
means that IBM App Connect Enterprise must have access to IBM MQ when it is processing the messages
in the flow. For more information about using IBM MQ with IBM App Connect Enterprise, see “Installing
IBM MQ” on page 96.
When the queue manager coordinates transactions, both queue manager and integration node access
shared memory to control a connection to the databases with which the message flow interacts.
Therefore, they require the same access control of the shared memory. One method to achieve this
control is to use the same ID for the integration node service ID and the queue manager administrative
ID.

204 IBM App Connect Enterprise 12.0: User Guide

If you specified an existing queue manager when you created the integration node, check that its
administrative ID is the same ID as the one used for the service ID of the integration node. If the ID is not
the same, change the queue manager ID to be the same as the integration node service ID.
Complete the following steps on the Windows system on which the integration node is running:

Procedure
1. Click Start > Run and enter dcomcnfg. The Component Services window opens.
2. In the left pane, expand Component Services > Computers > My Computer and click DCOM Config.
3. In the right pane, right-click the IBM MQ service labeled IBM MQSeries Services, and click
Properties.
4. Click the Identity tab.
5. Select This user and enter the user ID and password for the integration node service ID to associate
that ID with the queue manager.
6. Click OK to confirm the change.

Enabling data encryption for a JDBC connection

Encryption of JDBC connection is managed by parameters passed to the third party JDBC client jars that
are supplied by the JDBC provider. You can use the IBM App Connect Enterprise JDBC Providers policy or
a vendor-specific configuration file to pass the parameters.

About this task

Encryption parameters are specific to a JDBC provider. Refer to the documentation issued by your JDBC
provider for the details of the Java encryption parameters that you require in your runtime environment.
To enable data encryption for a JDBC connection, follow the instructions in one of the following sections:
• “Using the IBM App Connect Enterprise JDBC Providers policy to enable data encryption for JDBC
connections ” on page 205
• “Using a vendor-specific configuration file to enable data encryption for JDBC connections ” on page
206
Note: You can also use either method to apply extra environment parameters for a JDBC connection;
for example, when you configure JDBC with SSL, or with a high availability and scalability feature such
as Oracle RAC. SSL setup requires additional steps and these are described in “Setting up a public key
infrastructure” on page 2635.

Using the IBM App Connect Enterprise JDBC Providers policy to enable data encryption for JDBC
connections

About this task

For information about how policies are used to enable JDBC connections, see “Enabling JDBC
connections to the databases” on page 200.
The encryption parameters are set in the environmentParms property of the JDBC Providers policy; the
property applies extra parameters to the JDBC connection URL.
In the example described in this section, the Oracle JDBC thin client is used to explain how to configure
IBM App Connect Enterprise to enable the encryption features in the JDBC client JARs. The following
parameters are set to enable encryption of data between IBM App Connect Enterprise and an Oracle
database:
• ORACLE.NET.ENCRYPTION_CLIENT=REQUIRED
• ORACLE.NET.ENCRYPTION_TYPES_CLIENT(AES256)
• ORACLE.NET.CRYPTO_CHECKSUM_CLIENT=REQUIRED
• ORACLE.NET.CRYPTO_CHECKSUM_TYPES_CLIENT=(SHA256,SHA1)

Chapter 4. Configuring IBM App Connect Enterprise 205

 This configuration method is particularly suitable when there is a limited set of parameters, or when
different parameters need to be customized for multiple JDBC Providers policies.

Procedure
Complete the following step:
• Set the encryption parameters as name-value pairs separated by a semicolon by issuing the
mqsichangeproperties command. For example:

mqsichangeproperties integrationNodeName -c JDBCProviders -o Oracle -n environmentParms

-v
oracle.net.encryption_client=REQUIRED;oracle.net.encryption_types_client=AES256;oracle.net.crypto_checksu

Using a vendor-specific configuration file to enable data encryption for JDBC connections

About this task

Alternatively, you can use a vendor-specific configuration file that contains the encryption parameters.
The location of this file is specified by a JVM system property that is runtime environment of the
integration server. Update the JDBC Providers policy to refer to the relevant part of the configuration file.
The encryption parameters can be set as stanzas in an Oracle configuration file called TNSNAMES.ORA.
The location of the configuration file is made available to an integration server by using a Java system
property.

Procedure
Complete the following steps:
• Make the location of the configuration file available and issue the mqsichangeproperties command
to update serverName:
a. Make available the location of the configuration file to the integration server by specifying a Java
system property on the mqsichangeproperties command. For example:

mqsichangeproperties integrationNodeName -e integrationServerName -o ComIbmJVMManager

-n jvmSystemProperty -v "-Doracle.net.tns_admin=Location of TNSNAMES.ORA file"

b. Issue the mqsichangeproperties command to update the serverName property of the JDBC
Providers policy to specify the name of the Oracle Net service in the TNSNAMES.ORA file. For
example:

mqsichangeproperties integrationNodeName -c JDBCProviders -o Oracle -n serverName

-v Name of Oracle Net service

Support for Unicode and DBCS data in databases

You can manipulate Unicode Standard version 3.0 data in suitably configured databases, using ESQL, in
nodes that access databases through ODBC. Support for the manipulation of Unicode data is not available
for nodes that access databases through JDBC.
IBM App Connect Enterprise does not support DBCS-only columns in tables that are defined in databases;
therefore, the following data types are not supported through ODBC or JDBC connections:
• NCHAR, NVARCHAR, NVARCHAR2, NCLOB (on Oracle)
• NCHAR, NVARCHAR, NTEXT, UNICHAR, UNIVARCHAR (on Sybase)
• NCHAR, NVARCHAR (on Informix)
GRAPHIC, VARGRAPHIC, LONGVARGRAPHIC, and DBCLOB data type support on DB2 is provided for App
Connect Enterprise with the following limitations:

206 IBM App Connect Enterprise 12.0: User Guide

• Using the DB2 string functions with Unicode data can return unexpected results. For more information,
see “Unicode string functions in DB2” on page 207.
Support for Unicode is available only for the generally-supported versions of the following database
managers:
• IBM DB2 for Windows, Linux, UNIX, and z/OS operating systems.
• Oracle
• Microsoft SQL server
• Sybase Adaptive Server Enterprise (ASE)
For information about the versions of databases supported, see IBM App Connect Enterprise system
requirements.
Support for the manipulation of Unicode data is not available for nodes that access databases that use
JDBC; for example, DatabaseRetrieve and DatabaseRoute.
If you are using DB2:
• On Windows, Linux, and UNIX operating systems, your database must be created with code set utf-8.
• On all platforms, DB2 returns the lengths of strings in bytes, rather than characters; this response has
implications for the behavior of string length-related ESQL functions.
Some functions might fail, or function differently, when processed by the database. See “Unicode string
functions in DB2” on page 207 for further information.
If you are using Oracle:
• Your database must be created with NLS_CHARACTERSET of AL32UTF8.
• Your ODBC data source definition must include the setting ColumnSizeAsCharacter=1.
On UNIX and Linux platforms, this setting must be included in the appropriate stanza in the ODBC ini
files.
On Windows platforms, this string value must be added to the ODBC data source key in the registry.
See “Enabling ODBC connections to the databases” on page 184 for further information.
• For 32-bit connections, you must set the variable NLS_LANG in the App Connect Enterprise
environment to the value <yourlanguage>_<yourterritory>.AL32UTF8.
if you are using Microsoft SQL server:
• You must use NCHAR, NVARCHAR, and NTEXT data types for your column definitions.
• For App Connect Enterprise on UNIX and Linux platforms, your ODBC data source definition must
include the setting ColumnSizeAsCharacter=1; this setting must be included in the appropriate
stanza in the ODBC .ini files.
If you are using Sybase ASE:
• The default character set of your ASE server must be UTF-8.
• Your ODBC data source definition must include the settings ColumnSizeAsCharacter=1 and
CharSet=UTF8.
On UNIX and Linux platforms, this setting must be included in the appropriate stanza in the ODBC .ini
files.
On Windows platforms, this string value must be added to the ODBC data source key in the registry.
See “Enabling ODBC connections to the databases” on page 184 for further information.

Unicode string functions in DB2

When you use string functions in ESQL expressions, certain parameters refer to character positions or
counts.
For example, with the SUBSTRING function, coding:

Chapter 4. Configuring IBM App Connect Enterprise 207

 SUBSTRING('Hello World!' FROM 7 FOR 4)

results in the string Worl because 7 refers to the seventh character position, and 4 refers to four
characters.
If the string Hello World! is represented in an ASCII code page, the seventh byte of that representation
is the seventh character. However, in other code pages or encoding schemes (for example, some Unicode
representations) the seventh character could start at byte 13, and 4 characters can occupy 8 bytes.
IBM App Connect Enterprise correctly handles this situation; that is, the numeric parameters and results
of these string functions always refer to characters and not the bytes used to represent them.
In some situations, IBM App Connect Enterprise delegates expressions to a database engine for
processing. For example, if there is a WHERE clause, in a SELECT function, applied to a database data
source, the database is passed the WHERE clause if it can interpret all the functions in the expression.
If there are functions that are not supported by the database, IBM App Connect Enterprise passes only
those parts of the expression that can be interpreted, retrieves an unfiltered record set, and performs the
remaining filtering itself.
DB2 string functions use byte indexing and not character indexing. Therefore, for Unicode data, the
meaning of certain functions differs from the IBM App Connect Enterprise functions, even though they can
be ‘interpreted'.
Characters in Unicode UTF8 representation, for example, can occupy from 1-4 bytes, so that the seventh
character can start anywhere from byte 7 to byte 25.
The following string functions are affected:
• INSERT function
• LEFT function
• LENGTH function
• OVERLAY function
• POSITION function
• RIGHT function
• SPACE function
• SUBSTRING function
These functions either take numeric parameters, or return numeric results that refer to indexes, or
counts, of characters in a string.
When expressions involving these functions are passed to the DB2 database, and Unicode string data is
manipulated in the database, the results can be unexpected, or an error might occur.
This error might also occur if, for example, an expression of this type is passed directly to the database by
using the PASSTHRU function. In this situation, you could modify each expression yourself, as necessary,
for the target database.
It is not possible to systematically modify expressions to avoid this problem and IBM App Connect
Enterprise does not attempt to do so.
If the Unicode strings do not use any characters that, in UTF8 representation, occupy more than 1 byte
each, the functions perform correctly.

Configuring properties to connect to external resources

You can use policies to prepare the environment for external resources, or change connection details for
external resources.

About this task

The following topics describe how to prepare your environment to connect to external resources.

208 IBM App Connect Enterprise 12.0: User Guide

Configuring for Enterprise Information Systems
You can use policies to enable the WebSphere Adapters nodes in the integration node runtime
environment to connect with Enterprise Information Systems such as SAP, Siebel, and PeopleSoft.

About this task

The following topics describe how to prepare the environment to connect to Enterprise Information
Systems, and how to change the connection details for adapters without the need to redeploy them.

Preparing the environment for WebSphere Adapters nodes

Before you can use the WebSphere Adapters nodes, you must set up the IBM App Connect Enterprise
runtime environment so that you can access the Enterprise Information System (EIS).

Before you begin

Read “WebSphere Adapters nodes” on page 1050.

About this task

To enable the WebSphere Adapters nodes in the IBM App Connect Enterprise runtime environment,
configure the integration server with the location of the EIS provider JAR files and native libraries.
(On Windows, the location of the JAR files cannot be a mapped network drive on a remote Windows
computer; the directory must be local or on a Storage Area Network (SAN) disk.)
The integration server configuration file (server.conf.yaml) contains a section for connector
providers, which defines the location of the required JAR files and native libraries, as you can see in the
following example:

ConnectorProviders:
SAPConnectorProvider:
jarsURL: default_Path # Set to the absolute path containing the SAP JCo JARs
nativeLibs: default_Path # Set to the absolute path containing the SAP JCo libraries

By default, the location is set to default_Path, which indicates that the JAR files and libraries can be
found in the integration server's shared-classes directory.

Procedure
To configure the integration server with the location of required JAR files and libraries, complete the
following steps.
1. The WebSphere Adapters nodes require libraries from the EIS vendors. For more information on how
to obtain and use these libraries, see “Developing message flows that use WebSphere Adapters” on
page 1106.
2. Use a YAML editor to open the server.conf.yaml file, then find the ConnectorProviders section.
For more information, see “Configuring an integration server by modifying the server.conf.yaml file” on
page 172.
3. Set the jarsURL property to the absolute path where the JAR files are stored.
4. Set the nativeLibs property to the absolute path