Managing Ensemble Productions - InterSystems Documentation

Managing Ensemble 

Productions 

Version 2010.2 

25 April 2011 

InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com

Managing Ensemble Productions 

Ensemble Version 2010.2 25 April 2011 

Copyright © 2011 InterSystems Corporation 

All rights reserved. 

This book was assembled and formatted in Adobe Page Description Format (PDF) using tools and information from the following sources: 

Sun Microsystems, RenderX, Inc., Adobe Systems, and the World Wide Web Consortium at www.w3c.org.The primary document development 

tools were special-purpose XML-processing applications built by InterSystems using Caché and Java. 

and 

Caché WEBLINK, Distributed Cache Protocol, M/SQL, M/NET, and M/PACT are registered trademarks of InterSystems Corporation. 

, , and 

InterSystems Jalapeño Technology, Enterprise Cache Protocol, ECP, and InterSystems Zen are trademarks of InterSystems Corporation. 

All other brand or product names used herein are trademarks or registered trademarks of their respective companies or organizations. 

This document contains trade secret and confidential information which is the property of InterSystems Corporation, One Memorial Drive, 

Cambridge, MA 02142, or its affiliates, and is furnished for the sole purpose of the operation and maintenance of the products of InterSystems 

Corporation. No part of this publication is to be used for any other purpose, and this publication is not to be reproduced, copied, disclosed, 

transmitted, stored in a retrieval system or translated into any human or computer language, in any form, by any means, in whole or in part, 

without the express prior written consent of InterSystems Corporation. 

The copying, use and disposition of this document and the software programs described herein is prohibited except to the limited extent 

set forth in the standard software license agreement(s) of InterSystems Corporation covering such programs and related documentation. 

InterSystems Corporation makes no representations and warranties concerning such software programs other than those set forth in such 

standard software license agreement(s). In addition, the liability of InterSystems Corporation for any losses or damages relating to or arising 

out of the use of such software programs is limited in the manner set forth in such standard software license agreement(s). 

THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY INTERSYSTEMS 

CORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER SOFTWARE. FOR COMPLETE INFORMATION 

REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE LICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION, 

COPIES OF WHICH WILL BE MADE AVAILABLE UPON REQUEST. 

InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves the right, in its sole discretion 

and without notice, to make substitutions and modifications in the products and practices described in this document. 

For Support questions about any InterSystems products, contact: 

InterSystems Worldwide Customer Support 

Tel: +1 617 621-0700 

Fax: +1 617 374-9391 

Email: support@InterSystems.com

Table of Contents 

About This Book .................................................................................................................................... 1 

1 Ensemble Management Portal .......................................................................................................... 3 

1.1 System Requirements ................................................................................................................. 4 

1.2 Starting the Portal ....................................................................................................................... 4 

1.2.1 Starting from the System Management Portal ................................................................. 4 

1.2.2 Starting from Studio ......................................................................................................... 4 

1.3 Login .......................................................................................................................................... 5 

1.3.1 Logging into the Portal .................................................................................................... 5 

1.3.2 Working with Login Accounts ......................................................................................... 5 

1.3.3 Working with Namespaces ............................................................................................... 5 

1.3.4 Working with Security Settings ........................................................................................ 5 

1.4 Ensemble Home Page ................................................................................................................. 6 

1.4.1 Ensemble Menu ................................................................................................................ 6 

1.4.2 Ensemble Table ................................................................................................................ 7 

1.4.3 Job Table .......................................................................................................................... 8 

1.4.4 Log Table .......................................................................................................................... 8 

1.4.5 Service Table .................................................................................................................... 9 

1.4.6 Process Table .................................................................................................................... 9 

1.4.7 Operation Table ................................................................................................................ 9 

1.5 Logout ...................................................................................................................................... 10 

1.6 Portal Command Summary ...................................................................................................... 10 

2 Management Tasks ........................................................................................................................... 15 

2.1 Adding Items ............................................................................................................................ 16 

2.2 Configuring Items .................................................................................................................... 16 

2.3 Finding Items ............................................................................................................................ 17 

2.4 Monitoring Items ...................................................................................................................... 17 

2.5 Purging Items ........................................................................................................................... 18 

2.6 Starting and Stopping Items ..................................................................................................... 18 

2.7 Storing Items ............................................................................................................................ 19 

2.8 Testing Items ............................................................................................................................ 19 

2.9 Viewing Items ........................................................................................................................... 20 

3 What to Manage ................................................................................................................................ 21 

3.1 Working with Productions ........................................................................................................ 21 

3.2 Working with Host Classes ...................................................................................................... 22 

3.3 Working with Configuration Items ........................................................................................... 23 

3.3.1 Business Services ........................................................................................................... 24 

3.3.2 Business Processes ......................................................................................................... 24 

3.3.3 Business Operations ....................................................................................................... 25 

3.3.4 Scheduling Configuration Items .................................................................................... 25 

3.3.5 Assigning Configuration Items to Categories ................................................................ 28 

3.4 Working with Credentials ......................................................................................................... 29 

3.5 Working with Dashboards ........................................................................................................ 29 

3.5.1 Dashboards ..................................................................................................................... 30 

3.5.2 Business Metrics ............................................................................................................ 31 

3.6 Working with Business Rules ................................................................................................... 32 

3.6.1 Business Rules Pages ..................................................................................................... 33 


iii

3.7 Working with the Event Log .................................................................................................... 33 

3.8 Working with the I/O Archive .................................................................................................. 34 

3.9 Working with Jobs .................................................................................................................... 35 

3.9.1 Jobs Page ........................................................................................................................ 35 

3.10 Working with Messages ......................................................................................................... 36 

3.10.1 Message Status ............................................................................................................. 37 

3.10.2 Messages in Progress ................................................................................................... 38 

3.11 Working with Queues ............................................................................................................. 38 

3.12 Working with Sessions ........................................................................................................... 39 

3.13 Working with Workflow ......................................................................................................... 39 

3.13.1 Workflow Portal ........................................................................................................... 40 

4 Productions ........................................................................................................................................ 41 

4.1 Production List ......................................................................................................................... 41 

4.2 Starting a Production ................................................................................................................ 42 

4.3 Stopping a Production .............................................................................................................. 43 

4.4 Production Documentation ....................................................................................................... 44 

5 Configuration .................................................................................................................................... 45 

5.1 Configuration Diagram ............................................................................................................ 46 

5.1.1 Configuration Shapes ..................................................................................................... 46 

5.1.2 Configuration Names ..................................................................................................... 47 

5.1.3 Configuration Icons ........................................................................................................ 49 

5.1.4 Status Indicators ............................................................................................................. 50 

5.1.5 Pool Size ........................................................................................................................ 50 

5.1.6 Context Menu ................................................................................................................. 50 

5.2 Configuration Settings .............................................................................................................. 51 

5.2.1 Configure Production Settings ....................................................................................... 51 

5.2.2 Configure Business Host Settings .................................................................................. 54 

5.2.3 Business Service Settings ............................................................................................... 59 

5.2.4 Business Process Settings .............................................................................................. 60 

5.2.5 Business Operation Settings ........................................................................................... 61 

5.2.6 Reply Code Actions Setting ........................................................................................... 62 

6 System Monitor ................................................................................................................................. 65 

7 Event Log .......................................................................................................................................... 67 

7.1 Event Log Entries ..................................................................................................................... 67 

7.2 Event Log Filter ........................................................................................................................ 68 

7.3 Event Log Purge ....................................................................................................................... 69 

8 Message Browser .............................................................................................................................. 71 

8.1 Message List ............................................................................................................................. 71 

8.1.1 Message Details ............................................................................................................. 73 

8.1.2 Message Contents .......................................................................................................... 75 

8.1.3 Visual Trace .................................................................................................................... 76 

8.2 Message Filter .......................................................................................................................... 79 

8.2.1 Basic Filter Terms .......................................................................................................... 79 

8.2.2 Detailed Filter Terms ...................................................................................................... 80 

8.2.3 Filter Results .................................................................................................................. 84 

8.3 Resend Messages ...................................................................................................................... 85 

8.3.1 Resend Editor ................................................................................................................. 86 

9 Business Processes ............................................................................................................................ 87 

iv 

Managing Ensemble Productions

9.1 Business Process List ............................................................................................................... 87 

9.2 BPL Viewer .............................................................................................................................. 88 

9.3 Business Process Instances ....................................................................................................... 91 

9.3.1 Business Process Instance Entries .................................................................................. 91 

9.3.2 Business Process Instance Filter .................................................................................... 93 

9.3.3 Business Process Instance Purge .................................................................................... 93 

10 Host Monitor ................................................................................................................................... 95 

10.1 Monitor Items ......................................................................................................................... 95 

10.2 Monitor Instances ................................................................................................................... 97 

10.3 Monitor History ...................................................................................................................... 98 

11 Queues ............................................................................................................................................. 99 

11.1 Queue Contents ...................................................................................................................... 99 

11.2 Message Details .................................................................................................................... 100 

12 Maintenance .................................................................................................................................. 103 

12.1 Suspended Messages ............................................................................................................ 104 

12.1.1 Resend Editor for Resubmitting Messages ................................................................ 105 

12.2 Purge Management Data ...................................................................................................... 105 

12.3 Credentials ............................................................................................................................ 107 

12.4 Local Archive Manager ........................................................................................................ 108 

12.5 Lookup Settings .................................................................................................................... 109 

12.6 Default Settings .................................................................................................................... 110 

12.7 Enterprise Message Bank ..................................................................................................... 111 

12.7.1 Adding a Message Bank Business Operation ............................................................ 113 

12.7.2 Configuring a Message Bank Business Operation ..................................................... 113 

13 Testing Service ............................................................................................................................... 117 

13.1 Testing Service - 1 of 4, Select Target .................................................................................. 117 

13.2 Testing Service - 2 of 4, Select Message Type ..................................................................... 118 

13.3 Testing Service - 3 of 4, Submit Test Data ........................................................................... 118 

13.4 Testing Service - 4 of 4, View Results .................................................................................. 118 

14 EDI / HL7 Manager ...................................................................................................................... 121 

14.1 Schema Structures ................................................................................................................ 121 

14.2 Document/Message Viewer .................................................................................................. 122 

Index ................................................................................................................................................... 123 


v

List of Figures 

Figure 3–1: Dashboard Page with an Active Dashboard ....................................................................... 31 

Figure 5–1: Configuration Page ............................................................................................................ 45 

Figure 5–2: Configuration Page Left Column — Business Service ...................................................... 46 

Figure 5–3: Configuration Page Center Column — Business Process ................................................. 46 

Figure 5–4: Configuration Page Right Column — Business Operation ............................................... 47 

Figure 5–5: Different Configuration Names, Same Host Class ............................................................ 47 

Figure 5–6: Same Configuration Name, Different Host Classes ........................................................... 48 

Figure 5–7: Item List Box for Same-Named Configuration Items ........................................................ 48 

Figure 8–1: Standard Ensemble Message Body Contents in XML Format .......................................... 75 

Figure 8–2: HL7 Virtual Document Contents in Message Segment Format ......................................... 75 

Figure 8–3: The Visual Trace Page ........................................................................................................ 77 

Figure 9–1: The BPL Viewer Page ........................................................................................................ 88 

vi 

Managing Ensemble Productions

List of Tables 

Table 1–1: Ensemble Management Portal Commands .......................................................................... 10 

Table 2–1: Management Terminology Conventions .............................................................................. 15 

Table 4–1: Production Status Values ..................................................................................................... 42 

Table 5–1: Icons on Configuration Diagram Shapes ............................................................................. 49 

Table 5–2: Code Values for Reply Code Actions .................................................................................. 63 

Table 5–3: Action Values for Reply Code Actions ................................................................................ 63 

Table 8–1: Options for Filter Type ........................................................................................................ 81 

Table 8–2: Options for Filter Class ........................................................................................................ 82 

Table 8–3: Fields and Properties for Message Filter Conditions ........................................................... 82 

Table 8–4: Comparison Operators for Message Filter Conditions ........................................................ 83 

Table 12–1: Default Setting Properties ................................................................................................ 110 


vii

About This Book 

This book explains how to use the browser-based Ensemble Management Portal to configure, monitor, and maintain an 

Ensemble production. InterSystems Ensemble shares many underlying core technologies with InterSystems Caché. This 

book refers you to books in both documentation sets. 

The book begins by exploring the tasks involved in administering an Ensemble production: 

• “Ensemble Management Portal” introduces the login page, Ensemble home page, and main menu. 

• “Management Tasks” describes tasks you might want to accomplish. 

• “What to Manage” describes the parts of an Ensemble production. 

Further chapters describe major Ensemble functions you can perform using the portal: 

• Productions 

• Configuration 

• System Monitor 

• Event Log 

• Message Browser 

• Business Processes 

• Host Monitor 

• Maintenance 

• Testing Service 

• EDI / HL7 Manager 

There is also a detailed Table of Contents. 

The following books provide related information: 

• Introducing Ensemble provides an overview of the Ensemble product, its purpose and features. 

• Using Dashboards with Ensemble explains how to build browser-based dashboards that display real-time data for an 

Ensemble production. 

• Using Business Rules with Ensemble explains how to define business rules that direct business process logic at decision 

points. 

• Using Workflow with Ensemble explains how to incorporate human interaction into automated business processes. 

For more system administration topics, consult the following guides: 

• Caché System Administration Guide 

• Caché Security Administration Guide 

Managing Ensemble Productions 1

1 

Ensemble Management Portal 

This chapter describes how to use the browser-based Ensemble Management Portal. Developers use the portal to deploy 

new productions. System administrators use the portal to monitor or configure productions that are already running. Business 

analysts use the portal to define business rules for existing productions. 

The Ensemble Management Portal provides the ability to: 

• Start and stop a production. 

• View and modify production configuration. 

• Apply configuration changes while a production is running. 

• View, filter, and search for messages based on content and other criteria. 

• Choose Visual Trace to view message activity in visual format with full details. 

• View, filter, and search for message activity records in the Event Log. 

• Display and configure dashboards for business activity monitoring. 

• View the detailed data contents of messages or business metrics. 

• Work effectively with Electronic Data Interchange (EDI) formats such as HL7 or X12. 

• Edit business rules and view their activity records in the Business Rule Log. 

• Manage workflow, define user roles, and accept tasks. 

• Perform cleanup and maintenance tasks, such as purging old records or configuring login credentials. 

• Monitor production activities from the system viewpoint, as CPU jobs. 

This topic offers a quick tour of the portal as follows: 

• System Requirements 

• Starting the Portal 

• Login 

• Ensemble Home Page 

• Logout 

• Portal Command Summary 



1.1 System Requirements 

The Ensemble Management Portal runs on Internet Explorer 6.0 or higher. 

Additionally, the Scalable Vector Graphics (SVG) Viewer 3.0 must be installed on the system that is running Ensemble. 

If you encounter any problems, you can double-check your installation by looking for SVG Viewer under the Adobe products 

installation folder on the machine where you run the Ensemble Management Portal. 

1.2 Starting the Portal 

You can start the Ensemble Management Portal in one of the following ways: 

• Starting from the System Management Portal 

• Starting from Studio 

• Bookmarking the [Ensemble] home page URI once you navigate to it in your browser. For example, the Ensemble 

Management Portal home page URI in the Ensemble namespace for a default new installation is: 

http://localhost:57772/csp/ensemble/UtilEnsHome.csp 

If your system security requires it, a login page may display at some point in your navigation with a Please login prompt. 

See the Login section for details. 

1.2.1 Starting from the System Management Portal 

To start the Ensemble Management Portal from the System Management Portal: 

1. 

Click the Ensemble launcher in the Windows system tray and click System Management Portal to display the 

System Management Portal [Home] page. 

2. Click Ensemble Management Portal located at the bottom of the System Administration column on the left-hand side. 

3. Depending on the security of your system you may encounter a login page. Enter your username and password and 

click Login to continue to the [Ensemble] home page. 

1.2.2 Starting from Studio 

To start the Ensemble Management Portal from Studio: 

1. On the File menu, click Change Namespace to display the Connection Manager. 

2. Choose a Server and Namespace (choose an Ensemble namespace) and click OK. 

3. If necessary, enter the Username and Password for that namespace and server. 

4. Click OK to save your changes, Cancel to cancel them. 

5. On the Utilities menu, click Ensemble Management. 

6. Depending on the security of your system you may encounter a login page. Enter your username and password and 

click Login to continue to the [Ensemble] home page. 

4 Managing Ensemble Productions

Login 

1.3 Login 

The Ensemble Management Portal login page displays whenever you start the portal or leave the portal idle for more than 

15 minutes and you have more than minimal security on your instance. You may see a login page earlier in your navigation 

to the Ensemble Management Portal in either the System Management Portal or Studio, depending on the security configuration 

of your system. 

1.3.1 Logging into the Portal 

From the login page, you can log into the Ensemble Management Portal as follows: 

1. If you have more than one Ensemble namespace, the login page includes a Namespace list. Click the appropriate 

namespace from the Namespace list. If you have only one Ensemble namespace, the login page automatically selects 

that namespace. 

2. In the Username and Password fields, enter the username and password for a user account defined in the namespace. 

The default login for any namespace is the username _SYSTEM with a password of SYS. 

3. Click Login to display the [Ensemble] home page. 

1.3.2 Working with Login Accounts 

You can change the _SYSTEM password associated with an Ensemble namespace, or add new login accounts, by using the 

System Management Portal [Home] > [Security Management] > [Users] > [Edit User] page. For instructions, see the Creating 

and Editing Users section in the “Users” chapter of the Caché Security Administration Guide. 

1.3.3 Working with Namespaces 

For information about namespaces in Ensemble, see the Namespaces section in the “Production Concepts” chapter of 

Developing Ensemble Productions. 

1.3.4 Working with Security Settings 

For each Ensemble-enabled namespace there is a CSP application that needs to be properly configured to run the Ensemble 

Management Portal. Normally there is nothing you need to do about this. At installation time, the CSP applications in the 

namespaces ENSEMBLE and ENSDEMO acquire the following authentication settings, depending on the type of security 

that you select at installation time. 

Security Level 

Minimal 

Normal 

Locked Down 

Type of Authentication 

Unauthenticated 

Password 

Password, Kerberos, and LDAP 

During installation, Ensemble identifies the level of security you select and saves this information for future use. Any time 

you create a new namespace, the built-in CSP applications in that namespace acquire the appropriate authentication settings 

for that security level. 



1.4 Ensemble Home Page 

The [Ensemble] home page contains a welcome message, a menu of commands, and information about the active Ensemble 

production. 

You can display the Ensemble home page in any of the following ways: 

• Navigate from the System Management Portal or Studio. 

• Click Home in any Ensemble Management Portal menu. 

• Click Ensemble in the navigation path of any portal page. 

At far right, the title bar provides a Namespace list that you can use to switch to a different Ensemble namespace. There is 

also a Go to list that you can use to return to previously visited pages in the Ensemble Management Portal or System 

Management Portal. 

Under the home page title bar is a display area. At the top left corner of this display is the Ensemble Management Portal 

menu, also referred to as the Ensemble Menu. 

The main display of the Ensemble home page shows tables that contain summary information about the Ensemble installation 

and any production activity in the active namespace. Each table on the home page provides summary statistics about some 

key aspect of Ensemble operations. The numbers reflect a current snapshot when you refresh the home page. If you want 

to see the details behind these statistics, click the title of the following tables: 

• Ensemble Table 

• Job Table 

• Log Table 

• Service Table 

• Process Table 

• Operation Table 

At the top of the Ensemble home page, above the [Ensemble] link, is a Home option. Click it to display the System Management 

Portal [Home] page. 

1.4.1 Ensemble Menu 

The Ensemble home page as well as many pages in the Ensemble Management Portal contain a menu on the left-hand side 

of the page, the Ensemble Menu. Click commands in this menu to navigate to the associated pages. When you do, the 

navigation path changes to track your place in the portal structure. In addition to Home, the Ensemble menu selections are: 

• Productions — lists productions known to the currently selected namespace. 

• System Monitor — displays real-time status of external connections and internal message queues. 

• Event Log — lists event log entries and allows you to enter criteria to filter the list. 

• Message Browser — lets you filter, search, and view the message archive for the currently running production. 

• Business Processes — lists all business processes in the current namespace. 

• Business Rules — lets you define business rules. 

• Business Rule Log — lets you log business rules activity. 

• Host Monitor — displays the status of configuration items in the current production. 


Ensemble Home Page 

• Jobs — lists the system jobs doing work for the current production. 

• Queues — lists the queues in use by the currently running production 

• Maintenance — lets you select specialized tasks from the Maintenance menu. 

• Dashboards — lists the available Business Activity Monitoring dashboards. 

• Business Metrics — summarizes the data being collected by business metric classes. 

• Workflow Portal — lets you manage workflow, define user roles, and accept tasks. 

• Testing Service — lets you send test requests to the currently running production. 

• EDI / HL7 Manager — lets you work with Electronic Data Interchange (EDI) formats such as HL7. 

1.4.2 Ensemble Table 

The home page Ensemble table displays the following data fields: 

• Ensemble Running (or other status values) — This field describes the Ensemble execution engine. The value Running 

appears if any Ensemble production is running. Otherwise, the field may display the values Stopped, Suspended, or 

Troubled. For details about these values, see the Production List section in the “Productions” chapter. 

• Production — The name of the running production, or name of the last production run. If you click Start Production, 

Stop Production, Update Production, or Recover on the home page, this is the production that you are starting, stopping, 

updating, or recovering. 

The home page Production field provides links to other portal pages as follows: 

– If you click the production name, the display changes to the configuration diagram for that production, where you 

can configure the operational settings for a production in the active namespace. See the “Configuration” chapter 

for details. 

– If you click more... to the right of the production name, the [Ensemble] > [Productions] page displays where you 

can select a different production to start. 

• Start Time — The start time of the currently running production. The Start Time field is never reset while the production 

is running, even if you click Reset Counter to reset other fields. If there is no production running, the Start Time field 

is blank. 

The home page Ensemble table also provides the following commands: 

• Start Production — Start Production displays only if no production is currently running. Click Start Production to start 

the production listed in the home page Production field. 

• Stop Production — displays only if a production is currently running. Click Stop Production to stop the production 

listed in the home page Production field. 

• Update Production — Under some conditions, when you start the portal there is a discrepancy between the production 

as defined in the code, and the status of the running production. Examples would be if: 

– A specific business host experienced an error and has died (the most likely cause) 

– The user changed a configuration parameter for a business host in a running production, such that the host now 

needs to be restarted. 

– A production typically opens a Terminal window, but this window was closed by a user action while the production 

was still running. 



When discrepancies such as this arise, the Update Production command becomes available on the home page. Click 

it, to update the production and resolve the discrepancy. Ensemble displays a confirmation message. Click OK to return 

to the [Ensemble] home page. 

Alternatively, you can cause the production to update itself automatically. When you take this approach, the Update 

Production command never appears. To do this: 

– Start the Business Service Wizard. For instructions, see the Adding a Business Service to a Production section in 

the “Business Services” chapter of Developing Ensemble Productions. When the wizard displays, choose Other, 

and for the Service Class choose Ens.ProductionMonitorService. You may accept the default values for the other 

settings. Click OK. This adds a production monitor service to the production. 

– View the production configuration diagram on the [Ensemble] > [Productions] > [Configuration] page. Select the 

new production monitor service and configure its General Settings and Specific Settings. For details, see the 

“Business Service Settings” section in the “Configuration” chapter. The Call Interval setting controls how frequently, 

in seconds, the production monitor service checks to see if there is a discrepancy between the production 

as defined in the code, and the status of the running production. Each time it finds such a discrepancy, the production 

monitor service updates the production to resolve it. 

• Recover — Appears on the home page if a production has a status of Troubled due to some unexpected program error. 

Click Recover to clean up the troubled instance of the production so that you can run a new instance when you are 

ready. 

1.4.3 Job Table 

The Ensemble home page Job table displays the following data fields: 

• Total Jobs Running — The number of system jobs that have been allocated to pools for use by business hosts within 

this production. This number reflects a current snapshot when you refresh the home page. 

Each time a business service, business process, or business operation needs to do work, it starts a system job in which 

to complete its tasks. This job comes either from a private pool of jobs belonging to the business service, business 

process, or business operation, or (in the case of a business operation) it may come from the public actor pool for the 

production. When the task is done, the job returns itself to the pool of jobs from which it came. 

A production might need to start and stop several different jobs to complete a single requests. The details depend (in 

part) on whether requests are made synchronously or asynchronously. For example, if a job is required to wait, the job 

returns itself to its pool during the wait time to free up that resource. 

• Jobs OK, Jobs Inactive, Jobs of Other Status — The number of jobs with a status of OK, Inactive, or some other value, 

respectively. 

If you click the Job table title on the Ensemble home page, the [Ensemble] > [Jobs] page displays — the same result as 

clicking Job on the Ensemble menu. 

1.4.4 Log Table 

The home page Log table displays the following data fields: 

• Last Error Time — The date and time of the most recent entry in the Total Error Count. 

• Total Error Count — The number of error entries that have been written to the event log since this production was last 

started. Errors that were recorded during a previous run of this production or of any other production might still reside 

in the event log as entries, but are not included in the Total Error Count. 


Ensemble Home Page 

If you click the Log table title on the Ensemble home page, the [Ensemble] > [Event Log] page displays — the same result 

as clicking Log on the Ensemble menu. 

Tip: 

Most of the entries on the [Ensemble] > [Event Log] page are not errors. You can find the error entries by clicking 

on the Type column heading to sort the column. Entries labeled Error in this column are errors; they have red text 

and a pink background. The most recent errors appear at the top of the list. 

1.4.5 Service Table 

The home page Service table displays the following data fields: 

• Last Activity Time — The date and time of the most recently completed activity. 

• Activities Completed — A completed activity means that a business service has received a request message from outside 

the currently running production, and has done whatever it is designed to do as a result of receiving that request. It 

might be designed to invoke a business process or business operation, return a value, acknowledge receipt of the 

message, or something else. Whatever that is, when it is done the activity is considered complete. 

If you click the Service table title on the Ensemble home page, the [Ensemble] > [Host Monitor] page displays — the same 

result as clicking Host Monitor on the Ensemble menu. You can find the business service entries by clicking on the Type 

column heading to sort the column. 

1.4.6 Process Table 

The home page Process table displays the following data fields: 


• Activities Completed — A completed activity means that a business process has received a request message from within 

the currently running production, and has done whatever it is designed to do as a result of receiving that request. It 

might be designed to fire a rule, open a file for writing, execute programming logic to decide which business operation 

to invoke, return a value, acknowledge receipt of the message, begin a long-running workflow sequence, or something 

else. Whatever that is, when it is done the activity is considered complete. 

• Messages In Progress — A message in progress means that a business process has received a request message from 

within the currently running production, and has not yet completed all of the activities that it is designed to do as a 

result of receiving that request. 

• Messages In Queues — The total number of messages that are waiting to be received by business processes in the 

currently running production. 

If you click the Process table title on the Ensemble home page, the [Ensemble] > [Host Monitor] page displays — the same 

result as clicking Host Monitor on the Ensemble menu. You can find the business process entries by clicking on the Type 


1.4.7 Operation Table 

The home page Operation table displays the following data fields: 


• Activities Completed — A completed activity means that a business operation has received a request message from 

within the currently running production, and has done whatever it is designed to do as a result of receiving that request. 

It might be designed to invoke an external application or database, open a file for writing, return a value, acknowledge 

receipt of the message, or something else. Whatever that is, when it is done the activity is considered complete. 



• Messages In Progress — A message in progress means that a business operation has received a request message from 

within the currently running production, and has not yet completed all of the activities that it is designed to do as a 

result of receiving that request. If there is a message in progress, it is most likely in a retry loop. For details, see the 

“Messages in Progress” section in the chapter “What to Manage.” 

• Messages In Queues — The total number of messages that are waiting to be received by business operations in the 


If you click the Operation table title on the Ensemble home page, the [Ensemble] > [Host Monitor] page displays — the same 

result as clicking Host Monitor on the Ensemble menu. You can find the business operation entries by clicking on the Type 


1.5 Logout 

When you choose the Logout option from the Ensemble menu, the portal logs you out and displays a link inviting the next 

user to log in. To do so, click the link. To exit the portal completely, close the browser. If a production is running at this 

time, it continues to run while the portal is closed. 

1.6 Portal Command Summary 

The following table summarizes the major functions of the Ensemble Management Portal in alphabetical order. Each entry 

summarizes how to navigate the Ensemble Management Portal by choosing an Ensemble menu command, then selecting 

further commands. 

Table 1–1: Ensemble Management Portal Commands 

Page or 

Command 

Purpose 

Ensemble 

Menu 

Command 

Additional Commands 

Add Operation 

Add a business operation to the 

currently selected production. You 

must add the operation before you 

can configure it. 


Click Configure, click the neutral 

background in the top display, 

then in the bottom display click 

Add Operation. 

Add Process 

Add a business process to the 


must add the process before you 

can configure it. 





Add Process. 

Add Rule 

Add a business rule to the currently 

selected production. 

Business Rules 

At the top of the page, click Create 

New Rule Set or Create New Routing 

Rule Set. 

Add Service 

Add a business service to the 


must add the service before you can 

configure it. 





Add Service. 


Portal Command Summary 

Page or 

Command 

Purpose 


Menu 

Command 


Archive Manager 

Periodically save older messages to 

a separate archive for long term 

storage. 

Maintenance 

Select Archive Manager from the 

menu. 

Auto-Start 

Configure Ensemble so that a 

specific production starts 

automatically at system startup, and 

stops automatically at system 

shutdown. 

Maintenance 

Click a production name from the 

Auto-Start Production list. 

BPL Viewer 

Display the BPL diagram for a 

business process class at top. 

Diagram data appears at bottom. 

Business 

Processes 

Click Definition next to the 

business process name. 

Business Metrics 

View current values for the data 

being collected by a business 

metric. 

Business 

Metrics 

Click Properties next to the 

business metric name. 

Business Process 

Instances 

List any current instances of a 

business process in the currently 

running production. If a business 

process has completed its work, 

there is no entry for it on this page. 

Business 

Processes 

Click Instances next to the 

business process name. 

Configuration 

View relationships between 

configuration items in a visual format 

in the top display. Add or remove 

configuration items from a 

production. 


Click Configure next to the 

production name. To select the 

production for editing, click the 

neutral background. 

Credentials 

Create a table of usernames and 

passwords that business operations 

can use to establish remote 

connections. 

Maintenance 

Select Credentials from the menu. 

Dashboards 

View a list of available Business 

Activity Monitoring dashboards. 

Dashboards 

Click View next to the name of the 

dashboard. 

Event Log 

View event log entries. 

Event Log 

Enter criteria to filter the list of 

entries. 

EDI / HL7 

Manager 

View and transform messages in 

Electronic Data Interchange (EDI) 

formats such as HL7 or X12. 

EDI / HL7 

Manager 

View information from the 

standards organization, view 

document structure 

specifications, or view and 

transform the contents of specific 

messages. 

Login 

Enter a username and password to 

use the portal in an Ensemble 

namespace. 

— 

Click the Ensemble cube icon 

and select System Management 

Portal, then choose Ensemble 

Management Portal from the list of 

options on the page. 



Page or 

Command 

Purpose 


Menu 

Command 


Lookup Settings 

Create and configure data tables to 

support the Lookup and Exists utility 

functions 

Maintenance 

Select Lookup Settings from the 

menu. 

Message 

Contents 

View the contents of a message 

body. 

Message 

Browser 

Click Contents next to the 

message, in the Message 

Browser and other pages. 

Message Details 

View the entire contents of a 

message, including message header 

and message body. 

Message 

Browser 

Click Details next to the message, 

in the Message Browser and 

other pages. 

Message Queue 

Contents 

List the messages on the currently 

selected queue. Select a message 

in the top display, to reveal Message 

Details at bottom. 

Queues 

Click Contents next to the 

message queue. 

Monitor 

(connections) 

View continually updated status of 

external connections and internal 

message queues. 

System Monitor 

— 

Monitor (graph) 

Monitor the level of activity for 

currently running business services, 

processes, or operations. 

Host Monitor 

Click History next to the name of 

the configuration item. 

Monitor (table) 

Monitor the operational status of 

currently running business services, 

processes, or operations. 

Host Monitor 

Click Instances next to the name 

of the configuration item. 

Operation 

Settings 

Edit the operational settings of a 

business operation in the currently 



Click Configure, then select a 

Business Operation in the top 

display. 

Process Settings 


business process in the currently 




Business Process in the top 

display. 

Production 

Settings 

Edit the operational settings of the 

currently selected production. 


Click Configure, then click the 

neutral background in the top 

display. 

Purge 

Management 

Data 

Purge event log entries, the 

message warehouse, business 

process records, and the business 

rule log. 

Maintenance 

Select Purge Management Data 

from the menu. 

Rule Log 

View business rule activity records 

for the currently running production. 

Business Rule 

Log 

Enter criteria to filter the list of 

rules. 

Service Settings 


business service in the currently 




Business Service in the top 

display. 

Start Production 

Start a production. View the results 

of this request. 


Click Start next to the production 

name. 


Portal Command Summary 

Page or 

Command 

Purpose 


Menu 

Command 


Stop Production 

Stop a production. View the results 

of this request. 


Click Stop next to the production 

name. 

Suspended 

Messages 

Resend messages that have 

entered a Suspended state, for 

example because of a 

communication failure. If you have 

corrected the failure, you can now 

resend these messages. 

Maintenance 

Select Suspended Messages from 

the menu. 


View continually updated status of 

external connections and internal 

message queues. 


— 

Testing Service 

Enter parameter values for a test 

request message. View the results 

of a test request message. 


Select a business service, 

process, or operation; select a 

request; click OK, enter 

parameter values, click Save. 

Visual Trace 

Represent message history visually. 

Trace how and when messages 

traveled between production items. 

Enter criteria in the bottom display, 

to filter messages at top. 

Message 

Browser 

Click Trace next to the message, 

in the Message Browser and 

other pages. 

Workflow Portal 

Manage workflow, define user roles, 

and accept tasks. 


Select an option from the menu: 

My Tasks, Workflow Roles, Workflow 

Users, Task Browser, or Worklist 

Browser. 


2 

Management Tasks 

This chapter describes the tasks required to manage an Ensemble production. Each of the following sections defines tasks 

and explains how to complete them using the Ensemble Management Portal: 

• Adding Items 

• Configuring Items 

• Finding Items 

• Monitoring Items 

• Purging Items 

• Starting and Stopping Items 

• Storing Items 

• Testing Items 

• Viewing Items 

If you cannot find the task you have in mind, try the following table. This table lists the conventions that this chapter uses 

to identify tasks with many alternate names. 

Table 2–1: Management Terminology Conventions 

Task 

Add 

Configure 

Find 

Monitor 

Purge 

Start 

Stop 

Store 

Test 

Alternate Names for Similar or Related Tasks 

Configure, create, and register. 

Add, change, create, delete, determine, edit, modify, register, remove, and set. 

Filter and search. Items you might want to find include messages, business processes, and 

jobs. 

Administer, examine, manage, observe, study, and view. Items you might want to monitor 

include dashboards, messages, event log entries, external connections, and operational 

statistics. 

Archive, clean, delete, destroy, maintain, and remove. 

Access, boot, execute, launch, login, reboot, run, send, and startup. 

Close, exit, halt, and shutdown. 

Archive, populate, save. 

Debug and develop. Related activities include solution delivery and quality assurance. 



Task 

View 

Alternate Names for Similar or Related Tasks 

Display, examine, find, identify, monitor, search, and study. Items you might want to view 

include messages, event log entries, external connections, and operational statistics. 

If you want to find management tasks organized by what is being managed, more topics are also available in the next 

chapter, “What to Manage.” 

2.1 Adding Items 

When you add a configuration item — a business service, business process, or business operation — the underlying host 

class already exists. The class code has been written and compiled using the Studio tool. When you add a configuration 

item to a production, you assign parameters to the class and give that set of parameters a name. In effect, you are telling 

the production you want to use this already-existing class in a particular way. 

If you do not see the task you want in this section, try the Configuring Items section. 

Add... 

Business metric 

Business operation 

Business process 

Business rule 

Business service 

Credentials for remote login 

Data tables for lookups 

Production 

Routing rule 

Sequence of Portal Commands 

Productions, Configure, Production, Add Service 

Productions, Configure, Production, Add Operation 

Productions, Configure, Production, Add Process 

Business Rules, Create New Rule Set 

Productions, Configure, Production, Add Service 

Maintenance, Credentials 

Maintenance, Lookup Settings 

Productions, Create New Production 

Business Rules, Create New Routing Rule Set 

2.2 Configuring Items 

Configuration tasks do not create classes or code. They determine the context in which code executes while the production 

is running. When you configure a production, the classes already exist — the code has been written and compiled. By 

configuring the production, you are telling the production how you want it to use these already-existing classes. 

The “configure” task includes other tasks that you might want to perform, such as add, change, create, delete, determine, 

edit, modify, register, remove, or set. Many of these tasks are included in the following table. If you do not see the task 

you want in this section, try the Adding Items section. 

Configure... 

Business metric settings 

Business operation settings 

Business process settings 


Productions, Configure, Business Service 

Productions, Configure, Business Operation 

Productions, Configure, Business Process 


Finding Items 

Configure... 

Business rule definition 

Business service settings 

Production settings 

Remote connections 

Routing rule definition 

Workflow 


Business Rules, Select a Rule, Edit 


Productions, Configure, Production 




2.3 Finding Items 

The “find” task includes other tasks that you might want to perform, such as browse, filter, or search. If you do not see 

the task you want in this section, try the Viewing Items section. 

Find... 

Filter the event log for the currently running production by entering search criteria 

such as time of day or session identifier. 

Filter the rule log for the currently running production by entering search criteria such 

as reason or rule version. 

Filter the message log for the currently running production by entering search criteria 

such as time of day or session identifier. 

Sequence of Portal 

Commands 

Event Log 

Business Rule Log 

Message Browser 

2.4 Monitoring Items 

Viewing is essentially a passive activity; you glance at a display to get a snapshot of the data at one point in time. Monitoring 

tasks require more participation; you watch a display and interpret changes in the display between one time and another. 

Monitoring usually involves some form of observing and noting changes over time to determine whether there were any 

changes between time A and time B, and if so, what caused them. Monitoring does not need to be continuous; samples can 

be taken at regular or random intervals. 

The “monitor” task includes other tasks that you might want to perform, such as administer, examine, manage, observe, 

study, and view. If you do not see the task you want in this section, try the Finding Items section. 

Monitor... 

Currently running business processes 

Currently running business services, business processes, and 

business operations 

Dashboard activity 

Real-time status of external connections, event log, and message 

queues 


Business Processes, Instances 

Host Monitor 

Dashboards, View 




Monitor... 

Message queues 

Messages on a specific queue 

Messages in a Suspended state 

System jobs, in detail 


Queues 

Queues, Contents 

Maintenance, Suspended Messages 

Jobs 

This book describe how to monitor an Ensemble production using the Ensemble Management Portal. Other types of monitoring 

are available, and other books describe them. For example: 

• To read about a command-line interface that you can use to retrieve basic status information from a running production 

via a Telnet connection or command-line script, see the section “TCP Status Service” in the “TCP Text Line Inbound 

Adapter” chapter of Using TCP Adapters with Ensemble. 

• Windows Management Instrumentation (WMI) is a feature of the Windows operating system that provides a standardized 

way of collecting management information. It allows users and programmers to access management information from 

the operating system and other applications in a variety of ways, including scripts, programming languages, and management 

tools and applications. WMI is the Microsoft implementation of the Web-Based Enterprise Management 

(WBEM) standard from the Distributed Management Task Force (DMTF). 

The InterSystems implementation of WMI signals an Ensemble_LogEvent each time an Ensemble business host posts 

an alert to the Ensemble Event Log. To set up WMI monitoring for InterSystems products, see “Monitoring Caché 

Using WMI” in the Caché Monitoring Guide. 

2.5 Purging Items 

The “purge” task includes other tasks that you might want to perform, such as archive, clean, delete, destroy, maintain, 

or remove. If you do not see the task you want in this section, try the section “Monitoring Items.” 

Purge... 

Any runtime data: event log, rule log, I/O log, messages, business 

process instances 

Event log entries only 

Business process instance data 

Older messages, while saving them to a separate archive for long 

term storage 

Production configuration data 


Maintenance, Purge Management Data 

Event Log, Purge 

Business Processes, Instances, Purge 

Maintenance, Archive Manager 


2.6 Starting and Stopping Items 

The “start” task includes other tasks that you might want to perform, such as access, boot, execute, launch, login, reboot, 

run, send, or startup. The “stopping” task includes other tasks that you might want to perform, such as close, exit, halt, 

log out, or shut down. If you do not see the task you want in this section, try the Monitoring Items section. 


Storing Items 

Start or Stop... 

Configure Ensemble so that a specific production starts 

automatically at system startup, and stops automatically at 

system shutdown. 

Log into the Ensemble Management Portal. 

Log out of the portal, leaving the browser open for the next 

administrator to log in. 

Resend messages that have entered a Suspended state. 

Start a message archive operation. 

Start a production. 

Start or stop a business service on a schedule. 

Start or stop a business operation on a schedule. 

Start or stop a business process on a schedule. 

Start the Ensemble Management Portal. 

Stop a production. 


Maintenance, Auto-Start Production 

Login 

Logout 



Productions, Start 




Login 

Productions, Stop 

2.7 Storing Items 

The “store” task includes archiving messages and other important data. The Ensemble persistent message store operates 

automatically, but there are optional tasks that you might consider. 

Store... 

Periodically save older messages to a separate archive for long term 

storage. 

Create and configure data tables to support the Lookup and Exists utility 

functions. 




2.8 Testing Items 

The “test” task includes other tasks that you might want to perform, such as debug, deliver, or develop. If you do not see 

the task you want in this section, try the Monitoring Items section. 

Test... 

Messages in Electronic Data Interchange (EDI) formats such 

as HL7 or X12 

Productions, by sending request messages and receiving 

response messages 


EDI / HL7 Manager, Message Viewer 

or Testing Service 




2.9 Viewing Items 

Viewing is a passive activity; you glance at a display to get a snapshot of the data at one point in time. Monitoring tasks 

require more participation; you watch a display and interpret changes in the display between one time and another. Monitoring 

usually involves some form of observing and noting changes over time to determine whether there were any changes 

between time A and time B, and if so, what caused them. Monitoring does not need to be continuous; samples can be taken 

at regular or random intervals. 

The “view” task includes other tasks that you might want to perform, such as display, examine, find, identify, monitor, 

search, or study. If you do not see the task you want in this section, try the Monitoring Items section. 

View... 

BPL diagram of a business process class 

Data being collected by a business metric 

Business operation settings 

Business process settings 

Business processes, in various ways 

Business rule definition 

Business rule activity records 

Business service settings 

Credentials for remote connections 

Event log entries 

I/O archive entries 

Lookup table 

Message body contents 

Message header and body contents 

Messages of all kinds 

Production settings 

Routing rule definition 

Software version information 

Statistics about all productions 

Statistics about the currently running production 

Suspended messages 

Visual trace of the delivery of a message, from original 

source all the way through to the final destination 


Business Processes, Definition 

Business Metrics, Properties 

Productions, Configure, Operation 

Productions, Configure, Process 

Business Processes 

Business Rules, Select a Rule, View 


Productions, Configure, Service 


Event Log 

See “Working with the I/O Archive” 


Message Browser, Contents 

Message Browser, Details 



Business Rules, Select a Rule, View 

Maintenance 


Home 


Message Browser, Trace 


3 

What to Manage 

Each topic in this section describes an aspect of an Ensemble production that you can manage in some way, and explains 

how to accomplish this using the Ensemble Management Portal. Topics include: 

• Working with Productions 

• Working with Host Classes 

• Working with Configuration Items 

• Working with Credentials 

• Working with Dashboards 

• Working with Business Rules 

• Working with the Event Log 

• Working with the I/O Archive 

• Working with Jobs 

• Working with Messages 

• Working with Queues 

• Working with Sessions 

• Working with Workflow 

3.1 Working with Productions 

A production is the unit of delivery for development projects based on Ensemble. A production is a package of host classes 

and configuration items that solves a specific integration problem for an enterprise. 

A production has many settings that you can configure using the Ensemble Management Portal. These settings affect the 

behavior of the production, as well as the various configuration items within the production — services, processes, and 

operations. While the production is running, there are a variety of monitoring and diagnostic tasks you can perform. Any 

changes you make to a production while it is running are applied immediately, without requiring you to stop and restart 

the production. 



Production Task 

Purge old records for the currently running production. Resend 

suspended messages, set user credentials, and configure automatic 

startup. 

Configure a production and its associated business services, business 

processes, and business operations. 

Configure Ensemble so that a specific production starts automatically 

at system startup and stops automatically at system shutdown. 

Create a new production. 

Delete a production. 

Establish credentials for remote connections. 

Monitor dashboard activity. 

Purge records from the event log, message warehouse, business 

process archives, and business rule log. 

Quickly view the real-time status of incoming and outgoing 

connections for the production. 

Remove a production from a namespace, or remove a business 

service, business process, or business operation from a production. 

Start a production. 

Stop a production. 

Test a production. 

View a list of configuration items that have been instantiated in the 


View statistics about all productions. 

View statistics about instances of currently running business services, 

business processes, and business operations. 


Maintenance 

Productions, Configure 

Maintenance, Auto-Start Production 

Productions, Create New Production 

Productions, Delete Production 



Maintenance, Purge Management 

Data 



Productions, Start 

Productions, Stop 


Host Monitor 


Host Monitor, Instances 

3.2 Working with Host Classes 

An Ensemble host class is executable source code. Class developers use the Studio tool, the BPL Editor, or a text editor to 

create, view, edit, and compile host classes. No class can be created or changed from the Ensemble Management Portal, 

but you do choose them from the portal. 

Every host class extends Ens.Host, an Ensemble class that determines general characteristics for classes that operate as 

members of a production. Every host class is one of three types, all of which inherit from Ens.Host: 

• Business service class — Instances of the Ens.BusinessService class accept requests from entities outside Ensemble 

and relay them to host classes inside Ensemble for processing and fulfillment. A business service class corresponds to 

a single, well-defined action that an external entity needs to perform. This action enters an Ensemble production in the 

form of a request to the business service. The business service generates whatever activity is needed to satisfy this 

request. It invokes various lower-level host classes — business processes and business operations — and it controls 

the logic of these invocations. When all of its internal processing is complete, a business service formulates and returns 


Working with Configuration Items 

a response to the outside entity’s original request. Some requests do not require a response; if this is the case, none is 

returned. 

• Business process class — Instances of the Ens.BusinessProcess class accept requests from host classes inside 

Ensemble — business services or business processes — and either process the requests or relay them to other host 

classes inside Ensemble for processing. A business process class corresponds to a single, well-defined business task 

that needs to be performed. The business process generates whatever activity is needed to complete this task. It invokes 

various lower-level host classes — business processes or business operations — and it controls the logic of these 

invocations. When all of its internal processing is complete, a business process formulates and returns a response to 

the original request, if a response is needed. Some requests do not require a response; if this is the case, none is returned. 

• Business operation class — Instances of the Ens.BusinessOperation class accept requests from host classes inside 

Ensemble — business services or business processes — and either process the requests or relay them to entities outside 

Ensemble for processing. A business operation class consists of one or more methods, each of which corresponds to 

a single, well-defined external or internal operation that needs to be performed, such as retrieving a specific piece of 

data or making a specific type of calculation. When its internal processing is complete, a business process formulates 

and returns a response to the original request, if a response is needed. Some requests do not require a response; if this 

is the case, none is returned. By convention, a business operation is an extremely specific operation that contain very 

little logic and does what is requested of it without calling further operations or branching in any way. When the design 

of the production demands logic, this is contained in a higher-level business processes. 

A host class must be compiled and loaded before the corresponding business host — business service, business process, 

or business operation — can be added to the production. Once the business host is added to the production, it has configurable 

settings that can be adjusted using the display on the Ensemble Management Portal [Ensemble] > [Productions] > [Configuration] 

page. 

A host class determines how a configuration item can be configured, by publishing its configurable properties in a class 

parameter called SETTINGS. Any property listed in the SETTINGS parameter for a host class automatically appears in the 

display on the [Ensemble] > [Productions] > [Configuration] page, whenever an item of that host class is selected for configuration. 

You can edit and save values on the [Ensemble] > [Productions] > [Configuration] page without editing or recompiling 

the host class itself. Any changes you make are applied immediately, without requiring you to stop and restart a running 

production. The same is true of production-wide properties defined in the production class and exposed for configuration 

by using the SETTINGS class parameter in the production class. 

A host class is sometimes called a business class. Either term is appropriate. 

3.3 Working with Configuration Items 

An Ensemble configuration item is any business service, business process, or business operation within an Ensemble production. 

Every configuration item extends the class Ens.Item, and consists of a name, a reference to a specific host class, 

and a group of operational settings that determine how the host class behaves when it is a member of a running production. 

There is a clear difference between Ensemble configuration items and Ensemble host classes: 

• An host class is executable source code. 

• An configuration item is a specialized configuration of a host class. 

A configuration item is always associated with a specific production. It may resemble or duplicate items in other productions. 

Each production is an entirely closed universe that does not use configuration items from other productions. 

An Ensemble production contains the following types of configuration item: 

• Business services (includes business metrics) 



• Business processes (includes routing processes) 

• Business operations (includes workflow operations) 

You can use the diagram on the [Ensemble] > [Productions] > [Configuration] page to create, view, edit, and save configuration 

items. You can configure items that reference the same host class; each such item has a different name. All configuration 

items with the same host class have the same operational settings, but each item of that class can have different values for 

those settings, so each item is unique. 

After you define the configuration settings for a production using the Ensemble Management Portal and save your settings, 

the portal outputs the settings to the production class in the form of an embedded XML excerpt. You can view this XML 

directly; look for the production class in Ensemble Studio, on the Productions tab. The intention is for you to use the 

Ensemble Management Portal to generate the XML initially, and there is no need to edit the production class directly. 

However, the XML is there, if you ever want to view it, or export it from Studio. 

You can further define configuration items as described in the following sections: 

• Scheduling Configuration Items 

• Assigning Configuration Items to Categories 

3.3.1 Business Services 

A business service accepts requests from sources outside the Ensemble production. If designed to do so, it also returns a 

response to the requestor. A request that enters a business service from outside Ensemble is known as a primary request. 

This type of request instigates a tracking mechanism called a session, which remains open until all of the activities prompted 

by the primary request are completed. The session has an identifier that is used to mark all of the subsequent, internal 

messages that Ensemble generates to fulfill the primary request. 

Service Task 

Add a business service to a production. 

Remove a business service from a production. 

View or configure operational settings for a business service. 


Productions, Configure, Production, Add 

Service 



A business metric is a special type of business service used to monitor business activity and display the resulting statistics 

on dashboards. Business metrics have their own host class, Ens.BusinessMetric, which inherits from the business service 

host class. To use a business metric in a production, you must add and configure it as for any other business service, using 

the tasks described in the preceding table. However, there are additional details for business metrics only. See the “Business 

Metrics” chapter in Using Dashboards with Ensemble. 

3.3.2 Business Processes 

A business process accepts requests from business services and from other business processes. If designed to do so, it also 

returns a response to the requestor. A business process communicates only with other Ensemble configuration items. 

Business processes contain programmatic logic that describes what must happen inside Ensemble to fulfill a specific portion 

of a request that (at some point) originated from outside Ensemble. The logic within a business process is both applicationindependent 

and format-independent, and is described entirely in Ensemble terms. 

Process Task 

View the BPL diagram of a business process class. 


Business Processes, Definition 



Process Task 

Add a business process to a production. 

Define a business rule for a BPL business process. 

Monitor instances of currently running business processes 

in detail. 

Purge business process records. 

Remove a business process from a production. 

View business processes and their host classes in various 

ways. 

View or configure operational settings for a business 

process. 


Productions, Configure, Production, Add Process 


Business Processes, Instances 

Business Processes, Instances, Purge 




A routing process is a special type of business process used to direct routing rules for the Ensemble message routing engine. 

Routing Task 

Invoke a routing rule from a routing process. 

Define a routing rule set for a routing business process. 




To configure routing processes for use with the routing engine, reference the instructions in the Ensemble HL7 Version 2 

Development Guide or the Ensemble HL7 Version 3 Development Guide. 

3.3.3 Business Operations 

A business operation formulates and send a request to a target outside the Ensemble production. Business processes accept 

requests from business services and from business processes, and if designed to do so, also return a response to the requestor. 

Operation Task 

Add a business operation to a production. 

Establish credentials for remote connections to external 

systems. 

Remove a business operation from a production. 

View or configure operational settings for a business 

operation. 



Operation 




A workflow operation is a special type of business operation used to direct requests for human workflow to the Ensemble 

Workflow Engine rather than to an external application or database. Workflow operations have their own host class, 

EnsLib.Workflow.Operation, which inherits from the business operation host class. To use a workflow operation in a production, 

you must add and configure it as for any other business operation, using the tasks described in the preceding table. However, 

there are additional details for workflow operations only. See the book Using Workflow with Ensemble. 

3.3.4 Scheduling Configuration Items 

The default scheduling for configuration items is for them to run whenever the production is running. However, a finer 

control is possible. Not only can you enable and disable configuration items, but the [Ensemble] > [Productions] > [Configuration] 

page also offers a Schedule setting for each configuration item. This is an optional command string that schedules 



the item to be stopped and started at specific times and on specific days of the week, month, or year. When it is time to 

start, if the item is enabled, the scheduler starts it; when it is time to stop, if the item is running, the scheduler stops it. 

The Schedule string is a comma-separated list of event specifications. Each event specification has the following format: 

action:YYYY-MM-DDThh:mm:ss 

Where each item in the event specification, from left to right, has the described values: 

Item 

action 

: 

YYYY-MM-DD 

Possible Values 

START or STOP indicates the desired action 

Required separator 

Either: 

• YYYY is the year as 4 numerals 

• MM is the month as 2 numerals 

• DD is the day of the month as 2 numerals 

• Any of these fields may be the single character * (asterisk) indicating all years, 

all months, or all days 

Or: 

• YYYY is the word WEEK 

• MM is the specific occurrence of the day of the week (indicated by DD) in the 

month (01 = first occurrence of the specific day of the week in the month, 02 = 

second occurrence in the month, etc.) 

• DD is a specific day of the week (00 = Sunday, 01 = Monday, etc.) 

• MM may be * for all occurrences and DD may be * for all days 

Once a field is specified as *, all fields to the left of it are also assumed to be *.Thus, 

if the DD value is *, the MM value is treated as * even if it has a specific numeric 

value. Similarly, if MM is *, YYYY is treated as *. 

T 

hh:mm:ss 

, 

Required separator 

Hour, minute, and second 

Use the comma separator only if there is another event specification after the current 

one. Do not use it at the end of the Schedule string. 

If your schedule contains recurring events, the Schedule setting requires both START and STOP actions. If your schedule 

setting is an absolute one time event, then you need only use the appropriate single START or STOP action. In most cases, 

Schedule strings should contain both a START and a STOP action. 

Some examples of Schedule strings follow: 

• Start the configuration item every day at 8 a.m. and stop it every day at 5 p.m. 

START:*-*-*T08:00:00,STOP:*-*-*T17:00:00 

• Stop every year on January 2 at 7 a.m. and start again on January 3 at 7 a.m. 

STOP:*-01–02T07:00:00,START:*-01-03T07:00:00 



• Start every month on the second day of the month at 8 a.m. and stop every month on the tenth day of the month at 8:30 

p.m. 

START:*-*-02T08:00:00,STOP:*-*-10T20:30:00 

• Stop every Sunday at 10 a.m. and start every Monday at 8:30 a.m. 

STOP:WEEK-*-00T10:00:00,START:WEEK-*-01T08:30:00 

• Start every third Tuesday at 9 a.m. and stop every third Friday at 4 p.m. 

START:WEEK-03-02T09:00:00,STOP:WEEK-03-05T16:00:00 

• Stop on December 31, 2010 just before midnight. 

STOP:2010-12-31T23:59:59 

• Start on January 3, 2011 at 6:45 a.m. 

START:2011-01-03T06:45:00 

• The following two strings are equivalent: Start every day at 2 a.m. 

START:*-*-*T02:00:00 

START:WEEK-*-*T02:00:00 

See the Ens.ScheduleHandler entry in the Class Reference for more information. 

The following sections provide details on Daylight Saving Time considerations with using the Schedule configuration setting 

and also the intended use and limitations of the setting. 

3.3.4.1 Scheduling and Daylight Saving Time 

When daylight saving time (DST) begins, clocks skip an hour that day, usually from 2:00 a.m. to 3:00 a.m. Any item you 

have scheduled that falls into that nonexisting hour takes place at the beginning (which is also the end) of that hour. For 

example, on the day DST begins, an event scheduled to take place at 2:15 a.m. takes place at 2:00 a.m. (which is also 3:00 

a.m.). 

When DST ends, an hour of the day repeats, usually from 1:00 a.m. to 2:00 a.m. Any item you have scheduled that falls in 

that repeated hour takes place only once. Whether the event takes place on the first occurrence of the scheduled time or the 

second occurrence in the repeated hour depends on the operating system, but it only takes place once. For example, on a 

Windows system on the day DST ends, an event scheduled to take place at 1:15 a.m. takes place at the second occurrence 

of 1:15 a.m. 

3.3.4.2 Intended Use and Limitations of the Schedule Configuration Setting 

The Schedule setting starts and stops production business hosts according to a schedule; it is not a task scheduler. The 

schedule string defines a square wave in time declaring during what time intervals the item should be running, in between 

which it should be not be running. Ensemble cannot prevent scheduled transitions from being interrupted or superseded by 

other production events. 

The scheduler wakes up periodically (it sets its own alarm clock for when any scheduled item next expects a transition) 

and attempts to start or stop any items that are not currently in the expected state according to their schedule strings. It runs 

the UpdateProduction() method of the Ens.ScheduleHandler class and checks what event it needs to schedule next. 

There are two general classes of things that can prevent transitions from taking place as the schedule string indicates: 

• One is if the scheduler is unable to cause the intended state change; that is the UpdateProduction() method fails to 

affect the relevant items. 



For example, an item could be in a Read timeout or some other busy state that lasts longer than the Update timeout. 

Another example is a configuration item the scheduler starts cannot be stopped by the scheduler if the item is in the 

middle of a synchronous call. The configuration item must wait for a response to the call before the scheduler stops 

it. See the “Working with Messages” section. 

• The other is if the scheduler itself is prevented from waking up at the intended time. Examples of conditions that could 

cause this: the CPU is busy, a queue builds up of the alarm clock messages for the scheduler, the scheduler is itself 

disabled or crashed, the production is down, etc. The scheduler is not guaranteed to wake up during any particular 

interval, and when it does wake up it only looks at the intended state for the current moment, not at any history of when 

it should have woken up. 

Use of the schedule setting is not intended or designed as an event signaling device. It is intended to accommodate planned 

outages and scheduled intervals of activity or inactivity. If you have events that you must trigger at a particular time or as 

soon as possible thereafter, Ensemble offers better alternatives: 

• You can configure your business service to use an inbound adapter with the implemented OnTask() method where 

you call the business service. Ensemble provides classes for many types of inbound adapters. See the Ens.InboundAdapter 

entry in the Class Reference and the books in the Ensemble Adapter Guides set for details. 

• If you do not want to use an adapter, you can call the business service programmatically and schedule it to run using 

the [Home] > [Task Manager] page (/csp/sys/op/UtilSysTaskHome.csp) in the Management Portal. This gives you finer 

control in situations such as the system being down at 1:00 a.m. 

The recommended approach is to configure the business service with Pool Size = 0 and then use the Task Manager to 

launch a task that calls CreateBusinessService on it and invokes ProcessInput() on the resulting service instance 

object. The advantage of calling a business service this way is that you call it at the time you want and it runs only 

once. If Ensemble happens to be down at that time, your task can register an error. See the following sections for 

details: 

– “Using the Task Manager” section of the “Managing Caché” chapter of the Caché System Administration Guide 

– “Invoking a Business Service Directly” section of the “Business Services” chapter of Developing Ensemble 


3.3.5 Assigning Configuration Items to Categories 

The [Ensemble] > [Productions] > [Configuration] page offers a Category field for each configuration item. This is an optional 

text label that you can use to visually group configuration items within the production diagram. 

Once you have provided Category values for configuration items, when you are viewing the production configuration diagram 

you can right-click on the background of the diagram. Choose Show Category and a category name from the context menu. 

The diagram changes to reveal only those configuration items that match the Category name you have just selected. The 

diagram displays the Category name at the top left of the diagram, below the production name. 

Alternatively, when you choose Show Category, select All (the first option) to reveal all configuration items, regardless of 

category. 

Each category name is case-sensitive, and it may contain spaces. You may assign a configuration item to more than one 

category by providing a comma-separated list of category values in the Category field. Do not use leading or trailing spaces 

around these commas, as these are interpreted as characters within the label and can prevent what would otherwise be a 

proper match. Use: 

TEST,My Test Category,MINE 

Not: 

TEST, My Test Category , MINE 


Working with Credentials 

3.4 Working with Credentials 

Some remote systems require a username and password to log into that system. A username-and-password pair is a login 

credential. 

Ensemble permits you to store login credentials in a centralized table that can be viewed and edited only by users with 

access to the Ensemble Management Portal. This table, called the Credentials table, provides ease of management and 

protects login data from unauthorized access. Users can edit the Credentials table only by logging into the Ensemble 

Management Portal and choosing the Maintenance option, then Credentials. 

Each username-and-password pair in the Credentials table has an ID. When configuring an inbound or outbound adapter 

using the Ensemble Management Portal, you can enter this ID in place of the username or password that is required to log 

into the remote system. 

An adapter that uses credentials logs itself into a remote system as follows: Using the ID as a key into the Credentials table, 

it gets the username and password from the table and sends them to the remote system with a request to log in. 

This means that system administrator can log into the Ensemble Management Portal to change the username and password 

values for an ID, without disturbing any other data in the production configuration. 

When using the Ensemble Management Portal, you can confirm that an adapter uses credentials as follows: Open the configuration 

display on the [Ensemble] > [Productions] page. Choose a business host to configure. In the Specific Settings 

column, look for a Credentials field. If the Credentials field is not present, the adapter does not permit credentials to be 

configured for it. 

If the Credentials field is present in the configuration display, it must contain an ID from the Credentials table. If there is 

no appropriate entry in the Credentials table, you must create it, and enter its ID into the Credentials field for the adapter to 

work. 

Credentials Task 

Establish credentials for remote connections to external systems. 

Configure the remote connection settings for a business service. 

Configure the remote connection settings for a business operation. 





3.5 Working with Dashboards 

Ensemble supports business activity monitoring (BAM) by enabling developers to provide browser-based “corporate 

dashboards” that display graphical, real-time information about an Ensemble production. The following Ensemble elements 

support dashboards: 

• Business metrics are specialized business service classes that gather or otherwise calculate specific measured data 

called metrics. After you add a business metric to a production, it is automatically triggered to calculate the values of 

its properties at the time interval specified by its Call Interval configuration setting. These calculations can take a variety 

of forms, involving calls to business operations, federated databases, the Ensemble storage layer, or any arbitrary source 

code contained within the business metric class. 

• Dashboards are Web pages that provide a real-time, graphical display of metric values. Each dashboard presents one 

or more meters; that is, graphical elements that display the current value of a specific metric property within a specific 

business metric class. Ensemble provides a complete set of built-in meters that includes speedometers, odometers, fuel 

gauges, light bars, traffic lights, indicator lights, line charts, and bar charts. A production can also include custom 

meters. 



Each dashboard is associated with a specific production, displays values from that production, and can be viewed “live” 

from the Ensemble Management Portal whenever that production is running. The following tasks are required to configure 

and run dashboards: 

Dashboard Task 

Add a business metric to a production. 

Configure the Call Interval for a business metric. 

View current values of data being collected by a business 

metric. 

Monitor dashboard activity. 



Service 


Business Metrics, Properties 


For full details, see the book Using Dashboards with Ensemble. 

3.5.1 Dashboards 

The [Ensemble] > [Dashboards] page displays when you click Dashboards in the Ensemble Management Portal main menu. 

This topic briefly introduces the page. For full details, see Using Dashboards with Ensemble. 

3.5.1.1 Dashboard List 

At left, the [Ensemble] > [Dashboards] page reveals the same menu as on the [Ensemble] home page. You can click on 

selections in this menu to navigate to other portal pages. 

To the right and below the title bar, the Dashboard page displays a table called Available Dashboards. This table lists all 

the dashboards associated with productions in the currently active namespace. 

To the right of each entry in the Available Dashboards table are two commands: 

• Click View to display the dashboard. If you click on one of the meters in the top half of the screen, the bottom half 

displays detailed information about that meter. 

• Click View (no frames) to display the dashboard without the Dashboard page title bar (above) or the information frame 

(below). 

3.5.1.2 Dashboard Display 

When you click View to the right of an entry in the Dashboard page table, the display changes to the [Ensemble] > [Dashboards] 

> [Dashboard] page, which displays the specific dashboard you selected. Graphical meters display in the top half of the 

screen, according to the dashboard definition. 


Working with Dashboards 

Figure 3–1: Dashboard Page with an Active Dashboard 

If the production that includes a dashboard is not currently running, the dashboard is dimmed (inactive). To activate an 

inactive dashboard, stop the currently running production (if any) and start the production whose dashboard you want to 

view. Then, return to the [Ensemble] > [Dashboards] page and click View next to the dashboard name. 

Note: 

For dashboards to be able to refresh the page, you must make sure Internet Explorer has the Java Virtual Machine 

(JVM) enabled. You can verify this by selecting Tools, Internet Options, and clicking the Advanced tab to look 

at Java options. 

If you right-click on a meter in an active dashboard display, a context menu displays. The following menu options are 

available: 

• Drill Down — If the production developer has enabled the Drill Down feature for this metric, this selection displays a 

browser page that contains additional information related to the metric. When you are done viewing this information, 

click the browser Back command to return to the [Ensemble] > [Dashboards] > [Dashboard] page. 

• Zoom — Choose a zoom factor for the dashboard. 

• Change Chart Scale — A chart can be defined so that each data series has its own scale for the y-axis. When this is the 

case, you can click on the chart in the dashboard to select it, then right-click and choose Change Chart Scale to display 

the y-axis that corresponds to the next data series in the chart. Repeat to walk through all the possibilities for the chart. 

• Find, Find Again — Search for a text string on the dashboard. 

• View Source — Display the SVG code that displays the diagram. 

• About SVG Viewer — Display version and copyright information about the SVG Viewer used to render the dashboard. 

3.5.2 Business Metrics 

The [Ensemble] > [Business Metrics] page allows you to view the values contained within active business metrics in the 

currently running production. The Business Metrics page is useful to developers and system administrators solving problems 

encountered with the system. When a production is running smoothly, the intended display page for business metrics is the 

[Ensemble] > [Dashboards] > [Dashboard] page. 

The Business Metrics page displays when you click Business Metrics in the Ensemble menu. At left, the Business Metrics 

page reveals the same menu as on the [Ensemble] home page. You can click on selections in this menu to navigate to other 

portal pages. 



At far right, the title bar provides a Namespace drop-down list that you can use to switch to a different Ensemble namespace. 

There is also a Go to drop-down list that you can use to return to previously visited pages in the Ensemble Management 

Portal or System Management Portal. 

To the right and below the title bar, the Business Metrics page displays a table that lists all the business metrics associated 

with productions in the currently active namespace. 

To the right of each entry in the Business Metrics table is a Properties command to display the [Ensemble] > [Business 

Metrics] > [Business Metric Properties] page. Below the title bar and to the right of the main menu, a line of text displays: 

• Contents of Business Metric Cache for myMetric: 

Where myMetric is the business metric whose Properties command you clicked on the previous page. 

Beneath this introductory text is a table, with the following columns from left to right: 

• Instance — In the typical case, there is a single instance for the business metric, so the Instance column contains the 

number 1, and can be ignored. 

If the business metric defines multiple instances, the Instance column lists the name of the instance that contains the 

values shown in columns to the right. The table lists instances in the order in which the business metric class code 

defines them. 

• Property — The name of a business metric property. The table lists each property in the business metric class in 

alphabetical order by property name. If the business metric defines multiple instances, the table lists the properties for 

the first instance, then the properties for the second instance, and so on. 

• Value — The current value of the property. The values shown reside in the business metric cache. If a property has no 

value or is an empty text string, the cell is blank. 

If the values are actively changing, the display refreshes itself at the time interval set by the business metric Call Interval. 

You can also click the Refresh command in the browser to update the values in the display. 

• History — In the typical case, the property is single-valued, so this cell is blank. 

If the property is a multidimensional property with an automatic history, the History column lists a history of values 

that the property has held over time. This comma-separated list that begins with the oldest cached value at the top left 

of the History cell for that property; the History reads sequentially from left to right, and from top to bottom. 

The bottom right value in the History cell for a property is the same as the current Value of that property. 

3.6 Working with Business Rules 

Each business rule is an independently defined piece of logic that can be invoked from a BPL business process or routing 

business process. The details of any business rule are defined by editing it using the graphical Business Rule Editor. The 

tasks in the following table are associated with business rules. 

Business Rule Task 

Add a new rule set definition. 

Add a new routing rule set definition. 

Edit an existing rule definition. 

Invoke a routing rule. 

Purge the business rule log. 






Maintenance, Purge Management Data 


Working with the Event Log 

Business Rule Task 

View a record of rule activity for the currently running 

production. 

View an existing rule definition. 




For full details, see the book Using Business Rules with Ensemble. 

3.6.1 Business Rules Pages 

The [Ensemble] > [Business Rules] page displays a list of the business rules defined in the currently running production. A 

business rule determines how a business process will behave at a specific decision point. 

A rule definition is entirely separate from business process code. Rule definitions are stored in the Ensemble database and 

are evaluated at runtime. Modifications to rule definitions are simply updates to the database and can be instantly applied 

to a production that is still running. 

The developer of a BPL business process identifies a decision point by naming the business rule that will make the decision 

at this point. A user at the enterprise, typically a business analyst, defines the criteria that the rule will use to make the 

decision. The tool for creating and modifying this list of criteria is the Business Rule Editor. 

At runtime, the business process invokes the rule, the rule returns an answer to the business process, and the business process 

continues execution based on this answer. Meanwhile, Ensemble creates an audit entry that contains information about the 

business process that fired the rule, what value was returned, and why the answer was chosen. The Business Rule Log lets 

you view this information. 

You can display the Business Rules page from the Ensemble Management Portal as follows: 

• From the Ensemble menu click Business Rules to display the [Ensemble] > [Business Rules] > [Business Rule Editor] 

page. 

• Click Rule List at the top of the page. 

For details about the Business Rules page, Business Rule Editor, and Business Rule Log, see the “Managing Business 

Rules” chapter in Using Business Rules with Ensemble. 

In addition to regular business rules, message routing rules are also available. See the Ensemble HL7 Version 2 Development 

Guide or the Ensemble HL7 Version 3 Development Guide. 

3.7 Working with the Event Log 

Ensemble generates event log entries to record the following items: 

• Normal occurrences in the life cycle of any production, such as starting or stopping the production. 

• Abnormal occurrences, such as errors or warnings, that a specific production records in the event log. 

• Occurrences associated with debugging a production, such as traces or asserts. 

Viewing the event log is a way to “take the pulse” of a production by scanning the event log entries that it produces while 

it runs. The following options are available. 



Event Log Task 

Filter event log entries for the currently running production by entering 

search criteria such as time of day or session identifier. 

Purge event log entries. 

Quickly view the real-time status of the event log. 

View the event log entries generated by the currently running production. 


Event Log, Filter 

Event Log, Purge 


Event Log 

Not all errors or activities should necessarily generate an event log entry. Developers of custom code determine which 

abnormal occurrences a host class will write to the event log. Once a production is running, only those events can be 

monitored. It is up to the developer to choose which occurrences will be of interest to enterprise system administrators. 

The only way to cause the production to report additional new types of event is to rewrite its host classes using Ensemble 

Studio. However, you can use the Ensemble Management Portal to control what you see in the event log in another way: 

You can filter the event log to exclude all entries except those of special interest to you. 

3.8 Working with the I/O Archive 

All business services and business operations have a configuration setting called Archive IO. If True, the adapter associated 

with this business host logs in the Ensemble I/O archive each input and output communication it shares with the external 

system. 

I/O Task 

Configure the Archive IO setting for a business operation. 

Configure the Archive IO setting for a business service. 




To retrieve information from the Ensemble I/O archive, you must execute an SQL query, as follows: 

1. Start the System Management Portal. 

2. Navigate to the [Home] > [SQL] page. 

3. Choose the namespace where you want to execute the query. 

4. Click Execute SQL Statement. The [Home] > [SQL] > [Execute SQL Query] page displays. 

5. In the SQL Query field, type: 

SELECT * FROM Ens_Util.IOLog 

Where the table name identifies Ens.Util.IOLog or one of its subclasses. The choice of subclass depends on the type of 

data. Options include Ens.Util.IOLogFile, Ens.Util.IOLogObj, Ens.Util.IOLogStream and Ens.Util.IOLogXMLObj. 

6. Click Execute Query. The results display in the bottom half of the page. 

7. If there are no results, or if the results do not match your expectations, check to see that the Archive IO option is enabled 

for the business service or business operation that you want to investigate. 


Working with Jobs 

3.9 Working with Jobs 

Jobs are CPU processes that host the work done by an Ensemble production. This terminology is intended to avoid confusion 

between CPU processes (“jobs”) and business processes (“processes”). From a low-level, system viewpoint, an Ensemble 

production consists almost entirely of jobs waiting to wake up to perform work. When a request arrives on the queue of a 

business host, the item claims a job from its pool of available jobs. The job then hosts the work that needs to be done. If 

no job is available in the pool of jobs for that business host, it must wait for a job to become available, so that it can do the 

work. The job returns to the pool after the work is done, or whenever the next task is to wait for something to happen. A 

job always returns to the same pool from which it came. 

The choice of Actor Pool Size for the production, and Pool Size for each business host, determines how many jobs are 

available to perform which types of work for the production. These numbers are an essential part of the production design 

and are unlikely to need adjustment once the production is deployed live. Larger numbers are not necessarily helpful; most 

pool sizes are best set to either 0 or 1. For a full discussion of appropriate values for different types of production, see the 

Pool Size section in the “Production Concepts” chapter of Developing Ensemble Productions. 

The following portal commands are available to configure and monitor job use in a production. 

Job Task 

Configure the number of jobs allocated to a specific business 

operation within a production. 


process within a production. 


service within a production. 

Configure the number of jobs allocated to be shared publicly 

by business processes. 

Monitor status of system jobs associated with various 

production activities. 






Jobs 

3.9.1 Jobs Page 

The [Ensemble] > [Jobs] page allows you to match each Ensemble configuration item with the underlying system job(s) 

that are hosting its activities. The Jobs page lists the system Job ID number for each configuration item. You can use this 

information to look up detailed information about the job in the System Management Portal. The same Process ID number 

appears in the left-most column of the System Management Portal [Home] > [Processes] page. 

To display the Jobs page, click Jobs in the Ensemble Management Portal main menu. 

There is no menu on the Jobs page. You can return to the home page by clicking [Ensemble] in the title bar navigation path. 




Under the Jobs page title bar is a table called Current Ensemble Processes. Each row of the table lists one of the system 

jobs that is doing work for the currently running Ensemble production. Each row has the following columns: 

• Job — The system process ID for the job. 

• Configuration Name — This is the name assigned to the business host during configuration using the [Ensemble] > 

[Productions] configuration display. It may be different from the host class name. 



• Mode — The execution mode for the job: Background or Foreground. This is the value you set when defining the host 

using the [Ensemble] > [Productions] configuration display. If you selected the Foreground check box, the Mode field 

reads Foreground; otherwise it reads Background. 

• Status — Dequeuing, Running, Error, or Quiescent. Most jobs run in less than 1 millisecond, so it is almost impossible 

to see an entry on the Jobs page with a Running status, unless it is stuck in an infinite loop of some kind. All jobs 

should become Quiescent during production shutdown, and if one does not do so, there may be a problem with it. In 

all other cases entries on the Jobs page have a Status value of Dequeuing. 

Ensemble may terminate a job, in which case its last known status prior to termination appears in the Status column, 

and the background color of the row is red. This is called a “dead” job. 

• Detail — This string contains information relating to the Status field. If the status of the job is Running, the Detail field 

is blank. If the status of the job is Dequeuing or Quiescent, the Detail field lists the following information: 

– The current queue name (for public queues such as Ens.Actor) 

– The job ID (for private queues associated with specific business hosts). 

• Active Message — If there is currently a message from this job, this column displays it. 

• State — Dead, Starting, or Alive. 

In each row, the background color indicates the job’s status, as follows: 

• Blue — A startup job. 

• (Neutral) — Jobs that are Dequeuing, Running, or Quiescent. 

• Pink — A job that has Error status but is not dead. 

• Red — A dead job. 

3.10 Working with Messages 

All communication that passes between configuration items in Ensemble is accomplished using messages. A message has 

a header, which is the same for all messages and contains data fields that help route the message through the system. A 

message also contains a body, which provides different fields depending on the message contents. 

Every message class is one of two types: request or response. There may be request classes that do not have a corresponding 

response class defined, but every response is (conceptually) paired with a request. Any request class may be synchronous 

(waits for a response) or asynchronous (does not wait) in its implementation. These decisions are made by the class developer 

and they are not configurable once the production is complete. 

Ensemble offers some built-in message classes to handle various types of message content. Other message classes may be 

defined by class developers to fulfill a specific production need. Without exception, all instantiated messages have complete 

tracking information stored in the Ensemble message warehouse, and this information is available at all times to the 

Ensemble Management Portal pages devoted to messages. 

Since messages are the primary “currency” of action and communication within Ensemble, there are a large number of 

management tasks associated with messages. The following table lists what you can do to work with messages using the 

Ensemble Management Portal. 

Message Task 

Filter and view messages in various ways. 




Working with Messages 

Message Task 

Filter the message log for the currently running production by 

entering search criteria such as time of day or session identifier. 

View the contents of two messages and compare them, side by 

side. 

View message body contents. 

View message header and body contents for a message. 

Periodically save older messages to a separate archive for long 

term storage. 

Resend selected messages. 

View messages that have entered a Suspended state. Resend 

selected messages. 

View a visual trace of the delivery of a message, from original 

source all the way through to fulfillment (or failure). 

Test HL7 or X12 messages, by viewing and transforming them. 

Test a production by sending request messages and receiving 

responses. 


Message Browser, Filter 

Message Browser, Compare Messages 

Message Browser, Contents 

Message Browser, Details 


Message Browser, Resend Messages 


Message Browser, Trace 

EDI / HL7 Manager, Message Viewer 


3.10.1 Message Status 

When you trace messages using the Ensemble Management Portal, you see a visual representation of each message as it 

travels from one configuration item to the next. The message object can have various status values that indicate its rotation 

through a normal life cycle. These status values are visible on most Ensemble Management Portal message pages: Created, 

Queued, Delivered, Deferred, Completed, Discarded, or Suspended. These status values apply to instances of request and 

response messages individually. Request-response “pairs” are not tracked together, because a request might be repeated 

several times before it is successfully delivered, some requests have an optional response that can be ignored if it does not 

arrive, some responses can be deferred for later delivery, and some requests have no response defined for them at all. 

Message Status 

Completed 

Created 

Deferred 

Delivered 

Discarded 

Queued 

Suspended 

Meaning 

The intended recipient has received the message and has finished processing the 

message. 

The message is in transit between sender and target. 

The message response has been deferred by the business operation for later delivery. 

The intended recipient has received the message. 

The message is a response that reached its destination after the timeout period for the 

corresponding request expired. 

The message is on a queue. 

The message was suspended by the business operation after failing to reach its external 

destination, or by an administrator from the Instances display on the [Ensemble] > [Host 

Monitor] page. In either case, you can resend the message from the [Ensemble] > 

[Maintenance] > [Suspended] page or by clicking the Resend Messages command on the 

[Ensemble] > [Messages] page. 



3.10.2 Messages in Progress 

It is not always possible for a message to be immediately Delivered. Most host classes provide some level of recovery from 

initial obstacles that a message might encounter. Obstacles to delivery might arise for any number of reasons, including 

circumstances outside the Ensemble system (an external server goes down) or the need to wait for a decision from another 

business process or human participant (workflow). The different message status values help you to track what is happening 

to message that are not yet Delivered. Details are as follows: 

• In many cases, business operations are designed to retry a message a given number of times, at given intervals, before 

declaring the message failed or announcing a timeout. Many outbound adapters offer configurable parameters that 

control the time interval and number of retries to make. If this is the case, you can set these values when you configure 

Specific Settings for the business operation using the Ensemble Management Portal, without changing any classes in 

Studio. 

• Some business operations are designed to set the status of any failed messages to Suspended. Alternatively, you can 

manually suspend a message from the Instances display on the [Ensemble] > [Host Monitor] page. In either case, 

Ensemble automatically places all Suspended messages on a special queue. A system administrator can find these 

message on the [Ensemble] > [Maintenance] > [Suspended] page. An inspection of the routing information or contents 

of a specific message might reveal the reason why the message failed. For example, if the problem is that an external 

destination went out of service, a change can be made to reestablish communication with that server. Then the Suspended 

messages can be resent to the external server by clicking a command on the [Ensemble] > [Maintenance] > [Suspended] 

page or by clicking Resend Messages on the [Ensemble] > [Messages] page. 

• There is a message status that does not indicate either delivery or failure; that is the Deferred status. A business operation 

can set the status of a response message to Deferred before it exits. The Deferred response can be picked up and sent 

back to the original requester by any business host in the production. Between the time when the business operation 

defers the response, and when the response is finally sent, the response message has a status of Deferred. The sender 

of the original message is unaware of the fact that the message was Deferred. If the original call was synchronous, the 

call does not return to the sender until the deferred response is sent. 

3.11 Working with Queues 

In the Ensemble context, a queue is simply a list of message objects waiting to be processed by a business host — a business 

service, a business process, or a business operation — within a production. No queue setup is required. Ensemble manages 

all queues automatically; see the Queues section in the “Ensemble Messages” chapter of Developing Ensemble Productions 

for details. 

The following portal commands are available to monitor queue status. 

Queue Task 

List the messages on a specific queue. Provide a facility for viewing these 

messages in detail. 

Monitor the activities of a message queue in detail. 

Quickly view the real-time status of message queues. 


Queues, Contents 

Queues 


Queues offer one of the most useful means of quickly spotting a problem in the system. When there is buildup on a queue, 

it usually means something needs to be repaired. For example: 


Working with Sessions 

• If a service or operation queue is suddenly longer, this means that messages created by Ensemble suddenly cannot get 

out of the system, or that messages from outside the system suddenly cannot get in. An external connection may be 

down, or there may be a peak-hour effect that is affecting throughput on your external connections. 

• If a service or operation queue is consistently long, this means that messages created by Ensemble consistently cannot 

get out of the system, or that messages from outside the system consistently cannot get in. The pool of jobs for that 

service or operation may need to be larger, or you may need to reconfigure the external connection to overcome an 

entrenched issue there. 

• If the Ens.Actor queue is suddenly longer, a business process may have experienced an error that has caused it to become 

“stuck” in some way. 

• If the Ens.Actor queue is consistently long, the actor pool for the production may need to be larger. 

• If many queues have a consistently large buildup, there may be a general capacity issue on the host computer, the 

Ensemble production (in its role as a CSP application) may need more resources, or the underlying Caché installation 

may need to be tuned. For suggestions about how to allow enough capacity, see the Caché System Administration 

Guide and Using Caché Server Pages (CSP). In general, however, you will be able to keep queues moving with the 

simpler adjustments listed in this topic. 

Usually the most important information that the portal provides about queues is the destination, or target, of any message 

that has been too long on a queue. In general, when a queued message is not being sent, it is because it cannot get to its 

target. This means there is something wrong with the target of the queue (its associated service or operation, for example). 

If you can find out what is causing a problem with the target, when you solve that problem, the queue buildup generally 

disappears. 

3.12 Working with Sessions 

A session defines the boundaries of a primary request — one that enters Ensemble from an external source. A session exists 

from the moment the primary request enters Ensemble, usually via a business service. The session continues to exist while 

the production generates internal requests and responses to process the primary request. When the last internal activity 

prompted by the primary request is done, the session is over. If the primary request required a response, the final act that 

the production performs within the session is to formulate and send this response. 

Session Task 

Filter the message log for the currently running production to find all 

messages associated with a specific session. 

View a visual trace of a primary request message, from its original, external 

source all the way to fulfillment (or failure). 



Message Browser, Visual Trace 

3.13 Working with Workflow 

Workflow makes it possible to incorporate human interaction into automated business processes. Typical uses of workflow 

within the enterprise might include order entry, order fulfillment, contract approval, and help desk activities. 

A workflow management system automates the distribution of tasks among users. Tasks are distributed according to a 

predefined distribution strategy. This convention makes task distribution more efficient and task execution more accountable. 

Ensemble has a built-in Workflow Engine that supports a variety of default and custom distribution strategies for tasks and 

users. 



Workflow Task 

Manage workflow, define user roles, and accept tasks. 



3.13.1 Workflow Portal 

The browser-based user interface for managing workflow, defining user roles, and accepting tasks is called the Workflow 

Portal. You can access it from the Ensemble menu, by selecting the Workflow Portal option. When you do this, the 

[Ensemble Workflow] page displays. From here you can access any of the following pages: 

• [Ensemble Workflow] > [Workflow Tasks] — Accept and complete tasks, or relinquish tasks to other users. 

• [Ensemble Workflow] > [Workflow Roles] — Sort workflow users into workflow roles. 

• [Ensemble Workflow] > [Workflow Users] — Identify workflow users. 

• [Ensemble Workflow] > [Task Browser] — View a history of task activity, assign tasks, edit or cancel tasks. 

• [Ensemble Workflow] > [Worklist Browser] — View a list of all uncompleted tasks. 

For full details, see Using Workflow with Ensemble. 


4 


The [Ensemble] > [Productions] page contains a table with information about all the Ensemble productions that are defined 

in the current namespace. Only one of these productions can run at a time. If you try to start one, and another is already 

started, a warning message displays and nothing changes. You can stop the running production and start another one from 

the Ensemble Productions page. You can also use the page to navigate to a specific production in the list to configure. You 

can display the Productions page from various locations in the Ensemble Management Portal, as follows: 

• From the Ensemble Menu — Click Productions 

• From the Ensemble Table on the Ensemble Home Page — Click more... 




Under the Productions page title bar is a display area. At the top left corner of this display is the Ensemble Management 

Portal menu. This is the same menu as on the home page. You can click on selections in this menu to navigate to other 

portal pages. 

Above the Production List are two commands: 

• Click Create New Production to start the production wizards that create new productions. For instructions, see the 

“Creating a New Production” chapter in Developing Ensemble Productions. 

• Click Delete Production to remove an existing production from the namespace. 

From this page, you can choose which production to delete from a list of existing productions. As an added safeguard, 

you can click View Configuration Details before confirming the delete to verify you are deleting the appropriate production. 

4.1 Production List 

Under the Productions page title bar and to the right of the menu is a table that lists all the productions associated with the 

currently active namespace. You can begin typing any string in the Filter box to narrow down the list of productions. Each 

row is devoted to one production and has the following columns of information: 

• Production — The name of the production. 

• Status — The status of the production — Running, Suspended, Troubled, or Stopped — as described in the following 

table. 

• Last Start Time — The date and time when the production was last started. 



• Last Stop Time — The date and time when the production was last stopped. 

Table 4–1: Production Status Values 

Status 

Value 

Running 

Stopped 

Suspended 

Troubled 

Row Color 

Light green 

Light gray 

Orange 

Light gray 

Meaning 

When a production has been started and is operating normally, it has a status 

of Running. This is an acceptable state. 

A production acquires a status of Stopped when, at the end of the shutdown 

sequence, all of its queues are free of synchronous messages. This is an 

acceptable state. 

A production acquires the Suspended status if, at the end of the shutdown 

sequence, some queues still contain synchronous messages, waiting for a 

response. Depending on how the production has been designed, this may or 

may not indicate a problem. 

You may start a Suspended production. Starting the production again may 

permit the waiting messages to be processed. However, if you start the Suspended 

production, and more messages arrive while those in front of them in 

the queue cannot be resolved, queues may simply continue to fill. In that case 

you must investigate to discover why the incoming messages never complete. 

A production acquires a status of Troubled if Ensemble is stopped but the 

production did not shut down properly. This can happen if you restarted 

Ensemble or rebooted the machine without first stopping the production. 

When a production acquires a Troubled status, a Recover command appears 

on the Ensemble Management Portal home page (the [Ensemble] page). Click 

this command to clean up the troubled instance of the production so that you 

can run a new instance when you are ready. 

To the right of each entry in the Productions table are four of the following five commands: 

• Click Configure to display the configuration diagram. This is a graphical inventory of the business hosts in the production, 

organized into three columns: business services, business processes, and business operations. Each item in the diagram 

displays runtime status indicators. You can select individual elements to monitor and edit the details of performance 

and configuration. For details about this diagram, see the “Configuration” chapter. 

• Click Start to Start the production; offered if the production is stopped. 

• Click Stop to Stop the production; offered if the production is running. 

• Click Documentation to view or generate configuration documentation for this production in HTML format. 

4.2 Starting a Production 

You can start an Ensemble production from various pages in the Ensemble Management Portal, including the Productions 

page. To do so: 

1. The initial command sequence you choose depends on which page you are viewing when you begin. For example, you 

can: 


Stopping a Production 

• Begin from the home page. If the Ensemble panel (top left) displays a Stopped status and a Start Production 

command, examine the name in the Production field. If this production is the one you want to start, click Start 

Production. Otherwise, click more... to display the Productions page. 

• Begin from the [Ensemble] > [Productions] page. To start a production, find its name in the list and click Start to 

the right of it. If you want to view a production’s configuration details before starting it, you can click Configuration 

to the right of the production name. The production configuration diagram displays. 

• Begin from the configuration display on the [Ensemble] > [Productions] > [Configuration] page. While viewing the 

production diagram in the top half of the screen, click Start Production in the bottom half of the screen. 

2. Click Yes to confirm the action. 

3. The Production Start page displays the name of the production, its startup status, and any messages associated with 

production startup. 

Note: 

If any Terminal windows open as a result of starting the production, do not close them. 

4. When the startup Status is Finished, click OK at the bottom of the Production Start page. 

You can also configure an automatic start for an Ensemble production. On the [Ensemble] > [Maintenance] page, use the 

Auto-Start Production field to choose a specific production to start automatically at system startup, and stop automatically 

at system shutdown. 

4.3 Stopping a Production 

You can stop an Ensemble production from various pages in the Ensemble Management Portal, including the Productions 

page. To do so: 

1. The initial command sequence you choose depends on which page you are viewing when you begin. For example, you 

can: 

• Begin from the home page. If the Ensemble panel (top left) displays a Running status and a Stop Production 

command, examine the name in the Production field. If this production is the one you want to stop, click Stop 

Production. Otherwise, click more... to display the Productions page. 

• Begin from the [Ensemble] > [Productions] page. To stop a production, find its name in the list and click Stop to 

the right of it. If you want to view a production’s configuration details before stopping it, you can click Configuration 

to the right of the production name, and the production configuration diagram displays. 

• Begin from the configuration diagram on the [Ensemble] > [Productions] > [Configuration] page. While viewing 

production configuration information in the top half of the screen, click Stop Production in the bottom half of the 

screen. 

2. Click Yes to confirm the action. 

3. After a normal shutdown, the Production Stop page displays the name of the production, its shutdown status, and any 

messages associated with production shutdown. When the shutdown Status is Finished, click OK at the bottom of the 

Production Stop page. 

4. If the request to stop the production initially fails, the portal displays a message: 

“Production could not stop, do you want to force a shut down” 

And offers a command: 

Yes - Force to Shut Down 



If you click this command, the production is forced to shut down. 

You can also configure an automatic stop for an Ensemble production. On the [Ensemble] > [Maintenance] page, use the 

Auto-Start Production field to choose a specific production to start automatically at system startup, and stop automatically 

at system shutdown. 

4.4 Production Documentation 

From the [Ensemble] > [Productions] page, click Documentation in the appropriate row to generate or view production 

documentation, which includes a list of all the configuration items and their settings. 

If HTML documentation exists, you are prompted whether you want to Generate a new version of the documentation or 

View the documentation you previously generated. It may take a considerable amount of time to generate documentation 

for large productions; therefore, you may not want to generate new documentation if you have not made changes to the 

configuration of your production. 

You can also generate HTML documentation and additionally PDF documentation using the following methods in the 

Ens.Config.Production class: 

• CreateDocumentHTML — creates new documentation in HTML format. 

For example, to create documentation for Demo.Loan.FindRateProduction in HTML format: 

Set 

status=##class(Ens.Config.Production).CreateDocumentHTML("Demo.Loan.FindRateProduction",1,.URL,.ErrLog) 

• RemoveDocumentHTML — removes existing HTML-format documentation in the current namespace. 

• CreateDocumentPDF — creates new documentation as a PDF file. 

For example, to create documentation for Demo.Loan.FindRateProduction in PDF format, you can use the method in 

a statement similar to the following: 

Set 

status=##class(Ens.Config.Production).CreateDocumentPDF("Demo.Loan.FindRateProduction",1,"C:\Temp\Rate.pdf",.Log) 

The PDF format requires that you have a PDF renderer installed; if you have configured one for Zen, then it becomes 

the default renderer. See the Using Zen Reports guide for details. 


5 

Configuration 

The [Ensemble] > [Productions] > [Configuration] page allows you to configure operational settings for an Ensemble production 

in the active namespace. When you edit production settings using the configuration display, you can apply your configuration 

changes immediately, even if the production is running. 

You can view the configuration page from the [Ensemble] > [Productions] page by clicking Configure to the right of a production 

name. 

There is no menu on the Production Configuration page. Click Productions in the navigation bar to return to the list of 

productions. 

The following figure shows the configuration for the Demo.Loan.FindRateProduction contained in the ENSDEMO namespace. 

Figure 5–1: Configuration Page 

Under the Production Configuration page title bar are the following two display areas, one above the other: 


Configuration 

• Configuration Diagram — the upper display shows the production as a logical diagram. 

• Configuration Settings — the lower display provides data fields that you can edit to configure the production and its 

items shown in the diagram. 

You can drag the boundary between the displays to resize them as needed. In many cases you must use the scroll bars to 

see the full contents of either display. The following sections provide details on each portion of the Production Configuration 

page. 

5.1 Configuration Diagram 

At the top left corner of the configuration page is the name of the production, plus the message, Production Running, 

if that is the case. Under the production name are three columns, separated by vertical lines. From left to right, these columns 

contain Business Services, Business Processes, and Business Operations. 

The following sections describe the elements of the diagram in detail: 

• Configuration Shapes 

• Configuration Names 

• Configuration Icons 

• Status Indicators 

• Pool Size 

• Context Menu 

5.1.1 Configuration Shapes 

Any business service, business process, or business operation that has been added to the production appears as a rectangular 

shape in the configuration diagram, in the appropriate column. If the underlying host classes exchange Ensemble messages, 

lines connect the shapes across the columns. 

When you click on a shape in the configuration diagram, its background color changes to yellow and its connections to 

other entries change to bold purple. The data display at the bottom of the page also changes, to show which fields you can 

edit to configure the selected item. See the Configure Business Host Settings section for details. 

You can select any individual item by clicking it. To select the entire production, click anywhere in the neutral background 

of the diagram. 

The following figures provide a close view of one entry in each column on the page. 

Figure 5–2: Configuration Page Left Column — Business Service 

Figure 5–3: Configuration Page Center Column — Business Process 


Configuration Diagram 

Figure 5–4: Configuration Page Right Column — Business Operation 

When not selected, shapes in the diagram have the following background colors: 

Color 

White 

Gray 

Orange 

Business host status 

The item has been added to the production configuration and is enabled. 

The item has been added but is disabled. Compare the enabled FindRateFileService with 

the disabled FindRateEmailService in the full-size Configuration Page diagram in the previous 

section. 

The item is referenced by another item within the production, but is not yet added to the 

production. The background color changes to white or gray after you add the referenced 

item. 

5.1.2 Configuration Names 

The most important characteristic of any item in a production configuration is its name. 

By default, the name of a configuration item is the name of its underlying host class. When this is the case, the package 

name displays at the top of the shape. The host class name appears below the package name. For examples, see the business 

operations FindRateEmailOperation, FindRateFileOperation, and FindRateTCPOperation in the previous figures. 

You can assign the item a name that is different from its host class name. If so, the configured name displays in the item 

shape and no package name displays. This is true of the My Terminal Output business operation in the full-size configuration 

diagram at the beginning of this chapter. 

5.1.2.1 Different Configuration Names, Same Host Class 

Naming configuration items independently of their host class names provides flexibility in configuring your production. 

For example, if you want to use the same business service host class to communicate with various external sources, but 

you want to use slightly different runtime settings in each case, you can do so by assigning a different name to each configuration 

of the host class. A change to the underlying class code changes the behavior of all of the items of that class. 

Figure 5–5: Different Configuration Names, Same Host Class 


Configuration 

The Copy command is useful when you need to create multiple items with different configuration names, but the same host 

class. Select a configuration item in the diagram, then click Copy. A dialog prompts you to enter the new item name. Once 

you click OK to accept the copy, it has no relationship to the original item; you can configure, enable, and disable each item 

independently. There is more information about the Copy command in the Configure Business Host Settings section. 

Note: 

The Copy command works only within the same production. You cannot copy a configuration item from one 

production to another. 

5.1.2.2 Same Configuration Name, Different Host Classes 

You can assign the same configuration name to more than one item in the production; however, only one of the configuration 

items with the same name can be enabled at any one time. Usually you set this up because you want to use a different host 

class to fulfill the same role within your production at different stages of developing or maintaining it. 

For example, when testing or troubleshooting the production you might want to send messages by typing them at the console 

command line, or by reading data from files, but when running the production you might intend for these messages to arrive 

from an external application via a TCP connection. Each means of obtaining input for the production requires a different 

business service host class. 

Figure 5–6: Same Configuration Name, Different Host Classes 

If there are multiple items with the same configuration name, with one item enabled, only the enabled item is visible in the 

configuration diagram. Disabled configuration items with the same name as an enabled item are not visible. However, if 

you click on the enabled edition of the item, an Item list box appears in the configuration page at the boundary between the 

diagram and the data display, as shown (circled) in the following figure. 

Figure 5–7: Item List Box for Same-Named Configuration Items 

All of the host classes with the same configuration name as the currently selected item appear in the Item list box. The 

currently enabled host class appears in the list with an asterisk (*) beside its name, as shown for 

EnsLib.HL7.Service.TCPService in the figure. 

You can select the various host classes in the Item list box by clicking them. This displays the General Settings and Specific 

Settings for each edition of the item, but it does not control which of the host classes is enabled for the item. 

To enable a different host class out of the available choices in the Item list box, you must: 

1. Click the enabled item in the diagram. Its General Settings and Specific Settings display in the bottom half of the screen. 


Configuration Diagram 

2. Use the Item list box to choose another host class for the item. The General Settings and Specific Settings for this host 

class display in the bottom half of the screen. 

3. Select the Enabled check box and click Apply. This action enables the item whose settings you are now viewing and 

disables the previously enabled edition of the same-named item. 

5.1.2.3 Changing the Host Class of a Configured Item 

It is possible to change the host class for a configuration item permanently; that is, without switching between different 

host classes using the Item list box as described above. To do this use the Change Class command in the configuration page. 

5.1.2.4 Adapter Names in the Configuration Diagram 

For business services and business operations, the configuration diagram displays the name of the incoming or outgoing 

adapter class associated with the item. The choice of specific adapter is made in the host class for the service or operation 

and cannot be changed using the configuration page. 

5.1.3 Configuration Icons 

As described in the Working with Configuration Items section of the “What to Manage” chapter, there are regular configuration 

items and special cases of each type. Shapes on the configuration page indicate special cases with an icon, as shown 

in the following table. 

Table 5–1: Icons on Configuration Diagram Shapes 

Column 

Icon 

Meaning 

Reference 

(None) 

Business service 

Developing Ensemble Productions 

Business Service 

Business metric 

Using Dashboards with Ensemble 

(None) 

Business process created 

with custom code 


BPL business process 


Business Process 

BPL business process 

(reusable component) 


Routing process 

Ensemble HL7 Version 2 Development Guide 

(None) 

Business operation 


Business Operation 

Workflow operation 

Using Workflow with Ensemble 


Configuration 

5.1.4 Status Indicators 

Each configuration item has a circular status indicator in its upper left corner. This indicator changes color with the status 

of the configuration item it represents. Business services and business operations have the regular circle indicator, plus an 

arrowhead whose color represents the status of the associated inbound or outbound adapter. 

The status values for any indicator are as follows: 

• Green — OK. 

• Yellow — The item has experienced no activity within its configured Inactivity Timeout. 

• Red — The item has reported an error. 

• Orange — The item could not complete its current activity and is retrying it, as configured. 

• Blue — The item is in the process of starting up. 

• Gray — The configuration item is disabled. 

• (Any color, dimmed) — The production is not currently running. 

5.1.5 Pool Size 

Below the status indicator, each business host displays its private Pool Size — the number of jobs allocated for its own, 

private use in the current configuration. A business process shows no pool size if its private pool size is 0 (zero), meaning 

that it gets its jobs from the public actor pool shared by all business processes in the production. 

For an overview of pool sizes, see Working with Jobs in the “What to Manage” chapter. For a full discussion of appropriate 

pool sizes for different types of production, see the Pool Size section in the “Production Concepts” chapter in Developing 

Ensemble Productions. 

5.1.6 Context Menu 

You can right-click anywhere on the diagram in the top display to reveal the configuration context menu. The following 

menu options are available: 

• Show Category — Choose a category name. The diagram changes to reveal only those configuration items that match 

the category you have just selected. Select All (the first option) to reveal all configuration items, regardless of category. 

• Sort — Choose the order in which the configuration items display (the default is by name): 

– By Position — Items display in the order they appear in the production class; by default, this is the order you add 

them to the configuration. 

For details, see the How a Production Stores the Values of its Settings section in the “Creating a New Production” 

chapter of Developing Ensemble Productions. 

– By Name — Items display in alphabetical order. 

– By Status — Items display by status in the following order: error, missing, OK, disabled. 

• Add — Choose to add a Business Service, Business Process, or Business Operation to the production. 

• Production Settings — Edit production settings in the bottom display. 

• Zoom — Choose a zoom factor for the BPL diagram. Choose a large factor to view details, a small factor to gain an 

overview. 


Configuration Settings 

• Show Components — This option toggles between a production diagram that shows all types of BPL business processes, 

and a view that hides any BPL business processes that are reusable components. 

• Toggle Enabled — Enable a disabled configuration item, or disable an enabled configuration item. 

• Run-time — Choose one of two [Ensemble] > [Host Monitor] pages for this configuration item: Display a list of Instances, 

or display a graphical History of the item’s activity over time. 

• Show Message Queue — Display the [Ensemble] > [Queues] page for this configuration item only. 

• Show Event Log — Display the [Ensemble] > [Event Log] entries relating to this configuration item only. 

• Find, Find Again — Search for a text string in the underlying XML document. When found, the corresponding string 

is highlighted in the configuration diagram. 

• View Source, Original View — Switch between the diagram and the SVG code that displays the diagram. 

• About SVG Viewer — Display version and copyright information about the SVG Viewer used to display the production 

diagram. 

5.2 Configuration Settings 

The [Ensemble] > [Productions] > [Configuration] page allows you to configure the operational settings for an Ensemble 

production and its items. The text in the bar under the configuration diagram indicates the item for which you are configuring 

settings: the production, a business service, a business process, or a business operation. Your selection in the diagram 

controls which settings appear in the lower portion of the page for configuration: 

• To configure production settings, select the production by clicking in the neutral background of the configuration diagram. 

• To configure business host settings, select a particular business service, process, or operation by clicking on its shape 

in the configuration diagram. 

The following table describes the significance of the color of the setting name displayed on the lower portion of the configuration 

page. 

Color 

Black 

Green 

Blue 

Source 

Setting value comes from the production definition — the value you enter and apply in the 

configuration page. 

Setting value comes from the class definition; it is the default value for the property as defined 

in the class implementing the configuration item through the use of the InitialExpression attribute. 

Setting value comes from the default settings you enter in the Default Settings page for the 

namespace in the Ensemble instance that contains the production. See the Default Settings 

section in the “Maintenance” chapter of this guide for details. 

5.2.1 Configure Production Settings 

If Production Settings are not visible in the lower portion of the configuration display, click on the neutral background of 

the configuration diagram to display them. 

Under the name of the production is a row of commands, from left to right: 

• Apply — Activate the changes highlighted in yellow on the configuration page. 


Configuration 

When you click Apply to save changes made in the configuration form, Ensemble outputs your settings to the production 

class in the form of an XML document embedded in the XData ProductionDefinition section of the class. 

• Cancel — Undo the changes highlighted in yellow on the configuration page. 

• Help — View context-sensitive information about this page. 

• Start Production — Start the production whose configuration you are viewing. 

• Stop Production — Stop the production that is running in the active namespace. 

The next three commands allow you to add new configuration items to the production. Clicking one of these commands 

does not generate any new host classes. Any item that you add at this step must already have a corresponding host class 

that has been written and compiled in Ensemble Studio. These commands simply tell the production which items you want 

it to contain: 

• Add Service — Add a business service to the production. 

• Add Process — Add a business process to the production. 

• Add Operation — Add a business operation to the production. 

Beneath the row of commands are the settings you can configure for a production; they are grouped into the following three 

categories: 

• Production Settings 

• Additional Production Settings 

• Defaults for Additional Production Settings 

5.2.1.1 Production Settings 

The configuration page allows you to configure the following Production Settings common to all productions: 

Name 

Description 

The production name. This field has a gray background, which means you can view it, but you cannot edit it. 

Comments that describe the production. 

Actor Pool Size 

Number of system jobs available in a public pool of jobs for use by business processes that have no private pool 

of jobs. Allow enough for requests to keep moving through the message queues, but no more. 

For a full discussion of appropriate pool sizes for different types of production, see the Pool Size section in the 

“Production Concepts” chapter of Developing Ensemble Productions. 

Testing Enabled 

Select this check box to enable use of the Ensemble Testing Service pages to test this production. Clear this check 

box to disable the testing service. 

Log Unassigned Trace Events 

Trace messages are informational text messages that Ensemble can deliver to the Terminal window and, optionally, 

to the Ensemble event log. Trace messages are unrelated to Visual Trace, which provides a graphical view of 

Ensemble message objects as they travel through a production. 



By default, the Log Unassigned Trace Events check box is clear. When selected, it enables logging of all trace 

messages issued by production elements that are not configuration items. Logging means that Ensemble automatically 

stores copies of these trace messages in the event log. 

Each business service, business process, and business operation in the production has its own Log Trace Events 

setting, which controls logging of trace messages from that configuration item. There is no overlap or interaction 

between these settings. Log Unassigned Trace Events does not override or provide a default value for Log Trace 

Events. 

5.2.1.2 Additional Production Settings 

The right lower portion of the configuration page allows you to configure Additional Production Settings: 

Shutdown Timeout 

How long to wait while attempting to shut down a production before forcing the shutdown. The class default is 

120 seconds. 

Update Timeout 

How long to wait while attempting to update the configuration for a production that is busy, before abandoning 

the update. The class default is 10 seconds. 

(custom settings) 

Any custom settings added to the underlying production class. For details, see the Adding Configuration Settings 

section of the “Creating a New Production” chapter of Developing Ensemble Productions. 

Next to the Additional Production Settings title is a red arrow icon. Click this arrow to view and update the defaults for 

additional production settings. This feature makes it easier to move productions from one Ensemble instance to another. 

5.2.1.3 Defaults for Additional Production Settings 

When you click the default setting icon on the configuration page for the production, the Select Defaults for Additional 

Production Settings dialog box displays a table where you can view the setting values and, if appropriate, select to use the 

default values for the production settings. The table contains the following information. 

Column 

Default command 

Property 

Target 

Type 

Value 

Default 

Default Source 

Description 

Command displays only if the source of the current value is not a default. 

Name of the property setting. 

N/A at the production level. 

Data type of the property. See %Library.DataType for a list of types. 

Current value for the setting. 

Default value for this setting. 

Source of the default value: 

• class definition 

• default setting 


Configuration 

Column 

Value Source 

Description 

Source of the current value: 



• production definition 

If a setting row does not have a Default command in the first column, either the value is already set to the default or a default 

value does not exist. 

1. To update a production setting to a default value, click Default in the left column to initiate the following actions: 

• The Default value as defined in the production class or by a default setting is placed in Value. 

• Default command becomes disabled. 

• The property field background becomes yellow to indicate that you have modified the field. 

• The property label becomes either green or blue depending on the Default Source. 

2. If you make a mistake and want to return to the original values, click Reset; the table settings refresh to the setting 

values before you made any changes. 

3. Once you verify your changes, click OK to update the settings to the default values and transfer back to the Production 

Configuration page with your new settings. The color of the setting labels now reflect any changes you made using the 

defaults and any value that has been updated has a yellow background. 

The yellow background color for a field means that this field has been modified, whether you type in a new value, or 

click Default in the Select Defaults for Additional Production Settings dialog box. 

4. Click Apply to save all your setting updates. 

Important: 

Updates to default values only take effect when you click Apply on the Production Configuration page. 

5.2.2 Configure Business Host Settings 

When you select a business host in the diagram on the [Ensemble] > [Productions] > [Configuration] page, the runtime settings 

for this business host display in the lower portion of the page. 

Note: 

If you cannot find a particular business host in the configuration diagram, check that you have used the scroll bars 

to see the entire screen. Then refresh the display. If you still do not see the item, add it to the production using 

the appropriate Add command from the production configuration display and then configure it. 

At the boundary between the diagram and settings is a row of commands. From left to right: 

• Apply — Activate the changes highlighted in yellow on the configuration page. Even if the production is running, any 

changes that you Apply take effect immediately. 

• Cancel — Undo the changes highlighted in yellow on the configuration page. 

• Copy — Create a copy of the currently selected configuration item. When you click Copy, a dialog box prompts you 

to enter a configuration name. Enter a unique name and click OK. When first created, the copy has the same host class 

and settings as the original; only the name is different. Generally your next step is to configure the copy to make it 

unique. For example: 



– If you have an incoming TCP business service that receives messages from a client application, and you want to 

receive messages from a similar application on a different application server, you can copy the first TCP service 

and configure the copy with the other server address. 

– If you have a business process for one message routing interface, and you want a similar one but with slight 

alterations for another interface, you can copy the first routing process and configure the copy to route messages 

between different sets of business services and business operations. 

– If you have an outgoing email business operation that alerts a user, but you want to alert another user at different 

times of day, you can copy the first outgoing email operation and configure the copy with the other email address. 

• Remove — Remove this item from the production configuration. This action does not delete the business host class 

from the source code. It only removes the item — identified by Name — from the list of items included in the production. 

• Change Class — Change the Class field under General Settings for this item. If you change the host class, the General 

Settings retain their values, but you must reconfigure the Specific Settings, as these may be entirely different for the 

new host class. 

When you click Change Class, a prompt displays asking you to confirm your action. To accept the warning, click OK. 

The data display title becomes Change Business Class with the name of the business service, for example Change 

Business Class for Demo.Loan.FindRateFileService. You can view or edit the following settings. These are similar to 

your choices when you first added the business service to the production: 

– Class — Select a business service class from the drop-down list. 

– Name — By default, this field takes the value of the business service class name from the class definition in the 

source code. However, you can give a business service a name for any management purpose you wish. 

– Category — Optionally, you may enter a text label in the Category field. Category names are case-sensitive, and 

space characters are allowed within them. To place an item in multiple categories, list them in the Category field, 

separated by commas. Do not allow spaces around these commas. For details, see the “Assigning Configuration 

Items to Categories” section in the chapter “What to Manage.” 

– Comment — Enter a text description of the business service. 

Click Apply to activate your changes, Cancel to undo your changes and return to the settings display. 

• Instances — View detailed information about instances of the business host in the running production. This command 

displays only if Pool Size is > 0, but appears dimmed if the production is not running. 

• History — View information about the level of activity for this business service over time. 

• View Definition — Display the [Ensemble] > [Business Processes] > [BPL Viewer] diagram for the business process in 

the top half of the page. Details appear in the lower portion. This view of the BPL diagram is read-only. To edit the 

diagram you must open the business process host class in Ensemble Studio. Appears only if you select a BPL business 

process. 

• View Rules — Navigate to the Ensemble Message Routing Rule Editor. Appears only if you select a message routing 

business process. 

• Queue — Display the contents of the [Ensemble] > [Queues] > [Contents] page for this configuration item only in the 

lower portion of the page. Appears only if you select a business process or a business operation. 

• Test — Navigate to the Ensemble, Testing Service pages. The Test command works only when the production that 

contains this business host is running with testing enabled. Appears only if you select a business process or a business 

operation. 

• Help — View context-sensitive information about this page. 


Configuration 

Beneath the row of commands are the settings you can configure for a business service, process, or operation. They are 

grouped into the following three categories: 

• General Settings 

• Specific Settings 

• Defaults for Specific Settings 

5.2.2.1 General Settings 

The configuration page permits you to view or edit the following General Settings for a business host: 

Name 

Comment 

Schedule 

Category 

Class 

By default, the Name field takes the value of the business host class name from the class definition in the source 

code. However, you can give a business host a name for any purpose. 

For example, if you have a business service class that communicates with a specific type of server, and you use 

to communicate with the same type of server in different enterprise locations, you must configure the business 

service with different settings to communicate with each enterprise location, even though the type of server is the 

same. Each different configuration of the business service must have a different Name in the diagram, while the 

Class actually remains the same. All of the configuration settings listed in this topic apply to the business host 

identified by Name. 

An optional text description. 

An optional command string that schedules the business host to be stopped and started at specific times and on 

specific days of the week, month, or year. The string is a comma-separated list of event specifications, each of 

which has the following format: 

action:YYYY-MM-DDThh:mm:ss 

Where action is either START or STOP to indicate the desired event. For full details of the Schedule string, see 

the “Scheduling Configuration Items” section in the “What to Manage” chapter. 

An optional text label. When you are viewing the production configuration diagram, you can right-click on the 

background of the diagram, then choose Show Category and a category name from the context menu. The diagram 

changes to reveal only those configuration items that match the Category name you have just selected. Category 

names are case-sensitive, and space characters are allowed. To place an item in multiple categories, list them in 

the Category field, separated by commas. Do not put spaces around these commas. For details, see the “Assigning 

Configuration Items to Categories” section in the “What to Manage” chapter. 

The business host class name. This field has a gray background, which means it is read-only. If you want to change 

this field, click Change Class and choose a different host class name. 

For example, you might change the class of a business service that you have already configured if an enterprise 

that you communicate with upgrades to a different type of server. This could happen even if the purpose of the 

business service remains unchanged, such as Our Data Feed from Client X. A change in server on the 



Description 

Enabled 

Foreground 

external side might mean that the business service now needs a different class of adapter to communicate with the 

other enterprise. This would indicate a change to the Class field. The Name field allows continuity across this 

change. 

If you change the host class, the General Settings retain their values, but you must configure the Specific Settings, 

as these may be entirely different for the new host class. 

Comments that describe the business host class. This read-only field displays the first line of the class annotation 

in the code. If there is no annotation in the code, the Description field contains the text N/A. 

By default, the Enabled check box is selected for every business host. When you select Enabled, the business host 

— identified by Name — is enabled. When a business host is enabled, it is registered with the production, and 

instances of the business host accepts and processes messages whenever the production runs. You can clear the 

Enabled check box, if needed. 

For example, if there is a communications breakdown on the external side, an email server goes down, or something 

similar happens, you can disable the associated business service until throughput is restored. When the Enabled 

check box is clear, the business service is still present in the configuration, and its queue continues to accept 

messages, but none of these messages are processed until the business service is enabled again. 

By default, this check box is clear. Select it for debugging or diagnostic purposes only. Jobs in operational systems 

almost never run in the foreground. When the Foreground check box is selected, any system jobs used by the 

business service run in a Caché Terminal window at the front of the console display. This allows debugging or 

trace messages to be displayed in the Terminal window. See the section “Testing and Debugging Productions” 

in the “Creating a New Production” chapter of Developing Ensemble Productions. 

Log Trace Events 

Trace messages are informational text messages that Ensemble can deliver to the Terminal window and, optionally, 

to the Ensemble event log. Trace messages are unrelated to Visual Trace, which provides a graphical view of 

Ensemble message objects as they travel through a production. 

By default, the Log Trace Events check box is clear. When selected, it enables logging of all trace messages issued 

by this business host. Logging means that Ensemble will write the trace messages to the console Terminal window 

(as usual) but it will also automatically store copies of these messages in the event log. 

Inactivity Timeout 

Pool Size 

A business host has an Inactive status after it has not received any messages within the number of seconds specified 

by the Inactivity Timeout field. The Ensemble Monitor Service periodically reviews the status of business services 

and business operations within the production, and marks the item as Inactive if it has not done anything within 

the Inactivity Timeout period. The business host status (OK, Error, Inactive) can be seen on the [Ensemble] > [Host 

Monitor] page. The default value is 0 (zero). If a business host has an Inactivity Timeout setting of 0, it will never 

be marked Inactive, no matter how long it stands idle. 

Specifies how many system jobs to allocate to run this business host; the default is 1. Other values are appropriate 

in specialized circumstances as described in the General Settings notes for the particular business host type. 

For a full discussion of appropriate pool sizes for different types of production, see the Pool Size section in the 

“Production Concepts” chapter of Developing Ensemble Productions. 


Configuration 

From the Production Configuration page, click Apply to save all your setting updates. 

5.2.2.2 Specific Settings 

Each type of business host has specific settings depending whether it is a service, process, or operation. When you hover 

the cursor over a field name, if there is a description of this field in the class code, its description displays. Validation for 

the data you enter is performed using the data types in the class code. 

Under Specific Settings, the additional fields you can configure depend on the details of the business host class. Most 

business hosts have the following settings: 

Alert On Error 

Archive IO 

When Alert On Error is set to True, as soon as the business host encounters any type of error condition it automatically 

triggers an alert. An alert writes a message to the Ensemble event log and can also send notification to a 

user via email or pager. For details, see the Alerts section in the “Creating a New Production” chapter of Developing 

Ensemble Productions. 

If True, the adapter associated with this business service or operation logs in the Ensemble I/O archive each input 

and output communication it shares with the external system. See the Working with the I/O Archive section in 

the “What to Manage” chapter. 

The following sections provide details for the specific business host type: 

• Business Service Settings 

• Business Process Settings 

• Business Operation Settings 

5.2.2.3 Defaults for Specific Settings 

When you click the default setting icon on the configuration page for a specific business service, process, or operation, 

the Select Defaults for Specific Settings dialog box displays a table where you can view the setting values and, if appropriate, 

select to use the default values for the settings. The table contains the following information. 

Column 

Default command 

Property 

Target 

Type 

Value 

Default 

Default Source 

Description 

Command displays only if the source of the current value is not a default. 

Name of the property setting. 

Indicates if the property is for a host or adapter. 

Data type of the property. 

Current value for the setting. 

Default value for this setting. 

Source of the default value: 





Column 

Value Source 

Description 

Source of the current value: 



• production definition 

If a setting row does not have a Default command in the first column, either the value is already set to the default or a default 

value does not exist. 

1. To update a business host setting to a default value, click Default in the left column to initiate the following actions: 

• The Default value as defined in the production class or by a default setting is placed in Value. 

• Default command becomes disabled. 

• The property field background becomes yellow to indicate that you have modified the field. 

• The property label becomes either green or blue depending on the Default Source. 

2. If you make a mistake and want to return to the original values, click Reset; the table settings refresh to the setting 

values before you made any changes. 

3. Once you verify your changes, click OK to update the settings to the default values and transfer back to the Production 

Configuration page with your new settings. The color of the setting labels now reflect any changes you made using the 

defaults and any value that has been updated has a yellow background. 

The yellow background color for a field means that this field has been modified, whether you type in a new value, or 

click Default in the Select Defaults for Specific Settings dialog box. 

4. Click Apply to save all your setting updates. 

Important: 

Updates to default values only take effect when you click Apply on the Production Configuration page. 

5.2.3 Business Service Settings 

When you select a business service in the configuration diagram on the [Ensemble] > [Productions] > [Configuration] page, 

the runtime settings for this business service display in the lower portion of the page. For the most part, these settings 

describe how the service communicates with the specific external entity from which it receives requests. 

General Settings 

The configuration page permits you to view or edit the General Settings described in a previous section with the following 

additional notes that apply specifically to business services: 

Pool Size 

You must use a value of 0 if the business service is being invoked via the Ens.Director method CreateBusinessService; 

this is called an adapterless business service. 

You may use a value greater than 1 with File or FTP inbound adapters if you want multiple jobs competing to pull 

files from the same input directory, or if you have a TCP Service configured with an exclamation point (!) to 

make it initiate the connection. 

Specific Settings 

The configuration page permits you to view or edit Specific Settings for the inbound adapter associated with a business 

service: 


Configuration 

Adapter Class 

The class name for the inbound adapter associated with this business service, or if there is no associated 

adapter class. This field has a gray background because it is read-only. Its value is determined by the business 

service class definition in the source code. 

Adapter SETTINGS 

Below the Adapter Class, various other fields display. The exact fields vary depending on the adapter class. 

Whatever is listed in the SETTINGS parameter for the business service class or its associated adapter class appears 

in the Specific Settings. When you hover the cursor over a field name, if there is a description of this field in the 

class code, its description displays. Validation for the data you enter is performed using the data types in the class 

code. 

Alert Grace Period 

Call Interval 

Credentials 

Business services can be configured with an Alert Grace Period during which errors relating to external connections 

do not trigger alerts, even if Alert On Error is True. The Alert Grace Period is allowed to elapse, giving the business 

service and the external source time to reestablish their connection. If the error condition still exists after the Alert 

Grace Period, the business service triggers an alert; otherwise no alert is triggered. 

Setting Alert Grace Period to 0 disables this feature for the business service. 

Many inbound adapters have a configurable setting called Call Interval. This integer determines how frequently 

the business service invokes the associated inbound adapter to obtain new input. Call Interval has a minimum of 

0.1 seconds. The default is 5 seconds. 

Some inbound adapters make remote connections that require a username and password. Ensemble stores these 

login credentials in a centralized table that can be viewed and edited only by users with access to the [Ensemble] 

> [Maintenance] > [Credentials] page. Each entry in the Credentials table has an ID by which you can refer to it 

when configuring adapters for the production. 

If an inbound adapter requires credentials, the Specific Settings include a Credentials field. If this field is present, 

it must contain an ID from the table on the [Ensemble] > [Maintenance] > [Credentials] page. If there is no current 

Credentials entry for the remote system that this business service needs to connect to, you must create it. After 

creating the new entry in the [Ensemble] > [Maintenance] > [Credentials] page, go back to the configuration page 

and enter the new ID in the Credentials field. 

5.2.4 Business Process Settings 

When you select a business process in the configuration diagram on the [Ensemble] > [Productions] > [Configuration] page, 

the runtime settings for this business process display in the lower portion of the page. For the most part, these settings 

describe how the process communicates with other items within Ensemble. 

General Settings 

The configuration page permits you to view or edit the General Settings described in the previous section with the following 

additional notes that apply specifically to business processes: 

• Enabled — When you clear this check box, the Ens.Actor queue continues to accept messages addressed to it, but none 

of these messages are processed until you enable the business process again. 

• Pool Size — This number could be larger to allow higher throughput in some circumstances. If this number is 0, the 

business process has no private pool of jobs, and uses jobs from the public actor pool for the production. 



Larger numbers are not necessarily helpful; while the potential pool sizes actually range from 0–100, most pool sizes 

are best set to either 0 or 1, and there can be serious consequences when sizes are set to a number greater than 1. 

Important: 

When you disable a business process, it must have a Pool Size = 1 or greater if you want all instances of 

only this business process to stop. If the business process has a Pool Size = 0, the action disables all business 

processes that share the actor pool. See the Pool Size section in the “Production Concepts” chapter of 

Developing Ensemble Productions for details. 


Under Specific Settings, there may be additional fields you can configure. This depends on the details of the business process 

class. Most business processes have the following settings: 

Reply Code Actions 

Retry Interval 

Comma-separated list of code-action pairs, specifying which action the business process takes on receipt of various 

reply status conditions. 

See Reply Code Actions Setting for details. 

Number of seconds to wait between attempts to connect to the output system. 

Alert Retry Grace Period 

You can configure business processes with an Alert Retry Grace Period during which errors do not trigger alerts, 

even if Alert On Error is True. This grace period accommodates a business process that attempts a connection with 

a configured Retry Interval and Failure Timeout. During its retry sequence, the business process may encounter 

failures that become unimportant after one of its retry attempts succeeds. Thus, if a business process first 

encounters an error, but later achieves success within the time allotted by the Alert Retry Grace Period, no alert is 

triggered even though an error occurred. 

Failure Timeout 

Total number of seconds to keep trying to connect with the output system. After this number of seconds has 

elapsed, the business process returns an error code. 

5.2.5 Business Operation Settings 

When you select a business operation in the configuration diagram on the [Ensemble] > [Productions] > [Configuration] 

page, the runtime settings for this business operation display in the lower portion of the page. For the most part, these settings 

describe how the operation communicates with the specific external entities to which it sends requests. 


The configuration page permits you to view or edit the following Specific Settings for the outbound adapter associated with 

a business operation: 

Adapter Class 

The class name for the outbound adapter associated with this business operation, or if there is no associated 

adapter class. This field has a gray background because it is read-only. Its value is determined by the business 

operation class definition. 


Configuration 

Adapter SETTINGS 

Below the Adapter Class, various other fields display. The exact fields vary depending on the adapter class. 

Whatever is listed in the SETTINGS parameter for the business operation class or its associated adapter class 

appears in the Specific Settings. When you hover the cursor over a field name, if there is a description of this field 

in the class code, its description displays. Validation for the data you enter is performed using the data types in 

the class code. 

Reply Code Actions 

Retry Interval 

Comma-separated list of code-action pairs, specifying which action the business operation takes on receipt of 

various reply status conditions. 

See Reply Code Actions Setting for details. 

Number of seconds to wait between attempts to connect with a destination outside Ensemble. 

Alert Retry Grace Period 

Business operations can be configured with an Alert Retry Grace Period during which errors relating to external 

connections do not trigger alerts, even if Alert On Error is True. This grace period accommodates a business 

operation that attempts an external connection with a configured Retry Interval and Failure Timeout. During its 

retry sequence, the business operation may encounter connection failures that become unimportant after one of 

its retry attempts succeeds. Thus, if a business operation first encounters an error, but later achieves success within 

the time allotted by the Alert Retry Grace Period, no alert is triggered even though an error occurred. 

Setting Alert Retry Grace Period to 0 disables this feature for the business operation. 

Failure Timeout 

Credentials 

Total number of seconds to keep trying to connect with a destination outside Ensemble. After this number of 

seconds has elapsed, the business operation discards the message data and returns an error code. To ensure that 

no message is ever skipped, enter a Failure Timeout value of –1, which means “never time out.” Use a setting of 

–1 when complete data delivery is critical, for example in health care applications. 

Some outbound adapters make remote connections that require a username and password. Ensemble stores these 

login credentials in a centralized table that can be viewed and edited only by users with access to the [Ensemble] 

> [Maintenance] > [Credentials] page. Each entry in the Credentials table has an ID by which you can refer to it 

when configuring adapters for the production. 

If an outbound adapter requires credentials, the Specific Settings include a Credentials field. If this field is present, 

it must contain an ID from the table on the [Ensemble] > [Maintenance] > [Credentials] page. If there is no current 

Credentials entry for the remote system that this business operation needs to connect to, you must create it. After 

creating the new entry in the [Ensemble] > [Maintenance] > [Credentials] page, go back to the configuration page 

and enter the new ID in the Credentials field. 

5.2.6 Reply Code Actions Setting 

The Reply Code Actions setting allows you to supply a comma-separated list of code-action pairs, specifying which action 

the business host takes on receipt of various reply status conditions. The format of the list is: 

code=actions,(code,code)=actions, ... code=action 

The following table lists the types of reply status condition identified by code. 



Table 5–2: Code Values for Reply Code Actions 

Code 

E 

E#statuscode 

E*text 

X 

Meaning 

Error status returned from message handler. 

Error status returned from message handler has status code equal to statuscode. 

Error status returned from message handler contains text string text. 

There is no reply message object at all. 

The following values for action may be used alone or combined to form strings. 

Table 5–3: Action Values for Reply Code Actions 

Action 

C 

W 

R 

S 

D 

F 

Meaning 

Treat the document as Completed OK. 

Log a warning but treat the document as Completed OK. 

Retry the message according to the configured Retry Interval and Failure Timeout settings; finally Fail, 

unless a different action is also specified. 

Suspend the message, log an error, and move on to try the next message (the default). 

Disable the business process or operation, log an error, and restore the outbound message to the 

front of the business host queue. 

When you choose the disable action for a business process, you must configure the business with 

a Pool Size = 1 or greater if you want all instances of only this business process to stop. If the business 

process has a Pool Size = 0, the disable action disables all business processes that share the actor 

pool. See the Pool Size section in the “Production Concepts” chapter of Developing Ensemble 

Productions for details. 

Fail with an error and move on to try the next message. 

For example: 

E#6301=R,E#ErrGeneral=R,E=F 

The default value for the Reply Code Actions string is: 

E=F 

Which means when there is an error, fail and move on to try the next message. 

All codes where the actions consists of only W (log a Warning) are evaluated and warnings generated if they trigger. Other 

codes are evaluated in left-to-right order, executing the first one that triggers that has a non-warning actions value. 


6 


The [Ensemble] > [System Monitor] page displays real-time status information about the currently running production in a 

condensed, one page format. 

You can display the System Monitor page by choosing System Monitor from the Ensemble Management Portal main menu. 

You can return to the Ensemble home page by clicking [Ensemble] in the title bar navigation path. 

The main display area of the [Ensemble] > [System Monitor] page is laid out as a grid containing the following tables: 

• Input Connections (upper left) lists all incoming connections from external systems. 

• Output Connections (upper right) lists all outgoing connections to external systems. 

• Queues (lower left) lists the status of Ensemble internal message queues and how many messages are currently waiting 

in each queue. 

• Event Log (lower right) summarizes recent entries in the event log. 

Each entry provides an icon and color to indicate the item’s status. For connections and queues: 

• 

• 

Green dot — Active and OK. 

Yellow dash — Currently inactive, but otherwise OK. 

For the event log: 

• 

• 

• 

Red ! — Error. 

Orange W — Warning. 

Yellow A — Alert. 

For any entry displayed in a table on this grid, you can click its name to display useful details and links to more information. 

These links appear in the vertical display area at left, under the Auto update check box. Clear the Auto update check box 

to disable frequent real-time updates of the information on the System Monitor page. 

You can extend the System Monitor page to show information from user-defined business metric classes. These are the 

same business metric classes that support Ensemble dashboards. Perform the following steps to add entries to the System 

Monitor page: 

1. Define a business metric class and add it to your production. For background information, see the “Business Metrics” 

chapter in Using Dashboards with Ensemble. 



2. Set the Êns.Monitor.Settings global in your namespace. This global indicates which business metrics are 

supplying additional data to the System Monitor page. For each business metric, supply three ObjectScript statements, 

similar to the following: 

Set Êns.Monitor.Settings("MetricClasses",1,"Metric") = "MetricConfigName" 

Set Êns.Monitor.Settings("MetricClasses",1,"Title") = "Title for Display" 

Set Êns.Monitor.Settings("MetricClasses",1,"Instance") = "MetricInstanceName" 

Where: 

• These statements are appropriate for the first business metric you add. For additional business metrics, in place 

of the number 1, use an integer n where n is the same for all three statements. Increase n by 1 for each additional 

business metric class that you want to display on the System Monitor page. 

• In place of "MetricConfigName" provide the configured name of the business metric component. (If you do 

not enter a name when you add the metric to the production, the component name defaults to the class name.) 

• If you do not supply the statement that sets the "Title" value, the value of "Metric" is used as a default 

"Title". 

• In place of "MetricInstanceName" provide the metric instance name. If the metric does not have instances, 

you may omit the statement that sets the "Instance" value. If it does have instances and you do not supply a 

value, the first instance is used. 

For each business metric that you add, the System Monitor page indicates when it last updated the metric information, if 

there is any data for the given metric or instance, and whether or not the given metric is currently running. As with any 

entry on the System Monitor page, click the metric name to display useful details and links to more information. 


7 

Event Log 

The [Ensemble] > [Event Log] page displays the event log entries for the currently running production. You can display this 

page from the Ensemble Management Portal as follows: 

• From the Ensemble Menu — Click Event Log 

• From the [Ensemble] > [Maintenance] > [Purge] page — Click Show Event Log 

There is a Purge command to purge outdated entries from the event log. at the top of the Event Log page. 

The Ensemble Event Log page has two display areas, one above the other. The top display lists the event log entries recorded 

since the production was last started. The bottom display permits you to enter search criteria to filter the list of events. If 

the top display is empty when you first open it, click the Search command in the bottom display. 

7.1 Event Log Entries 

The Event Log top display contains a table. Each row in the table provides the following columns of information about an 

event: 

• # — An incremental count of the number of entries in the table. 

• ID — The unique identifier for the message that comprises this event log entry. 

• Time Logged — The date and time when this entry was logged. 

• Type — Indicates the type of entry: Alert, Assert, Error, Info, Status, Trace, or Warning. 

• Job — The system job that hosted the event. 

• Session — The unique identifier for the session that is (or was) associated with this message. A session marks the 

beginning and end of all the activities prompted by a primary request message from outside Ensemble. The primary 

request message has an ID value that is identical to the Session. Several additional messages may be instantiated within 

Ensemble during the session, in order to fulfill the primary request. All of these messages share the same Session, but 

each has a different ID value. 

The Session number is a link; click on it to view a visual trace of the session. 

• Source — The configuration item (service, process, or operation) that sent the message. 

• Method — The host class method that was in progress when the event was logged. 

• Text — The text string associated with the event log entry. 


Event Log 

7.2 Event Log Filter 

If you do not see the message you want to view in the Event Log page, you can filter the list of entries. To do so, enter 

values in the fields in the lower portion of the page to search for a particular class of event log entries, as follows: 

• SortOrder — Select a value from the list: Oldest First or Newest First. 

• TimeFormat — Select a value from the list: Time Only or Complete (time with date). 

• Source — Enter a value in this field to list all the events logged by a specific host class. 

• Method — Enter a value in this field to list all the events logged by a specific method. 

• Text — Enter a value in this field to list all the events whose text contains this string. 

• Job — Enter a value in this field to find events hosted by a specific system job. 

• Color By — Choose a criterion from the list: TimeLogged, Type, Job, Session, Source, Method, Text, or none (blank). 

The background color of rows in the Event Log table changes according to your choice. 

If the Color By selection is blank, the default background color indicates the event Type as follows: 

Color 

Yellow, with bold red text 

Silver, with red text 

Pink, with bold red text 

Green, with bold yellow text 

Blue, with bold yellow text 

Light blue 

Orange 

White 

Indication 

Alert 

Assert 

Error 

Production start 

Production stop 

Trace 

Warning 

(all others) 

• MaxRows — The maximum number of event log entries to display as a result of the search. If more matches are found, 

a message displays at the bottom of the table: There is more data. To display the additional data, change the 

MaxRows value and click Search again. 

• StartId — Enter the lower limit of a range of ID values. 

• EndId — Enter the upper limit of a range of ID values. 

• StartTime — Enter the lower limit of a range of TimeLogged values. 

• End Time — Enter the upper limit of a range of TimeLogged values. 

• Session Id — Find all the event log entries associated with a particular session. 

• At right, a column of check boxes allows you to limit the display to specific types of event: Assert, Error, Warning, 

Info, Trace, or Alert. 

Note: Most of these fields support the use of the SQL Like wildcard character (%). 

After you have edited these fields, you can click one of the commands at the bottom of the screen: 

• Click Search to sort the list of event log entries in the top display using the criteria shown in the bottom display. 


Event Log Purge 

• Click Reset to redisplay the entries in their default order and return the fields in the bottom display to their default 

values. 

After you click Search or Reset, the Event Log page refreshes. 

7.3 Event Log Purge 

You can purge outdated records from the Ensemble event log by clicking the Purge command at the top of the Event Log 

display. A dialog appears in the bottom half of the screen. 

The fields in this form allow to you purge event log entries as follows: 

• Type of Record — You are purging the Event Log. 

• Current Count — The number in this column reflects the total number of event log entries that are now in the persistent 

store for this production. Use the Current Count to decide whether or not it is worthwhile to purge the event log at this 

time. 

• Do not purge most recent — This is the parameter for the purge operation. It tells Ensemble how many days’ worth of 

event log entries to keep. The number can be 0 (zero), which keeps nothing and delete all entries that exist at the time 

of the purge operation. The default value for Do not purge most recent is 7, which keeps entries for the last seven days. 

The count of days includes “today,” so keeping messages for 1 day keeps the messages generated on the current day, 

according to local server time. 

At the bottom of the display area is the Start Purge command. If you click this command, Ensemble immediately purges 

the event log according to the parameters you have entered in the dialog. 

CAUTION: 

You cannot undo the Start Purge operation. 

Note: You can also purge event log entries along with other management data using the [Ensemble] > [Maintenance] > 

[Purge] page. 


8 


The Ensemble Message Browser allows you to find and view information about the messages that your Ensemble production 

has sent or queued. You can navigate to this page in the Ensemble Management Portal in one of the following ways: 

• Click Message Browser on the Ensemble menu. 

• Click Show Messages at the top of the [Ensemble] > [Maintenance] > [Purge] page. 

There is no menu on the Ensemble Message Browser page. You can return to the Ensemble home page by clicking 

[Ensemble] in the navigation path. 

The Message Browser features two display areas, one above the other: 

• Message List — The upper display lists messages in the persistent message store for the selected namespace. 

• Message Filter — The lower display permits you to enter search criteria to filter the list of messages. 

If the upper display is empty, click Search in the lower display. If the lower display is empty, click [Messages] in the navigation 

path. 

The Ensemble Message Browser also contains two commands above the message list: 

• Compare Messages — Click to display the message contents of two messages side by side; choose them by selecting 

the check box next to exactly two messages in the list. (To return to the Message Browser page from the contents display, 

click the browser’s Back command.) 

• Resend Messages — Click after selecting the check box of one or more messages to navigate to the Resend Messages 

page. 

8.1 Message List 

The Message Browser upper display contains a table. Each row in the table provides the following columns of information 

about a message: 

• Check box — Mechanism for selecting messages for the compare and resend commands. 

• # — An incremental count of the number of entries in the table. 

• ID — The unique identifier for the instantiated message; the object identifier () of the message header. 

• TimeCreated — The date and time when this message was instantiated. 



• Session — The unique identifier for the session that is (or was) associated with this message. A session marks the 


request message has an ID value that is identical to the Session. Several additional messages may be instantiated within 

Ensemble during the session to fulfill the primary request. All of these messages share the same Session, but each has 

a different ID value. 

You can click the Session number in any row of the table to see a visual trace of the message object through the production. 

• Status — Indicates the status of the message within its normal life cycle: Created, Queued, Delivered, Deferred, 

Completed, Discarded, or Suspended. If there is a request-response pair, the value does not indicate an overall status 

for the pair; a request may end up with a different Status from its corresponding response. 

A message in transit has a Status of Created, until it finds its place on a queue, when it becomes Queued. A message 

that reaches its destination is at first Delivered, then finally Completed. An asynchronous response is Discarded if it 

arrives after the timeout period for the corresponding request expired. A message response can been Deferred by a 

business operation to be sent later on; when a Deferred message is finally sent, it has a Status of Completed. 

Some business operations are designed to set the status of any failed messages to Suspended. Alternatively, an 

administrator can suspend a message from the Instances display on the [Ensemble] > [Host Monitor] page. In either 

case, such a message goes on a special queue where Ensemble keeps all Suspended messages. An administrator can 

use the [Ensemble] > [Maintenance] > [Suspended] page to examine Suspended messages, diagnose the problem, and 

if possible resend the Suspended messages after the problem is fixed. 

• Error — A quick overview of the results returned by the message to the configuration item that sent it, the Error field 

can have the values OK, Error, Retry, or Inactive. 

OK means normal behavior; Retry means the message experienced a failure but the item that sent it is configured to 

retry the failed message. Error means an error was reported somewhere in the activity. Inactive means that the item 

that sent the message has been idle for longer than its Inactivity Timeout setting, and may require diagnostic action. 

When you filter messages for diagnostic purposes, you can use the Error field to quickly select only those messages 

with errors. 

• Source — The configuration item (service, process, or operation) that sent the message. 

To the right of each row are four commands which you can click to display additional message information: 

• Details — Display the fields in the message object in the bottom half of the Message Browser display. 

• Contents — View the contents of the message body in an appropriate format. 

• Trace — Visually trace the path of the message object through the production. 

• Report — Display all the fields in the message header and message body in XML format. 

The default background color of rows in the Message Browser table indicates the message’s Status as shown in the following 

table. 

Color 

Red 

Orange 

Green 

Silver 

Orange 

Indication 

The message encountered an Error. 

The message is Queued. 

The message marks the start of a session. 

The message arrived after a timeout expired and is marked as Discarded. 

The message is Suspended. 


Message List 

Color 

White and pale blue, 

in alternating rows 

Indication 

These messages are OK. 

8.1.1 Message Details 

If you select a message in an Ensemble Management Portal page and click Details, additional message information displays 

in the lower portion of the screen. 

You can display message details by clicking Details next to the message displayed on the following pages of the Ensemble 

Management Portal: 

• [Ensemble] > [Messages] 

• [Ensemble] > [Messages] > [Visual Trace] (click on a specific message in the trace) 

• [Ensemble] > [Queues] > [Contents] 

• [Ensemble] > [Maintenance] > [Suspended] 

Details of the selected message display in the lower portion of the page. The left side of the display shows the entire contents 

of the Message Header. Fields include: 

• Type — The message type, Request or Response. 

• — The object identifier for the message header. Whenever a message header and message body are combined 

together as a message, the ObjectId value in the header is used to identify the combined message object. As a result, 

this value is the same as the message ID listed in the Message Browser and other pages in the Ensemble Management 

Portal. 

• Priority — The priority of the message relative to others in the queue: RealTime (1), High (2), Normal (3), or Low (4). 

The Ensemble messaging engine assigns priority values to messages automatically, in the course of normal processing, 

for its own use. Message priority cannot be programmed into a message class or configured in any way. Priority values 

are based in part on whether the message is synchronous (High) or asynchronous (Normal). Also, messages that start 

or stop a production are assigned greater priority than other types of message. 

• Invocation — The style of invocation for message: Queue or Inproc. 

Inproc means the message is formulated, sent, and delivered in the same process in which it was created. The job is 

not released to the sender’s pool until the message is delivered to the target. 

Queue means the message is created in one job, then placed on a queue, at which time the original job is released. 

Later, when the message is processed, a different job is allocated for the task. 

• TimeCreated — The message creation time stamp. For Queue messages, this is the time when Ensemble placed this 

message on the queue. For Inproc messages, this is the time when Ensemble called the Send method. 

• TimeProcessed — The message usage time stamp. For Queue messages, this is the time when Ensemble took the 

message off the queue to be processed. For Inproc messages, this is the time when Ensemble began processing the 

message. For Inproc messages, TimeProcessed will be very close to TimeCreated. 

• Status — Indicates the status of the message within its normal life-cycle: Created, Queued, Delivered, Deferred, 














• IsError — An integer value of 1 means that IsError is true; the message encountered an error. A value of 0 means 

IsError is false; the message did not encounter any errors. 

• ErrorStatus — If IsError is 1, then this is the text associated with the error. When IsError is 0, ErrorStatus is the string 

“OK”. 

• CorrespondingMessageId — If the message Type is a Response, this field contains the ObjectId of the corresponding 

request. If the message Type is a Request, this field contains the ObjectId of the corresponding response (if any) or it 

is blank. 

• SessionId — The unique identifier for the session that is (or was) associated with this message. A session marks the 


request message has an ID value that is identical to the SessionId. Several additional messages may be instantiated 

within Ensemble during the session, in order to fulfill the primary request. All of these messages share the same SessionId, 

but each has a different ID value. 

• SourceConfigName — The name of the configuration item that sent the message. 

• TargetConfigName — The name of the configuration item that was intended to receive the message. 

• SourceBusinessType — BusinessService, BusinessProcess, BusinessOperation, or Unknown. 

• TargetBusinessType — BusinessService, BusinessProcess, BusinessOperation, or Unknown. 

• BusinessProcessId — Every business process that gets executed has an instance and this is the object ID of that instance. 

If the message is a request, this field identifies the business process in whose context the message was created (sender). 

If the message is a response, this field identifies the business process to which it is being returned (receiver). This field 

is empty in various circumstances, for example if an error occurred. 

• TargetQueueName — The destination “address” for the message: Where is it going The TargetQueueName may be a 

name or a number. A name identifies a public queue, such as Ens.Actor. A number is the job ID associated with the 

private queue of a business host. 

• ReturnQueueName — The return “address” for the message: Where did it come from The ReturnQueueName may 

be a name or a number. A name identifies a public queue, such as Ens.Actor. A number is the job ID associated with 

the private queue of a business host. The ReturnQueueId value is listed even if there is no response expected or needed 

for a particular request message type. 

• MessageBodyClassName — The class name for the message body. 

• MessageBodyId — The object identifier for the message body. This field matches the field in the Message 

Body table. 

The right side displays the Message Body information. Fields include: 

• Message Body: Message Type — The message body class name. 

• If the message body is a standard Ensemble message body object, a table displays the following information: 

– — The object identifier for the message body. This field matches the MessageBodyId field in the 

Message Header table. 

– The name and value of each property in the Message Type class. 

If the message body is any other type, there are no additional fields in the display. 


Message List 

• Contents — Click to view the message contents. 

8.1.2 Message Contents 

If you select a specific message in an Ensemble Management Portal page and request to view its contents, the information 

displays in the lower half of the screen. 

You can display message contents from various locations in the Ensemble Management Portal, as follows: 

• [Ensemble] > [Messages]: 

– Select a message and click Contents 

– Select two check boxes in the column at far left, and click Compare Messages. This displays the contents of two 

messages side by side. To return to the [Ensemble] > [Messages] page, click the browser’s Back command. 

– While viewing message Details, click Contents. 

• [Ensemble] > [Messages] > [Visual Trace] — Select a message and click Contents. 

The standard Ensemble message body appears in colorized XML format, as shown in the following example: 

Figure 8–1: Standard Ensemble Message Body Contents in XML Format 

A virtual document, such as an HL7 message, appears in segments, with one segment visible per line, as shown in the following 

figure: 

Figure 8–2: HL7 Virtual Document Contents in Message Segment Format 

For HL7 messages, from left to right, each line displays: 

• The segment number on a white background: 1, 2, 3, etc. 



• The segment name on a shaded background: MSH, PID, etc. If you hover the cursor over a segment name in the shaded 

column, a tooltip describes the purpose of the message segment. 

• The field contents and separator characters as provided in the message. If you hover the cursor over a field in this display, 

a tooltip provides syntax information that a developer can use to access fields within the message body from Ensemble 

data transformations and routing rules. 

To view the contents of an entire virtual document, it may be necessary to drag the bottom scroll bar far to the right, 

depending on the amount of data in the message. For more about working with HL7 messages in the Ensemble Management 

Portal, see the “Viewing and Transforming HL7 Messages” chapter in the Ensemble HL7 Version 2 Development Guide. 

For more about virtual documents, see Ensemble Virtual Documents. 

8.1.3 Visual Trace 

Click Trace next to a message in the Ensemble Management Portal to display the [Ensemble] > [Messages] > [Visual Trace] 

page. The Ensemble Visual Trace page visually traces a specific message instance as it travels (or as it did travel) through 

the currently running production. You can also optionally display any relevant entries logged within the Ensemble event 

log among the messages in the trace. 

You can display the Visual Trace page by clicking Trace from the following pages in the Ensemble Management Portal: 

• [Ensemble] > [Messages] 

• [Ensemble] > [Queues] > [Contents] 

• [Ensemble] > [Maintenance] > [Suspended] 

• [Ensemble] > [Testing Service - 4 of 4] results page, after a testing session 

There is no menu on the Visual Trace page. You can return to the home page by clicking [Ensemble] in the navigation path. 

Under the Visual Trace page title bar are two display areas, one above the other. The top display contains a visual representation 

of message activity. The bottom display contains fields that permit you to select messages for visual display. You 

can drag the boundary between the displays to resize them as needed. In some cases you must use the scroll bars to see the 

full contents of either display. 

The Visual Trace page top display has three columns. Each column represents an Ensemble configuration item that can 

exchange messages with the other Ensemble configuration items shown on the page. These are: 

• Business Services (the column at left) 

• Business Processes (the column at center) 

• Business Operations (the column at right) 


Message List 

Figure 8–3:The Visual Trace Page 

When a message has traveled from one item to the next, an arrow connects the two items. The arrow is a horizontal line 

across the vertical columns that represent the items: Services, Processes, or Operations. The direction of the arrow indicates 

the path of the message, as follows: 

• The source item, marked with a circle, is the item that sends the message. The arrow points away from the source item. 

• The target item, marked with a rounded rectangle, is the item that receives the message. The arrow points toward the 

destination item. 

Each arrow in the Visual Trace page carries three fields of information: 

• A number in square brackets at left is the message identifier — the ID field displayed in the Message Browser display. 

If there are multiple messages in the Visual Trace display you can distinguish between them easily using this number. 

• A date and time above the arrow identifies TimeCreated — the date and time when this message was instantiated. 

• The name below the arrow is the message name. The configuration item that sent the message is identified at the top 

of the column. Items are grouped from left to right, as follows: Services, Processes, and Operations. 

Normal request message arrows are blue; responses are green. If a message encountered an error, its arrow is red. 

If there are more than 100 messages in the Visual Trace display, the list is displayed in groups of 100. At the bottom of the 

page is a row of commands that you can click to choose which group of messages to view: 0–100, 101–200, 201–300, and 

so on. 

If you click on an arrow in the Visual Trace page, the definition of that specific message is displayed in the bottom half of 

the screen. This is the same display that you see when you click Details in the [Ensemble] > [Messages] page. 



When you have selected a message in the Visual Trace page, you can click Contents to view the contents of the message 

in an appropriate format. 

You can right-click anywhere on the diagram in the top display to reveal the Visual Trace page context menu. The following 

menu options are available: 

• Zoom — Choose a zoom factor for the Visual Trace diagram. Choose a large factor to view details, a small factor to 

gain an overview. 

• Search — Search for a message according to the search criteria entered in the bottom half of the display. 

• Find, Find Again — Search for a text string in the underlying XML document. When found, the corresponding string 

is highlighted in the Visual Trace page top display. 

• Left-click on a segment in the Visual Trace page top display to select it. Right-click and choose Show Details. The 

bottom display provides detailed information about that segment of the message’s path through the production. 

• Left-click on a segment in the Visual Trace page top display to select it. Right-click and choose Show Contents. The 

bottom display shows the message contents that were transmitted on this segment of the message’s path through the 

production. 

• Legend — Reveal a popup guide to the conventions used for message arrows. This guide is the Visual Trace Legend, 

shown in the following figure: 


• About SVG Viewer — Display version and copyright information about the SVG Viewer used by the Visual Trace page. 

Note: 

When you view calls in the Visual Trace, synchronous calls from business processes are portrayed as if they were 

asynchronous. This does not change the fact that the calls are actually synchronous. It is a side effect of the 

internal tracking mechanism that Ensemble uses to free system resources while it is waiting for a synchronous 

call to return. 

When you are done viewing the top half of the Visual Trace page, there are fields in the bottom half of the Visual Trace 

page that allow you to select further messages for viewing. If these selection fields are not currently displayed, you can 

display them by clicking [Visual Trace] in the navigation bar. This action empties the top display and refreshes the bottom 

display with the following fields: 

• SessionId — Enter a session identifier, if you know a specific session by number. A session marks the beginning and 

end of all the activities prompted by a primary request message from outside Ensemble. The primary request message 


Message Filter 

has an ID value that is identical to the SessionId. Several additional messages may be instantiated within Ensemble 

during the session, in order to fulfill the primary request. All of these messages share the same SessionId, but each has 

a different ID value. 

• StartId — Enter the lower limit of a range of message ID values. 

• EndId — Enter the upper limit of a range of message ID values. 

• StartTime — Enter the lower limit of a range of TimeCreated values. 

• EndTime — Enter the upper limit of a range of TimeCreated values. 

• MaxMessages — The maximum number of messages to display as a result of the search. If more matches are found, 

they will not be displayed. Enter a number. The default is 50. 

Enter information in these fields and click Search. The Visual Trace top display changes accordingly. 

If you do not know the Search details, you cannot continue to use the Visual Trace page. You must first return to the 

[Ensemble] > [Messages] page to get an idea of what you need, then click Trace next to an entry in the Message Browser 

table. 

8.2 Message Filter 

If you do not see the message you want to view in the Message Browser page, you can filter and search the list of messages 

using fields that appears in the bottom half of the screen. There are many options for the filtering task; this topic explains 

them in detail. 

You can archive a specific set of filter criteria and retrieve it for later use. If you are using an archived filter of this kind, 

its name appears at the top of the Message Browser filter display. Below this is a row of commands: 

• Search — Sort the message list using the criteria in the bottom display. 

• Reset — Redisplay the message list using the default filter criteria. 

• Open — Retrieve a previously archived search. Ensemble displays a list of the saved searches in this namespace. 

Choose one and click OK. 

• Save — Save the current search to an archive so that you can retrieve it during a later session. If you are using a previously 

archived search, the Save operation overwrites it. 

• Save As — Save the current search to a new archive. Ensemble displays a dialog in which to enter the name of the 

search. Type a name and click OK. 

8.2.1 Basic Filter Terms 

To refine search criteria, you can edit the following fields in the Message Browser page: 

• Type — Choose a value from the list: Session Start, Request, Response, or All (the default). 

• Time Format — Select a value from the list: Time Only or Complete (time with date). 

• Start Time — Enter the lower limit of a range of Time Created values. 

• End Time — Enter the upper limit of a range of Time Created values. 

• Sort Order — Select Oldest First or Newest First. 

• Color By — Choose a criterion from the list: TimeCreated, SessionId, Status, Error, Source, or none (blank). The 

background color of rows in the Message Browser table changes according to your choice. 



If the Color By selection is blank, the default background color indicates the message’s Status as described in the 

Message List section. 

• StartId — Enter the lower limit of a range of message ID values. 

• EndId — Enter the upper limit of a range of message ID values. 

• MaxRows — The maximum number of messages to display as a result of the search. If more matches are found, a 

message displays at the bottom of the table: “There is more data.” To display the additional data, change the MaxRows 

value and click Search again. 

• Is Error — Select a value from the drop-down list: 

– Select true to list only messages that encountered errors. 

– Select false to list only messages without errors. 

• Status — Choose a value from the list: Created, Queued, Delivered, Deferred, Completed, Discarded, or Suspended. 

• Source — The configuration item that sent the message. Enter a name in the text box. If the configuration name contains 

spaces, do not use single or double quotation marks around the string. Simply enter the configuration name, including 

any space characters. 

8.2.2 Detailed Filter Terms 

The Message Browser filter display also offers Detailed Filter Terms. This panel of the filter display allows you to select 

extremely specific criteria based on the message header or message body contents. The interface is similar to the Rules 

Editor interface. You can add rules and define conditions. You can build statements using comparison operators, and 

organize statements using the logical operators AND and OR. 

From left to right, the columns in each row of the Detailed Filter Terms interface are: 

1. Type — Choose a value from the drop-down list. 

2. Class Name — Click the More command (...) to choose from a list of classes. 

3. Conditions — Allows you to specify fields and values for your logical statement. 

The following topics describe how to construct a filter using the Detailed Filter Terms interface. 

8.2.2.1 Logical Statements 

Each row in the Detailed Filter Terms interface represents a logical statement. To add a statement, click Add. To delete a 

statement, click X. After you add multiple rows to the Detailed Filter Terms, you can click the up-arrow and down-arrow 

icons to adjust the order of statements. 

If you add multiple rows, they are implicitly joined by AND, so that if you have three statements visible: 

Logical Statement 1 



Your filter actually works like this: 


AND 


AND 


You can vary this convention by adding a row and choosing OR in the Type field, then adding a row with another logical 

statement. When you do this, it inserts a logical OR between rows. The row with OR in it has no other details, just the OR 



selection in the Type field. Suppose you added an OR row and a fourth logical statement to the list shown above. The 

Detailed Filter Terms panel now looks like this: 




OR 


And the resulting logic is now: 


AND 


AND 


OR 


The operator AND binds more tightly than OR, so the effect of the above sequence is actually: 

(1 AND 2 AND 3) OR 4 

8.2.2.2 Filter Type 

In the Type column, choose a value from the drop-down list. The following table lists the Type choices and how they affect 

your subsequent choices in the Class Name and Conditions fields. 

Table 8–1: Options for Filter Type 

Type 

Body Property 

Header Field 

OR 

VDoc SearchTable Field 

VDoc Segment Field 

VDoc Property Path 

Class Name and Conditions refer to... 

Properties of a standard Ensemble message body object. 

Fields in a standard Ensemble message header object. 

(used to logical OR two filter terms) 

Entries in a search table class that you have defined in this Ensemble namespace. 

A search table class is a specialized tool that you create to work with virtual 

documents, a convention for representing Electronic Data Interchange (EDI) 

formats like HL7 Version 2 or X12. 

Fields in a virtual document message segment. Identify the standard (HL7 Version 

2 or X12) and the segment of interest. Ensemble then prompts you to choose 

from a list of fields in that segment. 

Fields in a virtual document message segment. Identify the standard (HL7 Version 

2 or X12) and then enter a virtual property path that identifies a message segment 

and field that is valid for that standard. 

Note: 

For background information about the VDoc fields in the Detailed Filter Terms interface, see Ensemble Virtual 

Documents. You do not need to use these fields unless your production routes HL7 Version 2 or X12 messages. 

8.2.2.3 Filter Class 

In the Class Name column, click ... (the More command). Ensemble displays a list of all the classes appropriate for the Type 

of message that you have chosen. For example: 



Table 8–2: Options for Filter Class 

Type 

Body Property 

Header Field 

OR 

VDoc SearchTable Field 

VDoc Segment Field 

VDoc Property Path 

Class Name 

Click ... and choose from all the message classes in the Ensemble namespace. 

— 

— 

Click ... and choose from all the search table classes in the Ensemble namespace. 

Click ... and choose from all the virtual document classes in the Ensemble 

namespace. 

Click ... and choose from all the virtual document classes in the Ensemble 

namespace. 

8.2.2.4 Filter Conditions 

In the Conditions column, specify fields and values for your logical statement, from left to right, as follows: 

1. Click .... Ensemble displays a list of choices appropriate for the Type and Class Name that you have chosen in this row. 

For further instructions, see the first table below. 

2. Choose a comparison operator from the drop-down list. See the second table below. 

3. Type an expression that you intend to match using the selected operator. 

Choices in the Conditions panel vary according to your choice of Type. The following table describes the choices. 

Table 8–3: Fields and Properties for Message Filter Conditions 

Type 

Body Property 

Header Field 

OR 

VDoc 

SearchTable 

Field 

Conditions 

Click ... and choose from a list of all the properties in the Class Name message class. 

— 

— 

Click ... and choose from a list of all the search table entries defined in the Class Name 

search table class. 



Type 

VDoc Segment 

Field 

Conditions 

You may use the Conditions panel as follows: 

1. Ensure that the left-hand Conditions field is empty. 

2. Click ... and when prompted, click OK. 

3. Choose a schema category and segment name from a list of supported schema 

categories and segment names. The contents of this list depend on your Class Name 

choice of virtual document type. Click OK to save your selections. 

4. A list of fields in the chosen segment displays. Choose a field and click OK. 

5. The resulting entry in the left-hand Conditions field looks something like this. This is 

an HL7 example. Different specific syntax is offered for X12, but the idea is the same: 

2.3.1:[PID:PatientAddress().city] 

Instead of selecting options to fill the left-hand Conditions field, you can type a string into 

the field, as long as you are careful to use the correct syntax. For HL7, you can type a 

numeric references if you prefer them to names, for example [5], [18.1], or 2.3.1:[3().1]. 

You may edit out the category reference and colon prefix, but keep the square brackets 

and their contents intact. 

Square brackets differ from curly brackets in that square brackets enclose a segment:field 

combination that does not require you to identify its containing message structure. In the 

example above, Ensemble matches any message structure in the 2.3.1 schema category 

that contains a PID segment with a PatientAddress().city field . 

VDoc Property 

Path 

You may use the Conditions panel as follows: 

1. Ensure that the left-hand Conditions field is empty. 

2. Click ... and when prompted, click OK. 

3. Choose a schema category and message structure from a list of supported schema 

categories and message structures. The contents of this list depend on your Class 

Name choice of virtual document type. Click OK to save your selections. 

4. A list of segments and fields in the chosen message structure displays. Choose a 

segment:field combination and click OK. 

5. The resulting entry in the left-hand Conditions field looks something like this. This is 

an HL7 example. Different specific syntax is offered for X12, but the idea is the same: 

2.3:ADT_A06:{MSH:SendingFacility.namespaceID} 

Instead of selecting options to fill the left-hand Conditions field, you can type a virtual 

property path into the field, as long as you are careful to use the correct syntax. Curly 

bracket syntax requires a specific message structure, such as ADT_A06, to be identified. 

The comparison operator between the two values in a Conditions statement can be any one of the following. 

Table 8–4: Comparison Operators for Message Filter Conditions 

Operator 

= 

!= 

The condition is true when the value at left is... 

Equal to the value on the right. 

Not equal to the value on the right. 



Operator 

> 

>= 

< 

, >=,

Resend Messages 

8.3 Resend Messages 

Your production may have circumstances when something goes wrong with a message and you wish to resend it, or you 

want to edit the content of the message before resending it. Select one or more check boxes in the column at the far left of 

each message you want to resend on the Ensemble Message Browser page and click Resend Messages. The [Ensemble] > 

[Messages] > [Resend] page displays a table of information about the selected messages. The list displays message information 

as described in the following table. 

Column 

Session 

Header 

Msg Body 

Created 

Source 

Target 

Description 

The unique identifier of the session to which this message belongs. Click to view the visual 

trace of the primary message object through the production. 

The unique identifier for the message header object. The Header number is the same as the 

Session number only if this message is the primary request message. Otherwise, it may be 

one of the subsequent messages that fulfills the original request. Click to view the visual trace 

of this specific message. 

The unique identifier for the message body object. Click to view the message contents. 

The message time stamp. For Queue messages, this is the time when Ensemble placed this 

message on the queue. For Inproc messages, this is the time when Ensemble called the 

Send method. 

The name of the configuration item that sent the message. 

The name of the configuration item that is the intended recipient of the message; this field 

also indicates if the production target is not running.* Click to see the contents of the target’s 

message queue. 

* You cannot resend a message if the intended target is not running. 

Above the list of selected messages next to Resend these messages is a choice of commands to perform on these messages: 

• No — Cancel the resend operation and empty the list of messages on the Resend page. Click [Messages] in the navigation 

path to return to the Ensemble Message Browser page. 

• Yes — Resend the messages, either to the original Target, or to the item you identify in the Set New Target field. When 

you click Yes, the message table displays with an additional Resend Status column on the left. Any status other than 

OK indicates that the resend operation failed. 

Any message that you resend retains the same Session identifier and transmits the same Msg Body object, but it acquires 

a new Header object with a new identifier to mark its additional trip through the production. Click the Header identifier 

to see a visual trace, including both the original message transmission and any resend operations that involve the same 

Session and Msg Body. The description in the new message header contains text including the original Header object 

identifier indicating that this message has been resent. 

• Edit then Resend — Edit a single message before resending; this command is only available if you select exactly one 

message on the Ensemble Message Browser page. See the Resend Editor section for details. 

• Set New Target — You may choose a different Target destination for the message. This must be the name of a configuration 

item within the same production. The Set New Target field offers a list of business hosts. 

You also have the option to select a check box to Insert resubmitted messages at head of Queue. 



8.3.1 Resend Editor 

When you select one message to resend from the Ensemble Message Browser page, you have the option to edit the body 

of the message before resending it. 

1. Click Edit then Resend to display the Ensemble Resend Editor page. 

2. Use the entry fields to update the message body data. The fields vary depending on the method signature of the message. 

If the method has no properties, none are displayed. 

If you are editing a virtual document message (HL7, X12), you can edit data in the message content and also edit object 

properties in the box below the content box. 

3. Click Resend to send a new copy of the message header with your edited message body contents to the target. 

4. After a successful resend, the page refreshes with text indicating the new Header and Msg Body identifiers. Click Trace 

to see the visual trace of the resent message. 

Any message that you edit and then resend retains the same Session identifier, but acquires a new Header object with a 

new identifier to mark its additional trip through the production and transmits a new Msg Body object with the updated 

data. The visual trace includes both the original message transmission and any resend operations that involve the same 

message. The description in the message header contains text indicating this message has been resent; the description 

includes the original along with any subsequent header object identifiers. 


9 


The [Ensemble] > [Business Processes] page allows you to view information about business processes in the currently 

running production. Some of the information describes the underlying host classes; other information shows current instances 

of configured business processes that are active within the production. 

You can display the Business Processes page from the Ensemble Management Portal as follows: 

• Main menu — Choose the Business Processes option. 

• [Ensemble] > [Maintenance] > [Purge] — Click the Show Business Processes command at the top of the page. 

There is no menu on the Business Processes page. You can return to the home page by clicking [Ensemble] in the title bar 

navigation path. 




9.1 Business Process List 

Under the Business Processes page title bar is a table called Defined Business Processes. Each row of the table lists one 

of the business processes known to the currently selected Ensemble namespace. All items are listed. Some may be instantiated 

by the currently running Ensemble production, some may not. Each row of the table begins with the following column: 

• Name — The configured name of the business process. 

To the right of each row in the table are three commands that you can click to display detailed information about the business 

process: 

• Click Definition to display a BPL diagram of the underlying host class for the business process. 

• Click Instances to list any current instances of the business process in the currently running production. If a business 

process has completed its work, there is no entry for it on this page. 

• Click RuleLog to view a record of business rules invoked by this business process. 



9.2 BPL Viewer 

The [Ensemble] > [Business Processes] > [BPL Viewer] page displays a BPL diagram of the underlying host class for the 

business process, if a diagram is available. You can display this page from various locations in the Ensemble Management 

Portal, as follows: 

• [Ensemble] > [Business Processes] — Click Definition next to the business process name. 

• From the configuration diagram on the [Ensemble] > [Productions] page — While configuring a business process, click 

the BPL Definition command. 

There is no menu on the BPL Viewer page. You can return to the home page by clicking [Ensemble] in the title bar navigation 

path. 

Figure 9–1:The BPL Viewer Page 

Under the BPL Viewer page title bar are two display areas, one above the other. The top display shows the graphical view 

of the underlying host class for the currently selected business process. This is the same BPL diagram that you can create, 

edit, or view in the Ensemble Studio environment. The bottom display provides read-only information about the class and 

about the BPL diagram. You can drag the boundary between the displays to resize them as needed. In some cases you must 

use the scroll bars to see the full contents of either display. If there is no BPL diagram of the class available, the page reports 

this and nothing is shown in either display. 

When there is a BPL diagram available in the top display, you can click on the diagram and then right-click to reveal the 

BPL Visual Editor context menu. This is the same menu that is available when you are working in the BPL Visual Editor 

in the Studio tool. In the BPL Viewer page, the following view-only options are enabled for the context menu: 

• Zoom — Choose a zoom factor for the BPL diagram. Choose a large factor to view details, a small factor to gain an 

overview. 


BPL Viewer 

• Show Annotation — When this option is selected, reveal the text notes that explain each shape; otherwise, conceal 

them. When you reveal annotations, they appear to the upper right of each shape that has an element in 

the BPL document. 

• Arrange Layout — Auto-arrange the position of shapes in the diagram. 

• Validate Activity — You can select one of the items in the diagram and choose the context menu Validate Activity 

command to make sure it is properly defined. 

• Rules Editor — If you select a element in the diagram you can choose the Rules Editor command to open the 

associated rule set on the [Ensemble] > [Business Rules] > [Business Rule Editor] page. 

• Drill Down, Drill Up — An activity that consists of several sub-activities displays an square icon that contains a plus 

sign or a circular arrow. Click on this icon to drill down for details about the activity. Alternatively, you can select the 

activity, right-click, then choose Drill Down from the context menu. In either case, a BPL diagram of activity details 

displays. To return to the higher level, right-click and choose Drill Up. 

• Find, Find Again — Find and Find Again let you search for a text string in the underlying BPL document. When found, 

the corresponding string is highlighted in the BPL diagram. 


• About SVG Viewer — Displays version and copyright information about the SVG Viewer used by the BPL Visual 

Editor. 

When there is a BPL diagram available, several data fields appear in the bottom display. You cannot edit these fields in 

the Ensemble Management Portal, but you can view them. If you want to change them, you must enter the Ensemble Studio 

environment and edit them there. The following read-only data fields appear on the BPL Viewer page when the diagram 

first displays. For details about any of these fields, see documentation of the BPL element in the Ensemble 

Business Process Language Reference: 

• On the left: 

– Type — The type of BPL element: for the business process as a whole. 

– Name — The business process class name. 

– Component — An integer value of 1 means that the business process has been designated as a reusable component. 

A value of 0 means it has not. 

– Annotation — If an annotation was added in the Studio environment, it appears here. 

– Show Annotation — An integer value of 1 means that Show Annotation is true; display any BPL annotations in 

the BPL Viewer top display. A value of 0 means Show Annotation is false; do not display annotations. 

– Width — Width of the BPL diagram in logical units. 

– Height — Height of the BPL diagram in logical units. 

• On the right: 

– Layout — automatic or manual 

– Language — basic or objectscript 

– Request — The primary request class for the business process. 

– Response — The primary response method for the business process, if a response was defined. 

– Context — A list of the properties in the general-purpose, persistent variable context, which is defined using the 

and elements in BPL. 

– ContextSuperClass — The superclass for the business process context object, if a unique one was defined 



– Includes — A comma-delimited list of include file names, if any were supplied. 

– Version — An integer that expresses a version number for the business process. 

If you select an element in the BPL diagram, different fields display in the lower half of the BPL Viewer page. For details 

about any of these fields, see documentation of the corresponding BPL element in the Ensemble Business Process Language 

Reference: 

• For all element types, the following fields display: 

– Type — The type of BPL element, such as , , , etc. 

– xPos — Horizontal position of the element in the BPL diagram, relative to the origin (0,0) at top left. Numbers 

increase as the element moves to the right. 

– yPos — Vertical position of the element in the BPL diagram, relative to the origin (0,0) at top left. Numbers 

increase as the element moves down. 

• For most elements, the following fields also display: 

– Name — The element name, if it has one. 

– Annotation — If an annotation is available in the BPL file, it appears here. 

– Disabled — An integer value of 1 means that the business process has been disabled. A value of 0 means it is 

enabled (not disabled). 

• Other fields may appear as appropriate for the element type. For example: 

– 

• Property — The property to be manipulated. 

• Value — The value to be given to the property. 

• Action — Whether the value is to be set, appended (for a collection), or other. 

• Key — A key for finding a member of a collection property. 

– 

• Target — The queue that is the target of a message sent by a element. 

• Async — An integer value of 1 means that Async is true; the element sends a message asynchronously. 

A value of 0 means Async is false; the element sends the message synchronously. 

• Request — The name and parameters of the request that is sent by this element. 

• Response — The name and parameters of the response that is expected by this element. If no response 

is defined, the field is blank. 

– 

• Property — The property to be iterated over. 

• Key — The index that controls the iteration. 

– 

• Calls — A list of the elements that this element waits for. 

• Type — Wait for “all” calls to finish, or simply “any” call. 

• Timeout — The number of seconds to wait. 


Business Process Instances 

– 

• Value — The text string to be output by this element. 

You can close the BPL Viewer page and return to the [Ensemble] > [Business Processes] page by clicking [Business Processes] 

in the navigation path at the top of the BPL Viewer page. 

9.3 Business Process Instances 

The [Ensemble] > [Business Processes] > [Business Process Instances] page displays any current instances of a business 

process in the currently running production. If a business process has completed its work, there is no entry for it on this 

page. 

You can display the Business Process Instances page by clicking Instances next to the name of a business process name 

on the [Ensemble] > [Business Processes] page. 

There is no menu on the Business Process Instances page. You can return to the home page by clicking [Ensemble] in the 

title bar navigation path. You can return to the [Ensemble] > [Business Processes] page by clicking your browser’s Back 

command one or more times. 

There are three commands at the top of the Business Process Instances page, below the title bar: 

• Click the Home command to return to the home page and the main menu. 

• Click the Filter Instances command to find instances of special interest. 

• Click the Purge command to purge instance records. 

Under the row of commands are two display areas, one above the other: 

• The top display lists the instances. 

• When you click an underlined ClassName in the top half of the screen, the corresponding BPL diagram displays in the 

top half of the screen. 

• When you click the Filter Instances command in the top half of the screen, the bottom display permits you to enter 

search criteria to filter the list of instances. 

• When you click an underlined PrimaryRequest number in the top half of the screen, the corresponding message contents 

display in XML format in the bottom half of the screen. 

The following topics provide details. 

9.3.1 Business Process Instance Entries 

The Business Process Instances table displays the start time for the currently running production, followed by a list of 

business process instances. Several columns of information are provided for each instance in the table: 

• ID — The unique identifier for the instantiated business process. 

• IsCompleted — An integer value of 1 means that IsCompleted is true; the primary request that initiated this business 

process has been completed. A value of 0 means IsCompleted is false; the primary request has not yet been completed. 

• ClassName — The configured name of the business process host class. 

When the ClassName is underlined, it means that the host class is a BPL business process. You can click on the 

underlined ClassName to display the BPL diagram for the host class. 



• SessionId — The unique identifier for the session that is (or was) associated with this business process. A session 

marks the beginning and end of all the activities prompted by a primary request message from outside Ensemble. One 

or more business processes may be instantiated within Ensemble during the session, in order to fulfill the primary 

request. All of these business processes share the same SessionId, but each has a different ID value. 

• PrimaryRequest — The message ID number of the request that caused this business process to be instantiated. The 

PrimaryRequest number is distinct from the object ID number of the business process. The PrimaryRequest may or may 

not be the same as the SessionId. If the numbers are different, it means that the request message that started the session 

triggered subsequent requests within Ensemble, and one of these later messages is the one that actually instantiated 

the business process. 

When the PrimaryRequest number is underlined, it means that the primary request message can be displayed as a set 

of properties in XML format. You can click on the underlined PrimaryRequest number to display the message properties 

in colorized XML format in the bottom half of the screen. For example: 

• TimeCreated — The date and time when this business process was instantiated. 

• TimeCompleted — The date and time when this business process completed the primary request that instantiated it. If 

this request has not been completed, this field is blank. 

• ContextId — The unique identifier for the general-purpose, persistent variable context, which is defined using the 

and elements in BPL to hold persistent properties for this business process instance. This column 

is available for BPL business processes only. 

The ContextId is underlined to indicate that you can click on it to display the context properties in colorized XML 

format in the bottom half of the screen. For example: 

• RuleLog — Click this command to display a history of business rule activity for this business process instance. 

Note: 

The bottom half of the screen contains a search form that you can use to filter the list of business process instances. 

When you are done viewing the primary message content or the context properties, you can click the browser 

Refresh command to redisplay the search form in the bottom of the screen. 

In each row, background color indicates the status of the business process instance: 

• Gray — Completed. 

• White — These items are in progress. 


Business Process Instances 

9.3.2 Business Process Instance Filter 

When you click the Filter Instances command in the Business Process Instances top display, the bottom display offers a 

collection of data fields that you can use to further expand or refine the Business Process Instances table: 

• Sort Order — Select a value from the drop-down list: Oldest First or Newest First. 

• Business Process Class — Enter the name of a business process class to find all instances of that class. 

• Time Format — Select a value from the drop-down list: Time Only or Complete (time with date). 

• Max Rows — The maximum number of business process instances to display as a result of the search. If more matches 

are found, they will not be displayed. Enter a number. The default is 50. 

• Start Time — Enter the lower limit of a range of TimeCreated values. 

• End Time — Enter the upper limit of a range of TimeCreated values. 

After you have edited these fields, you can click one of the commands at the bottom of the screen: 

• Click Search to sort the list of entries in the top display using the criteria shown in the bottom display. 

• Click Reset to redisplay the entries in their default order and return the fields in the bottom display to their default 

values. 

After you click Search or Reset, the Business Process Instances page redisplays. 

9.3.3 Business Process Instance Purge 

You can purge outdated records from the Ensemble business process archives by clicking the Purge command at the top 

of the Business Process Instances display. A dialog appears in the bottom half of the screen. 

The fields in this dialog allow to you purge business process instance data as follows: 

• Type of Record — You are purging Business Processes. 

• Current Count — The number in this column reflects the total number of instances that are now in the persistent store 

for this production. Use the Current Count to decide whether or not it is worthwhile to purge these records at this time. 

• Do not purge most recent — This is the parameter for the purge operation. It tells Ensemble how many days’ worth of 

records to keep. The number can be 0 (zero), which keeps nothing and delete all business process instance records that 

exist at the time of the purge operation. The default value for Do not purge most recent is 7, which keeps records for 

the last seven days. 

The count of days includes “today,” so keeping messages for 1 day keeps the messages generated on the current day, 


At the bottom of the display area is the Start Purge command. If you click this command, Ensemble immediately purges 

instances according to the parameters you have entered in the dialog. 

CAUTION: 


Note: 

You can also purge business process instances along with other management data using the [Ensemble] > [Maintenance] 

> [Purge] page. 


10 

Host Monitor 

The [Ensemble] > [Host Monitor] page is your interface to the runtime statistics provided by the Monitor Service. The 

Monitor Service is a business service that is implicitly included in every Ensemble production. The Monitor Service continually 

monitors the activities of Ensemble items while a production is running, and records data about them at frequent 

intervals. 

You can use the Monitor page to monitor the general health of the system. If you detect a change on the page that indicates 

a problem has occurred or is developing, you can go to other pages in the Ensemble Management Portal to find out more 

about the troubled item. 

You can display the Host Monitor page in any of the following ways: 

• Click Host Monitor in the Ensemble Management Portal main menu. 

• Click the Service, Process, or Operation link in the home page statistics display. 

There is no menu on the Host Monitor page. You can return to the Ensemble home page by clicking [Ensemble] in the title 

bar navigation path. 




Under the Host Monitor page title bar are two display areas, one above the other. The top display lists all the Ensemble 

items — business services, business processes, and business operations — that you can monitor using this page. Only the 

items included in the configuration for the currently running production are shown. 

The bottom display contains a graph or table with detailed information about the item that is currently selected in the top 

display. If nothing is selected, the bottom display is empty. You can drag the boundary between the displays to resize them 

as needed. In some cases you must use the scroll bars to see the full contents of either display. 

10.1 Monitor Items 

The top display on the [Ensemble] > [Host Monitor] page contains a table. Each row of the table lists one of the Ensemble 

items — business services, business processes, or business operations — that the currently running production can instantiate. 

Some of these items may be instantiated at the present time, others might not. Each row in the table has the following 

columns: 

• Name — The item name, by default the same as the host class name. 

• Type — Service, process, operation, or actor. 


Host Monitor 

• Status — A summary of the more detailed fields provided in the bottom half of the Host Monitor page. The Status 

field can have the values OK, Error, Retry, or Inactive. 

OK means normal behavior; Retry means the item encountered a failure but is set up to retry the failed message. Error 

means an error was reported somewhere in the activity. Inactive means that the item has been idle for longer than its 

Inactivity Timeout setting, and may require diagnostic action. 

The Status value is a snapshot, as of the present moment. If the item had an OK status but is now Inactive, only the 

Inactive status is shown. 

• Adapter State — Special information about the adapter associated with this item. 

• Last Action — The date and time of the last action performed by this item. 

• Elapsed Time — The number of seconds since this item last performed an activity. 

• Queue — The number of items waiting on this item’s queue, at the current time. If the item does not have its own 

queue, the field is blank. 

• Count — The number of actions currently in the queue for this item. Count is the total number of messages queued 

minus the total number of messages processed, all since the object was first instantiated. Count can become larger or 

smaller from time to time, depending on how fast the actions are dequeued. The real significance of this number is that 

you can check how busy the system is or determine if anything has clogged the dequeue process. Problems exist if the 

number is large. 

Actions are counted differently depending on the item: 

Item 

Actor 

Business 

Service 

Business 

Process 

Business 

Operation 

Actions in Count 

The number of new business processes 

(using the actor pool) that have been started. 

The number of request messages received 

by the service from external systems. 

The number of new business processes 

(using private job pools) that have been 

started. 

The number of response messages received 

by the operation from external systems. 

Actions Not Counted 

How many messages the process has sent 

or received from items inside Ensemble. 

How many request messages the service 

has sent to items inside Ensemble. 

How many messages the process has sent 

or received from items inside Ensemble. 

How many external responses have been 

relayed back to items inside Ensemble. 

In each row, the background color indicates the item’s Status as follows: 

• Red — Error 

• Yellow — Inactive 

• Light gray — Stopped 

• Orange — There are more than 100 messages waiting in this item’s queue 

• White, with regular text — These items are OK 

• White, with bold text — These items are OK and have been active within the last minute 

Text style indicates the item’s Status as follows: 

• Bold text — Items with ElapsedTime less than one minute. 

• Dimmed text — Items with ElapsedTime greater than one hour. 


Monitor Instances 

To the right of each entry in the table are two commands: Instances and History. You can click either command to display 

detailed information about the entry in the bottom half of the Host Monitor page: 

• Click Instances to view detailed information about items of the selected type that are currently instantiated. 

• Click History to view information about the level of activity for this type of item over time. 

10.2 Monitor Instances 

The Instances display on the [Ensemble] > [Host Monitor] page allows you to view information about objects that are currently 

instantiated in the production. You can reveal this information in the bottom half of the Host Monitor page as follows: 

• From the [Ensemble] > [Host Monitor] page, click Instances next to the name of a configuration item. 

• From the [Ensemble] > [Productions] > [Configuration] page, click the configuration item and then click Instances. 

The Monitor Instances table is a snapshot of all of the objects of the selected type that are currently instantiated in the production. 

Table entries can include business process instances or jobs that are doing work on behalf of business hosts. Several 

columns of information are provided for each instance in the table: 

• Name — The item name. By default this is the same as the host class name. 

• Job — Identifies the job in which this item is running. 

• Status — A summary of the more detailed fields provided in the bottom half of the Host Monitor page. The Status 

field can have the values OK, Error, Retry, or Inactive. OK means normal behavior; Retry means the item encountered 

a failure but is set up to retry the failed message. Error means an error was reported somewhere in the activity. Inactive 

means that the item has been idle for longer than its Inactivity Timeout setting, and may require diagnostic action. 

• Adapter State — Special information about the adapter associated with this item. 

• Last Action — The date and time of the last action begun by this item. 

• Count — The number of actions that this item has performed, from instantiation up until the current time. 

• Method — The name of the host class method invoked to perform the most recent action begun by this item. 

• Retry — The number of retries attempted, so far, in pursuit of the current action. 

• Abort — The Abort and Suspend links are available only when a configuration item is currently in a Retry state. Click 

Abort to abandon attempts to retry messages. 

• Suspend — Click Suspend to suspend a message that is in a Retry state. You can later resubmit the message from the 

[Ensemble] > [Maintenance] > [Suspended] page or resend the message by clicking Resend Messages on the [Ensemble] 

> [Messages] page. 

In each row, the background color indicates the item’s Status, as follows: 

• Red — Error 

• Yellow — Inactive 

• Orange — Retry 

• White — These items are OK 


Host Monitor 

10.3 Monitor History 

The Ensemble Host Monitor allows you to view detailed information about the level of activity, over time, for configuration 

items of a particular type. You can reveal this information in the bottom half of the Host Monitor page as follows: 

• From the [Ensemble] > [Host Monitor] page, click History next to the name of a configuration item. 

• From the [Ensemble] > [Productions] > [Configuration] page, click the configuration item and then click History. 

The Activity History graph is a simple line-chart with two axes as follows: 

• The graph has a vertical axis that represents the number of activities. The vertical axis begins at 0 (zero) at the bottom 

left of the display, and extends up to the top left. 

• The graph has a horizontal axis that represents time. The horizontal axis begins at 0 (zero) at the bottom right of the 

display. The 0 (zero) starting point is the beginning of the time period you select using the Time options at the bottom 

of the graph. 

You can chose 1 hour, 8 hours, 1 day, or 1 week. The default is 1 hour. The horizontal axis extends up to the end of the 

chosen time period at the bottom left of the display. 

Data for the History graph is drawn from the Count field for the configuration item. The Monitor Service archives the Count 

field for each item every 5 seconds. 

When you request a History graph, the Host Monitor page displays this data for the chosen item, distributed over the chosen 

period of time. At left is a list of items in the Host Monitor page, highlighting the name of the item you are currently 

viewing. You can click on a different item in this list to view its History graph. 

The Ensemble Host Monitor shows the information for the running production in your chosen namespace. If for any reason 

you restart the Ensemble instance containing the production, you lose all previous data and the history starts over. 


11 

Queues 

The [Ensemble] > [Queues] page allows you to monitor the activities of Ensemble message queues in detail. To display this 

page, click Queues in the Ensemble Management Portal main menu. 

There is no menu on the Queues page. You can return to the home page by clicking [Ensemble] in the title bar navigation 

path. 




Under the Queues page title bar is a table called Current Ensemble Message Queues. Each row of the table lists one of the 

message queues being used by the currently running Ensemble production. Each row has the following columns: 

• Name — The name of the configuration item that has the queue. This is the name assigned to the business service, 

business process, or business operation using the configuration display on the [Ensemble] > [Productions] page. It may 

be different from the host class name. 

• Count — How many messages are on the queue. This value is a snapshot and may change when you refresh the page. 

• Created — The date and time when the queue was first created. 

To the right of each row in the Queues table is a Contents command that you can click to display detailed information about 

the messages on the queue. The Contents command displays only if the number of messages waiting on that queue is greater 

than 0. 

In each row, the background color indicates the Count of messages on the queue: 

• Red — More than 10 messages. 

• Orange — From 4–9 messages. 

• Pink — From 1–3 messages. 

• White or pale blue, in alternating rows — There are no messages on these queues. 

11.1 Queue Contents 

The [Ensemble] > [Queues] > [Contents] page displays a list of messages that are currently waiting on a specific queue. To 

display this page, click Contents next to the name of a queue in the [Ensemble] > [Queues] page. 


Queues 

There is no menu on the Queue Contents page. You can return to the Ensemble home page by clicking [Ensemble] in the 

title bar navigation path. 

Under the Queue Contents page title bar are two display areas, one above the other. The top display lists messages. The 

bottom display provides detailed information about the message that is currently selected in the list. If nothing is selected, 

the bottom display is empty. You can drag the boundary between the displays to resize them as needed. In some cases you 

must use the scroll bars to see the full contents of either display. 

In the top display is a table called Message Queue Contents. Each row of the table lists one of the messages currently 

waiting on the queue that you selected in the [Ensemble] > [Queues] page. Each row of the table has the following columns: 






• Index — This integer value starts at 1 for the first message placed on the queue after the production starts, and increments 

by 1 for each successive message. A message has the same Index value for the entire time it is on the queue. Index 

values are never reused. 

• MessageId — The object identifier for the message. 

In each row, the background color indicates the message’s overall status, as follows: 

• Red — The message encountered an Error. 

• Orange — The message is Queued. 

• Green — The message marks the start of a session. 

• Silver — The message arrived after a timeout expired. It has been marked as Discarded. 

• Orange — The message is Suspended. 

• White or pale blue, in alternating rows — These messages are OK. 

To the right of each row in the Queue Contents table are two commands: 

• Details — Click this command to display detailed information about the message in that row. 

• Abort — Click this command to abandon any ongoing attempts to send the message. 

At the top of the display is an Abort All command. If clicked, a confirmation dialog displays. If you confirm the operation, 

all queued messages shown on this page are deleted, and the display returns to the [Ensemble] > [Queues] page. 

11.2 Message Details 

If you select a message in the [Ensemble] > [Queues] > [Contents] page and request further details, message details display 

in the bottom half of the screen. Message details provide full information about every data field in the currently selected 

message. 

Two tables display the contents of the message header and message body, left and right respectively. 

On the left is the Message Header, which displays the entire contents of the message header. Fields include: 

• — The object identifier for the message header. Whenever a message header and message body are combined 

together as a message, the ObjectId value in the header is used to identify the combined message object. As a result, 


Message Details 

this value is the same as the message ID listed in the [Ensemble] > [Messages] page and other pages in the Ensemble 


• Type — The message type, Request or Response. 






• Invocation — The style of invocation for message: Queue or Inproc. 

Inproc means the message will be formulated, sent, and delivered in the same job in which it was created. The job will 

not be released to the sender’s pool until the message is delivered to the target. 

Queue means the message is created in one job, then placed on a queue, at which time the original job is released. 

Later, when the message is processed, a different job will be allocated for the task. 

• TimeCreated — A Queue message lists the time the message was placed on the queue. An Inproc message lists the 

time the Send method was called. 

• TimeProcessed — A Queue message lists the time the message was taken off the queue to be processed. An Inproc 

message lists when processing of the message began; for Inproc messages, TimeProcessed will be very close to Time- 

Created. 

• Status — Indicates the status of the message within its normal life-cycle: Created, Queued, Delivered, Deferred, 












• IsError — An integer value of 1 means that IsError is true; the message encountered an error. A value of 0 means 

IsError is false; the message did not encounter any errors. 

• ErrorStatus — If IsError is 1, then this is the text associated with the error. When IsError is 0, ErrorStatus is the string 

“OK”. 

• CorrespondingMessageId — If the message Type is a Response, this field contains the ObjectId of the corresponding 

request. If the message Type is a Request, this field contains the ObjectId of the corresponding response (if any) or it 

is blank. 

• SessionId — The unique identifier for the session that is (or was) associated with this message. A session marks the 


request message has an ID value that is identical to the SessionId. Several additional messages may be instantiated 

within Ensemble during the session, in order to fulfill the primary request. All of these messages share the same SessionId, 

but each has a different ID value. 

• SourceConfigName — The name of the configuration item that sent the message. 

• TargetConfigName — The name of the configuration item that was intended to receive the message. 


Queues 

• SourceBusinessType — BusinessService, BusinessProcess, BusinessOperation, or Unknown. 

• TargetBusinessType — BusinessService, BusinessProcess, BusinessOperation, or Unknown. 

• BusinessProcessId — Every business process that gets executed has an instance and this is the object ID of that instance. 

If the message is a request, this field identifies the business process in whose context the message was created (sender). 

If the message is a response, this field identifies the business process to which it is being returned (receiver). This field 

is empty in various circumstances, for example if an error occurred. 

• TargetQueueName — The destination “address” for the message: Where is it going The TargetQueueName may be a 

name or a number. A name identifies a public queue, such as Ens.Actor. A number is the job ID associated with the 

private queue of a business host. 

• ReturnQueueName — The return “address” for the message: Where did it come from The ReturnQueueName may be 

a name or a number. A name identifies a public queue, such as Ens.Actor. A number is the job ID associated with the 

private queue of a business host. The ReturnQueueId value is listed even if there is no response expected or needed for 

a particular request message type. 

• MessageBodyClassName — The class name for the message body. 

• MessageBodyId — The object identifier for the message body. This field matches the field in the Message 

Body table. 

On the right side of the message details display is the Message Body information. Fields include: 

• Message Body: Message Type — The message body class name. 

• If the message body is: 

– A standard Ensemble message body object, a table displays the following information: 

• — The object identifier for the message body. This field matches the MessageBodyId field in the 

Message Header table. 

• The name and value of each property in the Message Type class. 

– Any other type, there are no additional fields in the Message Body display. 

• Contents — Click this command to view the message body contents in an appropriate format. 

After viewing message details from the [Ensemble] > [Queues] > [Contents] page, you can: 

• Find another message in the list. Click Details to study it. 

• Close the [Ensemble] > [Queues] > [Contents] page and return to the [Ensemble] > [Queues] page, by clicking your 

browser’s Back command one or more times. 

• Return to the home page, by clicking [Ensemble] in the navigation path. 


12 

Maintenance 

The [Ensemble] > [Maintenance] page allows you to select cleanup operations such as resending suspended messages or 

purging outdated records from the persistent store. You can also indicate production configuration default settings, set user 

credentials for remote connections, and configure an automatic startup for a specific production. Click Maintenance on the 

Ensemble menu to navigate to the page. 

At far right, the title bar provides a Namespace list that you can use to switch to a different Ensemble namespace and return 

to the Ensemble home page. 

Under the Maintenance page title bar is a display area. The Maintenance menu displays at the top left corner of this display. 

You can click on selections in this menu to navigate to portal pages to perform the functions as described in the following 

table. 

Menu item 

Home 

Suspended Messages 

Purge Management Data 

Credentials 

Local Archive Manager 


DICOM Settings 

Default Settings 

Enterprise Message Bank 

Function 

Return to the [Ensemble] home page. 

View all messages that are in a Suspended state. 

Purge entries from the event log, rule log, message warehouse, business process 

archives, and business rule log. 

Create a table of usernames and passwords that business operations can use 

to establish remote connections. 

Periodically save older messages to a separate archive for long term storage. 

Create and configure data tables to support the Lookup and Exists utility functions. 

Create and manage associations between modalities and an Ensemble 

namespace for use in productions. See the “DICOM Associations in Ensemble” 

chapter in the Ensemble DICOM Development Guide for details 

Create and edit default values for production and business host configuration 

settings for a namespace. 

Monitor messages from multiple productions on multiple machines from a central 

location. 

The Maintenance page display area provides the following information and options: 

• Current Ensemble Version — The InterSystems release number associated with the Ensemble software that is installed 

on this machine. 

• Auto-Refresh Rate — This is a number of elapsed seconds, after which the Ensemble Management Portal will refresh 

the portal page you are currently viewing. The default duration is 23 seconds. 


Maintenance 

A refresh operation as frequent as every 5 seconds might be helpful or distracting, depending on how you are using 

the portal. To change the rate, enter a new value in this field. If you never want an automatic refresh to occur, set the 

value to 0 (zero). 

• Auto-Start Production — You can configure Ensemble so that a specific production starts automatically at system 

startup, and stops automatically at system shutdown. In the Production list, click a production name. To disable automatic 

production start, click the blank entry; this is the default. 

For more details, see the Production Life Cycle section of the “Production Concepts” chapter of Developing Ensemble 

Productions. 

When you are finished making changes in the Maintenance page, click Save to apply the changes. 

12.1 Suspended Messages 

The [Ensemble] > [Maintenance] > [Suspended] page allows you to study and resubmit messages that have entered a suspended 

state. Some business operations are designed to set the status of any failed messages to suspended. Alternatively, you can 

suspend a message from the Instances display on the [Ensemble] > [Host Monitor] page. 

In either case, such a message goes on a special queue where Ensemble keeps all suspended messages. You can use the 

Suspended Messages page to find and examine these messages. An inspection of the routing information or contents of a 

specific message might reveal the reason why the message failed. For example, if the problem is that an external destination 

went out of service, you can make a change to reestablish communication with that server. Then you can resubmit the 

suspended messages to the external server from this page. 

You can display the Suspended Messages page by clicking Maintenance on the Ensemble menu and then clicking Suspended 

Messages from the Maintenance menu. 

If some messages in the currently running production are suspended, the page lists them. If no messages are suspended, 

the list is empty. The list displays message information as described in the following table. 

Column 

Check box 

# 

ID 

Time Created 

Session 

Error 

Source 

Target 

Description 

Mechanism for selecting messages for the Resubmit, Edit & Resubmit, Discard, and Delete 

commands. 

An incremental count of the number of entries in the table. 

The unique identifier for the instantiated message. 

The date and time when this message was instantiated. 

The unique identifier of the session to which this message belongs. A session marks the 

beginning and end of all the activities prompted by a primary request message from outside 

Ensemble. 

A quick overview of the results returned by the message to the configuration item that sent 

it, the Error field can have the values OK, Error, Retry, or Inactive. OK means normal behavior; 

Retry means the message experienced a failure but the item that sent it is configured to retry 

the failed message. Error means an error was reported somewhere in the activity. Inactive 

means that the item that sent the message has been idle for longer than its Inactivity Timeout 

setting, and may require diagnostic action. 

The name of the configuration item that sent the message. 

The name of the configuration item that is the intended recipient of the message. 


Purge Management Data 

To the right of each row are two commands which you can click to display additional message information: 

• Click Details to display the message details in the lower portion of the page. 

• Click Trace to display a visual trace of the path of the message object through the production on the Ensemble Visual 

Trace page. 

Above the list of suspended messages is a choice of commands to perform on these messages: 

• Resubmit — Select one or more check boxes in the column at the left of each message you want to resubmit and click 

to resubmit the messages. As message similar to the following displays for each successfully resubmitted message: 

Resubmit suspended message ID '7' completed. 

Any message that you resubmit retains the same Session identifier and transmits the same Header object. The 

description in the message header contains text indicating this is a Resubmitted message. 

• Edit & Resubmit — Edit a single message before resubmitting; this command is only valid if you select exactly one 

message. See the Resend Editor for Resubmitting Messages section for details. 

• Discard — Remove the message from list on the Suspended Messages page. The message is still accessible from the 

Ensemble Message Browser. 

• Delete — Remove all record of the message from the Ensemble database. 

CAUTION: 

You cannot undo the Discard or Delete operations. 

12.1.1 Resend Editor for Resubmitting Messages 

When you select one message to resubmit from the [Ensemble] > [Maintenance] > [Suspended] page, you have the option 

to edit the body of the message before resubmitting it. 

1. Click Edit & Resubmit to display the Ensemble Resend Editor page. 

2. Use the entry fields to update the message body data. The fields vary depending on the method signature of the message. 

If the method has no properties, none are displayed. 

If you are editing a virtual document message (HL7, X12), you can edit data in the message content and also edit object 

properties in the box below the content box. 

3. Click Resubmit to resubmit the original message header with your edited message body contents to the target. 

4. After a successful resubmit, the page refreshes with text indicating the Header and Msg Body identifiers. Click Trace 

to see the visual trace of the resubmitted message. 

Any message that you edit and resubmit retains the same Session identifier and transmits the same Header object, but it 

contains an updated Msg Body object with a new identifier. The description in the original message header contains text 

indicating that this message has been resubmitted and includes the original Msg Body object identifier. 

12.2 Purge Management Data 

The [Ensemble] > [Maintenance] > [Purge] page allows you to delete outdated entries from the event log, message warehouse, 

business process archives, and business rule log. You can only purge entries associated with the currently running production. 

You can display the Purge page as follows: 

1. From the Ensemble menu, click Maintenance. 


Maintenance 

2. From the Maintenance menu click Purge Management Data. 

3. The Purge Management Data page displays. 

Under the Purge page title bar is a display area; the Maintenance menu is at the top left corner of this display. Under the 

title bar and to the right of the menu is a row of commands, as follows: 

• Show Event Log displays the [Ensemble] > [Event Log] page. You can use this page to get information about event log 

entries that you might want to purge or avoid purging. 

• Show Messages displays the [Ensemble] > [Messages] page. You can use this page to get information about messages 

that you might want to purge or avoid purging. 

• Show Business Processes displays the [Ensemble] > [Business Processes] page. You can use this page to get information 

about business process instances that you might want to purge or avoid purging. 

• Show Business Rule Log displays the [Ensemble] > [Business Rule Log] page. You can use this page to get information 

about rule log entries that you might want to purge or avoid purging. 

If you click one of these commands to view information, you can return to the Purge page by navigating back to the Purge 

Management Data page described at the beginning of this section or by using the Back command on your browser. 

Below the row of commands on the Purge page is a dialog box that contains the following fields: 

• Type of Record — Identifies the purpose of each row in the table. Each row contains one type of artifact that the currently 

running production is producing on an ongoing basis: Event Log, Messages, Business Processes, Business Rule Log, 

or I/O Archive. 

• Current Count — Total number of entries of this type that are now in the persistent store for this production. Use the 

Current Count to decide whether or not it is worthwhile to purge the records and if so, how many days’ worth of records 

you want to keep. 

• Include message bodies — If selected, this check box indicates that when Ensemble purges message headers, it should 

also purge the associated message bodies. Ensemble verifies that body classes exist and are persistent, before purging 

them. If this check box is clear (the default) message header data is purged, but message body data is retained. 

Important: 

When Ensemble purges a message body object, it does not automatically delete any embedded persistent 

object your code references as a property in your message body class. As a developer, you must 

appropriately handle the deletion of these referenced objects using a mechanism such as a delete trigger, 

a %OnDelete() method, or through relationships. 

• Keep data integrity — If selected (the default) this check box indicates that when Ensemble purges message headers, 

even if a message meets the age criterion for purging, it is not deleted unless its status is complete. Ensemble considers 

messages to be complete if they are marked Complete, Error, Aborted, or Discarded. This is to keep session-level 

integrity. 

The query that identifies the messages to delete checks all the messages (including business process instances) in a 

session to see whether any of them are not complete. The purge only performs the delete if all the messages are complete. 

The scope of this query, therefore, has an impact on the time taken to do the purge. 

This option is important to support long-running business processes. Usually this is the desired behavior. However, if 

you know there are old messages in the system whose incomplete status is not significant, you can purge them by 

clearing the Keep data integrity check box. 

Important: 

The purge criteria for using Keep data integrity also includes Ensemble system processes such as the 

Scheduler. Before clearing this check box, carefully consider the value for the Do not purge most 

recent setting. 


Credentials 

• Do not purge most recent — This tells Ensemble how many days’ worth of records to keep. The number can be 0 

(zero), which keeps nothing and deletes all entries that exist at the time of the purge operation. The default value for 

Do not purge most recent is 7, which keeps entries for the last seven days. 

The count of days includes today, so keeping messages for 1 day keeps the messages generated on the current day, 


At the bottom of the dialog is the Start Purge command. If you click it, Ensemble immediately purges the persistent store 

according to the parameters you have entered in the Purge page. The page uses a background job to do purges, and reports 

the results of the last-run purge, including a status code, or a notice if the background job is running or has failed to run. 

CAUTION: 


12.3 Credentials 

Some remote systems require a username and password to log into that system. A username-and-password pair is a login 

credential. Ensemble permits you to store login credentials in a centralized table that can be viewed and edited only by 

users with access to the Ensemble Management Portal. 

Each entry in the Credentials table has an ID by which you can refer to it when configuring business services or business 

operations for the production. Adding an entry to the Credentials table for a production consists of assigning an ID to a 

username-and-password pair. 

The [Ensemble] > [Maintenance] > [Credentials] page displays the Credentials table for the currently running production. 

You can display the Credentials page as follows: 

1. From the [Ensemble] home page menu, choose Maintenance. 

2. From the Maintenance menu choose Credentials. 

3. The Credentials page displays. 

There is no menu on the Credentials page. Under the title bar is a row of commands, as follows: 

• Home — Click to return to the Ensemble home page. 

• Create New Credentials — If you click this command, a dialog displays in the bottom half of the Credentials page. You 

can enter information in this dialog to create a new entry for the Credentials table. 

Below these commands, the Credentials page displays text — The following Credentials are currently defined — and a table. 

The table lists all the credentials associated with the currently running production. Each row in the table has the following 

columns: 

• ID — The configured name of the username-and-password pair. This is the name to be used when configuring a business 

service or business operation to establish a remote connection. 

• User — The username. 

• Password — The password. 

To the right of each entry in the Credentials page table are two commands: 

• Edit displays a dialog in which you can edit the Username or Password for an entry. You cannot change the ID of an 

entry. To use a different ID, you must create a new entry by clicking Create New Credentials. Then, if you want, you 

can delete the old entry. 


Maintenance 

• Delete deletes the entry in that row. 

CAUTION: 

You cannot undo the Delete operation. 

12.4 Local Archive Manager 

The [Ensemble] > [Maintenance] > [Archive Manager] page allows you to periodically save older messages to a separate 

archive for long term storage. 

The Archive Manager requires you to identify a namespace in which to keep the archive. InterSystems strongly recommends 

that you keep this archive in a namespace that meets both of the following criteria: 

• A separate namespace from those in which you run Ensemble productions. If you are running productions in more 

than one namespace, be aware that multiple namespaces can archive their messages into one shared target namespace. 

• An Ensemble-enabled namespace, so that you can use Ensemble Management Portal features such as the Message 

Browser and Visual Trace whenever you have a reason to examine the archived messages. For details about Ensembleenabled 

namespaces, see “Working with Namespaces” in the chapter “What to Manage.” 

You can display the Archive Manager page as follows: 


2. From the Maintenance menu choose Archive Manager. 

3. The Archive Manager page displays. 

There is no menu on the Archive Manager page. 

At the top of the page is an Run Archive command. This command is enabled only if there is data in all three fields in the 

form and there is no previous archive operation still in progress. 

Next, the page displays text — Current archive manager settings for namespace — and the name of the currently selected 

namespace. The following fields display information about the Archive Manager: 

• Archive to namespace — The namespace to which Ensemble saves archived messages. 

• Archive manager class name — The class that acts as the Archive Manager. Generally you will keep the default of 

Ens.Archive.Manager, but if you wish to customize the archive operation you can subclass Ens.Archive.Manager and 

write your own code. If so, choose your subclass for this field. 

• Number of days before archiving — Messages older than this number of days are automatically archived when you run 

the archive operation. 

To edit any of these settings in this part of the page, click Edit at right. A form displays. Change the information in the 

fields and then click Save. If the save is successful, the page is refreshed with the new settings displayed. If the save failed, 

the form displays the error message from the server. 

The Archive history display provides information about the last or current archive. For example: 

Archive start time 2008-06-04 16:52:55 

Archive stop time 2008-06-04 16:52:55 

Total messages processed 3002 - 100% finished 

Total messages archived 0 

Total message headers deleted 0 

Total message bodies deleted 0 

Archive status idle 



When the Run Archive command is enabled, and you click it, a confirmation dialog asks if you want to begin the archive 

operation. Click OK if you want to begin; a message displays to confirm that the archive has been started. If not, click 

Cancel. 

CAUTION: 

You cannot stop the Run Archive operation. 

After you click Run Archive, the archive operation runs in the background and displays progress statistics while it is running. 

The numbers in the display update continuously, with count and percentage continuing to change until the result reaches 

100%, status becomes idle, and a final stop time appears: 

Archive start time: 2008-05-14 18:19:02 

Archive stop time: 

Total messages processed 100 - 10% finished 

Total messages archived 3 

Total message headers deleted 1 

Total message bodies deleted 1 

Archive status running 

For each message to be archived, Ensemble: 

• Copies the message header to the target namespace. 

• Copies the serialized message body (not the message body object) to the target namespace. 

• Deletes the message header and message body objects from the original namespace. 

If errors occur during the archive operation, you will see the following display. 

Total number of errors XX [show error log] 

[show error log] is a link that toggles with [hide error log]. You can click this link to show or hide the error log. The maximum 

number of errors displayed in the table is 1000. 

Each time you run an archive operation, the previous archive error log is deleted. 

12.5 Lookup Settings 

The [Ensemble] > [Maintenance] > [Lookup Settings] page allows you to create and configure data tables to support the 

Lookup and Exists utility functions. The Lookup utility function is provided so that you can easily perform a table lookup 

from a business rule or DTL data transformation. 

For details, see the sections “Utility Functions” and “Lookup Tables” in the “Creating a New Production” chapter of 

Developing Ensemble Productions. 

The Lookup function works only after you have created a lookup table and have populated it with data. You can do this 

using the [Ensemble] > [Maintenance] > [Lookup Settings] page. You can display the page as follows: 


2. From the Maintenance menu choose Lookup Settings. 

3. The Lookup Settings page displays. 

There is no menu on the Lookup Settings page. 

At the top of the page is an Add New Table command. When you click this command, the page refreshes with the cursor in 

the Lookup Table field and hint text below each of the three fields for entering a key: Lookup Table, Key, and Value. 

Next, the page displays text — View and edit Ensemble lookup tables for namespace — and the name of the currently 

selected namespace. Below the introductory text is a list of lookup tables in the namespace. 


Maintenance 

To create a new table, type the new table name in the Lookup Table field. Provide the first entry in the table by entering a 

Key, with or without a Value. Click Insert to save your changes. Continue adding Key and Value pairs as needed to populate 

the table. After the first Insert, your table becomes available as a choice in the list at the top of the form. If you ever click 

the Insert command while the required fields Lookup Table and Key are empty, the hint text changes color to indicate an 

error. 

When you select a table from the list, its full set of Key and Value pairs display in a grid below. Each row in the grid offers 

Edit and Delete commands that apply to the Key listed in that row. Click Edit to edit the value of a key. If you make any 

changes, click Insert to save them. 

A Delete Table command is available at the bottom of the Lookup Settings form. If you click this command while a specific 

lookup table is selected, a confirmation dialog displays, asking if you want to delete all keys for that table. Click OK to 

delete the table and all of its keys; click Cancel to continue without deleting anything. 

CAUTION: 

You cannot undo the Delete Table operation. 

12.6 Default Settings 

The [Ensemble] > [Maintenance] > [Default Settings] page allows you to create and edit default values for production and 

business host configuration settings by namespace. The following table describes the properties listed on the page for each 

existing default setting. 

Table 12–1: Default Setting Properties 

Column 

Production Name 

Item Name 

Host Class Name 

Setting Name 

Setting Value 

Edit 

Delete 

Description 

Name of the production within the current namespace to which this setting applies; an 

* indicates in all productions. 

Name of the configuration item; an * indicates for all items. 

Name of the host class; an * indicates for all classes. 

Name of the configuration setting. 

Default value of the setting. 

Click to edit the default setting properties on the Edit Default Setting page. 

Click to delete this default setting from the namespace. Click OK to confirm the delete 

action. 

When you click Edit or Create New Setting at the top of the page you navigate to a form to enter the following values: 

• Production Name (required) — Choose from the list of existing production definitions in the namespace or enter a 

production name where the default setting should be used. Use * to use the setting in all productions. 

• Item Name (required)— Enter the name of the configuration item that should use the default setting. Use * to use the 

value in all configuration items with the setting. 

• Host Class Name (required) — Enter the class name of the business service, process, or operation that should use the 

default setting. Use * to match all classes. 

• Setting Name (required) — Enter the name of the default setting. 

• Setting Value — Enter the value for the default setting. 

• Description — Enter an optional description for your default setting. 



Click Save to update or create the default setting and return to the updated list on the Default Settings page. Click Cancel 

to return to the Default Settings page without saving any of your edits. 

See the entry for Ens.Config.DefaultSettings in the Class Reference for programming details. 

12.7 Enterprise Message Bank 

The Enterprise Message Bank is a remote archiving facility where you can collect messages, event log items, and search 

table entries from multiple Ensemble client productions. It is made up of the following components: 

• A client operation you add to an Ensemble production and configure with the address of a Message Bank server. 

• The Message Bank server which is a simple Ensemble production consisting exclusively of a Message Bank service 

that listens for submissions from any number of client productions. 

The Message Bank is part of the Enterprise Monitor. You access it using the Enterprise Message Bank option on the 

[Ensemble] > [Maintenance] menu of the Ensemble Management Portal. The Ensemble Enterprise Monitor also provides 

pages for you to monitor the status of client productions, browse the message bank, and perform a search of HL7 messages 

from the monitored clients. You can also access the Enterprise Monitor directly using the following default URI: 

http://localhost:57772/csp/ensemble/Ens.Enterprise.Portal.MonitorStatus.cls 

To use the Message Bank facility, perform the following steps: 

1. Message Bank Server — Set up the Message Bank in one Ensemble-enabled namespace by subclassing the 

Ens.Enterprise.MsgBank.Production abstract class, copying its ProductionDefinition XData block, and then 

compiling your new class in that namespace. For example: 

Class MyEnsemble.MyMessageBank Extends Ens.Enterprise.MsgBank.Production 

{ 

XData ProductionDefinition 

{ 

 

Production for receiving and collating message bank submissions from one or more 

client 

Ensemble namespaces and for maintaining a local repository of production status information 

about each 

client namespace, for display on the Enterprise Monitor page. Open the the Monitor page on the 

same 

machine that that is hosting this Production. 

0 

120 

10 

 

0 

0 

0 

10 

 

 

0 

0 

0 

Big 

0 

1 

 

100 

5 

9192 


Maintenance 

-1 

10 

 

 

 

} 

} 

This is the production for receiving and collating message bank submissions from one or more client Ensemble 

namespaces and for maintaining a local repository of production status information about each client namespace. You 

can view the gathered information on the Enterprise Monitor page on the same machine that is hosting this production. 

For testing purposes, you can put the message bank production on the same machine and instance as your regular 

productions, but it should be in a separate namespace from any production you plan to monitor. The Message Bank 

production uses the following services: 

• Ens.Enterprise.MsgBank.TCPService — to accept inbound data from the client productions 

• Ens.Enterprise.MonitorService — to gather status of client productions 

2. Message Clients — In each regular production for which you want to collect messages, add a new business operation 

using the Ens.Enterprise.MsgBankOperation class. This operation and its configuration control archiving of events via 

TCP to a near real-time Ensemble server running the Message Bank production. See Adding a Message Bank Business 

Operation for the detailed procedure. 

3. Navigate to the [Ensemble] > [Maintenance] > [Enterprise Message Bank] page to view the collected messages in the 

message bank. The first time you enter the Enterprise Message Bank page from the Maintenance menu, it requires you 

to enter the following information about the Message Bank: 

• Enterprise Message Bank Webserver IP Address 

• Enterprise Message Bank Webserver IP Port number 

• Enterprise Message Bank Webserver execution Namespace 

• Use SSL to connect to the Enterprise Message Bank Webserver 

Ensemble caches the information and does not display it again unless you clear this cache by performing a Kill on the 

Êns.MsgBank global. 

4. Once you enter the proper information, you see the Ensemble Enterprise Monitor: Client Systems List page. From here 

you can click Message Bank Browser to display a list of archived messages. 

Important characteristics of the Message Bank: 

• The Message Bank has no synchronization dependencies for message body classes with the contributing productions; 

therefore, it receives a serialized form of each message. For virtual document message bodies (HL7, for example) it 

reparses the serialized document into an object, and receives and stores the search table entries from the contributing 

production as well. You can perform almost the same search for HL7 messages as on the original machine; however, 

the same is not true for other types of message bodies. 

To search by HL7 custom schema properties in the Message Bank, the custom schema definition must be in the Message 

Bank production namespace. 

• For uniqueness, the Message Bank production prepends the numeric identifier of client productions to the message 

IDs. 

• The Message Bank page also serves as a portal for viewing the state of multiple client productions and for invoking a 

resend service on them. For these extra features to work the Message Bank needs to know the web addresses of the 

client productions. 



• The Message Bank mechanisms do not delete the messages from the originating production, you should handle that 

function with a separate purge process. 

• It is possible to replay messages from the Message Bank back into the originating production or another client production. 

12.7.1 Adding a Message Bank Business Operation 

In each regular production for which you want to collect messages, add a new business operation using the 

Ens.Enterprise.MsgBankOperation class. This operation and its configuration control archiving of events via TCP to a near 

real-time Ensemble server running the Message Bank production. 

You can add a Message Bank business operation to any Ensemble production from the Ensemble Management Portal using 

the following procedure: 

1. Start the Business Operation Wizard from the [Ensemble] > [Productions] > [Configuration] page in one of the following 

ways: 

• Click in the diagram background and then click Add Operation. 

• Right-click in the diagram, point to Add on the context menu, and then click Business Operation. 

2. Click All Operations and then choose the Ens.Enterprise.MsgBankOperation class from the Operation Class list. 

The class already exists and requires no programming. You can see the details of the class in its entry in the Class 

Reference. 

3. You must make the Operation Name of this configuration item the Message Bank operation class name. Either leave 

this blank to use the default class name or enter Ens.Enterprise.MsgBankOperation. 

4. You can configure the optional Display Category and Comment fields later. 

5. Click OK to save your changes and finish the wizard. 

The Message Bank business operation is now part of the production and ready to configure as described in the following 

section. 

12.7.2 Configuring a Message Bank Business Operation 

You can configure a Message Bank business operation by clicking it in the diagram on the [Ensemble] > [Productions] > 

[Configuration] page. The following settings display below the diagram; you can edit these values to configure the business 

operation. When you are finished editing, click Apply to save your changes, or Cancel to ignore them. 

• General Settings — The general settings on the left configure the business operation as a production item. These settings 

are common to all business hosts. For descriptions, see the General Settings section in the “Configuration” chapter 

of Managing Ensemble Productions. 

Important: 

Verify that the Name setting value is Ens.Enterprise.MsgBankOperation. This is a requirement 

for running an Ensemble Message Bank operation. 

• Specific Settings — The specific settings on the right configure properties particular to this business operation and its 

associated adapter. 

The setting names are, in many cases, localized descriptions of the class property names. You can hover the cursor over 

any setting name to display its help text as it appears in the Class Reference or click the setting name to display the help 

text in a separate pop-up window. 

Configure the following settings specifically for the Message Bank: 


Maintenance 

Adapter Class 

Archive Items 

Verify that this read-only setting lists the client adapter Ens.Enterprise.MsgBank.ClientTCPAdapter class. 

Controls which messages to send to the Message Bank. The default behavior is to archive everything except 

scheduler messages as shown by the value: 

*[*],-Ens.ScheduleService[*],-Ens.ScheduleHandler[*] 

See Configure Archive Items for details. 

Enable Archiving 

Set to True. This starts messages queuing from all configuration items in the client production. Note that this 

queueing continues even if you disable the operation and while it is not able to connect to the Message Bank. The 

operation forwards any queued messages to the Message Bank server whenever it is enabled. 

If set to False, the operation does not queue any messages for the Message Bank. 

Event Log Interval 

How frequently should we check for conforming Event Log events that may need to be forwarded to the Message 

Bank server. 0 means check only when messages are being forwarded. 

Force Keepalives 

IP Address 

Port 

If set to True, send empty event submissions periodically if no conforming events need to be submitted. 

IP address of the Message Bank production. 

TCP port number for the Message Bank production input service (9192 is the default). 

The remaining entries in the Specific Settings column are determined by the more general business operation, business 

host, and TCP adapter classes from which this class inherits. See the following appropriate references for details on these 

adapter settings: 

• Configure Business Host Settings in the “Configuration” chapter. 

• Business Operation Settings in the “Configuration” chapter. 

• Adapter Settings in the “TCP Outbound Adapter” chapter of Using TCP Adapters with Ensemble. 

After configuring these settings, your production becomes a client of the Message Bank. Enable this business operation to 

see it connect to the Message Bank. 

12.7.2.1 Configure Archive Items 

This setting controls which messages the production sends to the message bank. It is a comma-separated list of configuration 

names of items whose messages are to be archived to the Message Bank server. 

Archive log events for each item using the following colon-separated syntax: 

item[evtype1:evtype2:Trace_cat] 

Within the event type brackets, you can use the following characters in your selection list: 



Pattern 

character 

* 

- 

! 

$ 

- 

_ 

Placement 

at the front of an item 

at the end of an item 



for events of type Trace 

Resulting action 

include all event types 

exclude the type from archiving entirely 

exclude message bodies from archiving 

exclude search table entries from archiving 

exclude message headers from archiving 

optionally used to select a particular category of trace event. 

Event type Trace without a suffix means Trace events of all 

categories. 

For example: 

• *[*] — Archive everything 

• *$[*],Ens.Alert![-*] — Archive all events, headers, and bodies but not SearchTable entries; but do not archive 

bodies or events from item Ens.Alert. 

Note: 

Ensemble only archives trace events if it has logged them. You can only use these settings to restrict which logged 

events get archived, not to archive any events that you did not configure to be logged. 


13 


The Ensemble Testing Service allows you to test a business process or business operation of a running Ensemble production 

in the active namespace. You can navigate to the Testing Service from the following locations in the Ensemble Management 

Portal: 

• From the Ensemble menu, click Testing Service. 

• From the Ensemble Configuration display on the [Ensemble] > [Productions] page, click a business process or business 

operation in the top pane and click Test in the bottom pane. This brings you to the second page of the testing service 

with the business host preselected. 

The Testing Service offers a series of pages that enable you to formulate and send test messages through your production: 

• Testing Service - 1 of 4, Select Target 

• Testing Service - 2 of 4, Select Message Type 

• Testing Service - 3 of 4, Submit Test Data 

• Testing Service - 4 of 4, View Results 

Throughout the process you can use the following commands that appear at the bottom of the page: 

• Click Back to return to the previous Testing Service page (unavailable on the first Testing Service page). 

• Click Next to continue with the next testing service page (does not appear on the last two Testing Service pages). 

• Click Cancel to return to the [Ensemble] home page (does not appear on the last page). 

13.1 Testing Service - 1 of 4, Select Target 

The first page of the Ensemble Testing Service provides a greeting and the name of the currently running production. The 

Testing Service requires that the production you want to test is running and has testing enabled. 

Ensure the Production is Running 

If the production you want to test is not the one indicated as the current production or there is no production running, perform 

the following procedure: 

1. From the Ensemble menu, click Productions to display the [Ensemble] > [Productions] page. 

2. Stop the running production (if any) and Start the one you want to test. 

3. From the Ensemble menu, click Testing Service to display the first testing service page. 



Enable Testing 

If testing is disabled for the running production, the first Testing Service page notifies you. Click the link to the Production 

Configuration page, or click Productions from the Ensemble menu to enable testing for this production: 

1. On the [Ensemble] > [Productions] page, click Configure next to the production you are testing. 

2. Under the Production Settings column at the bottom left of the page, select the Testing Enabled check box, click Apply 

and then OK. 

3. From the Ensemble menu, click Testing Service to display the first testing service page. 

Select Testing Target 

From the first page of the Testing Service, choose the testing target: 

1. When testing is enabled, this page offers options that let you select either a Business Process or Business Operation 

as the target of your testing. Choose one, then select the appropriate business host from the list to the right of your 

selection. 

2. Click Next to continue testing and move to page two of the Testing Service. 

13.2 Testing Service - 2 of 4, Select Message Type 

The second Testing Service page allows you to choose the message type you want to send. It displays the following fields: 

• Current Production — The name of the currently running production (view-only). 

• Target — The business process or business operation that you selected in the previous Testing Service page (viewonly). 

• Request Type — Select from a list of request messages. Only the request types that are valid for the Target are listed, 

including subclasses of supported types. 

Click Next to continue testing and move to page three of the Testing Service. 

13.3 Testing Service - 3 of 4, Submit Test Data 

The third Testing Service page provides data fields that you can use to set properties for the specific request. The fields 

vary depending on the method signature of the request. If the method has no properties, none are displayed. 

If you are testing a virtual document message (HL7, X12), there is a free-form box where you can paste test message content. 

Below this box you can enter object properties for the message. 

Click Invoke to submit the request with the values you entered and move to page four of the Testing Service. 

13.4 Testing Service - 4 of 4, View Results 

If time elapses while the Testing Service attempts the request, a Waiting page displays the following view-only information: 

• Target — The session ID associated with the request. 


Testing Service - 4 of 4, View Results 

• Request Type — The request type of the selected target. 

• Session Id — The session ID associated with the request. 

• Request Sent — The date and time when the request was sent. 

• Response received — The status Waiting and a graphical progress bar, indicating that work is being done. 

Finally, the Results page displays any output values from the response generated by your request, including any errors with 

the full error message text. 

You can perform one of the following commands when the test completes: 

• Click Done to return to the Ensemble home page. 

• Click Trace to navigate to the Visual Trace page to visually follow the path of the message through the production. 


14 

EDI / HL7 Manager 

The [Ensemble] > [EDI and HL7 Manager] page allows you to view and transform Electronic Data Interchange (EDI) messages 

to determine how you want your Ensemble production to handle them. To display the page, click EDI / HL7 Manager in the 

Ensemble menu. 

Under the title bar is a display area with a table of links. Each row in the table corresponds to a family of Electronic Data 

Interchange (EDI) document types. The available links are: 

• ASC X12 — Display the Web site for the Accredited Standards Committee (ASC) X12, founded by the American 

National Standards Institute (ANSI) as a cross-industry forum to build and support electronic data exchange standards, 

related documents and products intended for worldwide use. The URI is http://www.x12.org/ 

For details about X12, see the “Viewing and Transforming Documents” chapter in the Ensemble X12 Development 

Guide. 

• ASTM — Display the Web site for ASTM International Standards Worldwide. The URI is http://www.astm.org/. 

For details, see the “Viewing and Transforming Documents” chapter in the Ensemble ASTM Development Guide. 

• HL7 Version 2 — Display the Web site for the American National Standards Institute (ANSI) standards developing 

organization Health Level Seven (HL7). The URI is http://www.hl7.org/ 

For details about HL7 Version 2, see the “Viewing and Transforming Messages” chapter in the Ensemble HL7 Version 

2 Development Guide. 

• UN/EDIFACT — Display the Web site for United Nations Directories for Electronic Data Interchange for Administration, 

Commerce and Transport. The URI is http://www.unece.org/trade/untdid/welcome.htm 

For details, see the “Viewing and Transforming Documents” chapter in the Ensemble EDIFACT Development Guide. 

Each choice has a link for Schema Structures and a Document or Message Viewer. 

14.1 Schema Structures 

• ASC X12 — Displays a list of the supported X12 schema specifications. You can click on any link in the display to 

drill down for details. 

• ASTM — Displays a list of the supported ASTM schema specifications. You can click on any link in the display to 

drill down for details. 

• HL7 Version 2 — Displays a list of the supported HL7 Version 2.x schema specifications. You can click on any link 

in the display to drill down for details. 


EDI / HL7 Manager 

• UN/EDIFACT — Displays a list of the supported EDIFACT schema categories and implementation guides and the 

transaction set implementation names they define. You can import schema categories from SEF and XML files. 

14.2 Document/Message Viewer 

When you click Document Viewer or Message Viewer next to one of the EDI document types, the [Ensemble] > [EDI and 

HL7 Manager] > [EDI Document Viewer] page displays with the following specific information depending on the type: 

• ASC X12 — Options on this page allow you to retrieve X12 message data from external files or the Ensemble message 

archives to preview the results of applying various parsing schemes or data transformations to the message data. 

• ASTM — Options on this page allow you to retrieve ASTM message data from external files or the Ensemble message 

archives to preview the results of applying various parsing schemes or data transformations to the message data. 

• HL7 Version 2 — Options on this page allow you to retrieve HL7 message data from external files or the Ensemble 

message archives to preview the results of applying various parsing schemes or data transformations to the message 

data 

• UN/EDIFACT — Options on this page allow you to retrieve EDIFACT message data from external files or the Ensemble 

message archives to preview the results of applying various parsing schemes or data transformations to the message 

data. 


Index 

A 

actor pool 

and jobs, 35 

and queues, 38 

size of, 52, 57, 59, 60 

Actor Pool Size field, 52 

Adapter Class field, 60, 61 

adapters 

inbound, 59 

outbound, 61 

adding 

business operations, 52 

business processes, 52 

business rules, 33 

business services, 52 

items to a production, 16 

login credentials, 107 

portal user accounts, 5 

Alert Grace Period field, 60 

Alert log entry type, 67 

Alert On Error field, 58 

Alert Retry Grace Period field, 61, 62 

Archive IO field, 58 

Archive Manager page, 108 

archives 

see log entries 

Assert log entry type, 67 

Auto-Start Production field, 104 

B 

BPL Viewer page, 88 

browsers, Web, 3 

business activity monitoring, 29 

business hosts 

configuring, 54 

scheduling start and stop, 56 

Business Host Settings 

Alert On Error, 58 

Archive IO, 58 

Category, 56 

Change Class, 55 

Class, 56 

Comment, 56 

Enabled, 57 

Foreground, 57 

Inactivity Timeout, 57 

Log Trace Events, 57 

Name, 56 

Pool Size, 57 

business metrics, 24 

and dashboards, 29 

viewing properties, 31 

Business Metrics page, 31 


adding, 52 


Error, 96 

host class, 23 

Inactive, 96 

in productions, 25, 46 

listing instantiated objects, 95 

monitoring, 95 

OK, 96 

production diagram, 46 

Retry, 96 

status of, 96 

BusinessOperation Settings 

Reply Code Actions, 62 

Business Operation Settings 

Adapter Class, 61 

Alert Retry Grace Period, 62 

Credentials, 62 

Failure Timeout, 62 

Retry Interval, 62 


adding, 52 

BPL diagram, 88 


Error, 96 


Inactive, 96 


instances, 91 


monitoring, 91, 95 

OK, 96 


Retry, 96 

status of, 96 

viewing a list of, 87 

Business Processes page, 87 

BPL Viewer, 88 

color indicators on, 92 

Definition, 88 

Instances, 91 

SessionId, 76 

Business Process Instance page 

Purge, 93 

Business Process Instances page, 91 

Business Process Settings 

Alert Retry Grace Period, 61 

Enabled field, 60 

Failure Timeout, 61 

Pool Size, 60 

Reply Code Actions, 61 

Retry Interval, 61 

Business Rule Editor page 

Rule List, 33 

Business Rule Log page 

Filter Rule Log, 93 

SessionId, 76 


usiness rules, 32 

adding, 33 

list of rule definitions, 33 

Business Rules page, 33 


adding, 52 


Error, 96 


Inactive, 96 




OK, 96 


Retry, 96 

status of, 96 

Business Service Settings 

Adapter Class, 60 

Alert Grace Period, 60 

Call Interval, 60 

Class, 56 


Enabled, 57 

Pool Size, 59 

C 

Call Interval field, 29, 60 

Category field, 56 

Change Class command, 55 

classes 

see host classes 

Class field, 56, 56 

color 

in XML syntax displays, 75, 92 

color as a status indicator 


Configuration page, 50 

Event Log page, 68 

Host Monitor page, 96, 97 

Jobs page, 36 

Message Browser page, 80 

Queues page, 99, 100 

System Monitor page, 65 

Comment field, 56 

Compare Messages, 75 

Completed status, 37 

configuration items, 23 


Add Operation, 52 

Add Process, 52 

Add Service, 52 

BPL Definition, 88 

Business Host Settings, 54 

Business Operations, 46 

Business Operation Settings, 61 

Business Processes, 46 

Business Process Settings, 60 

Business Services, 46 

Business Service Settings, 59 

Production Settings, 51 

Specific Settings, 59, 61 

Start Production, 42 

Stop Production, 43 


business hosts, 54 



business rules, 33 


inbound adapters, 59 


outbound adapters, 61 

productions, 51 

remote connections, 107 

workflow, 40 

Created status, 37 

credentials, login, 29 


for inbound adapters, 60 

for outbound adapters, 62 


Credentials field, 60, 62 

Credentials page, 107 

ID, 107 

Password, 107 

Username, 107 

D 

Dashboard page, 30 

View, 30 

dashboards, 29 

viewing a list, 30 

viewing individually, 30 

Default Settings page, 110 

Deferred status, 37 

Delivered status, 37 

Dequeuing status, 36 

diagnostics 

see testing 

diagrams 

BPL business process, 88 

production, 45 

Discarded status, 37 

documentation 


E 

Enabled field, 57, 57, 60 

Ens.Actor, 36, 38, 60, 74, 102 

Ens.BusinessOperation, 23 

Ens.BusinessProcess, 23 

Ens.BusinessService, 22 

Ens.Host, 22 

Ens.Item, 23 

Ens.Request, 36 

Ens.Response, 36 

Ensemble Management Portal, 3 

commands, 10 

items to manage, 21 



starting, 4 

tasks to perform, 15 

Ensemble version, 103 

Enterprise Message Bank page, 111 

errors 

Error log entry type, 67 

Error status, 36, 96 

IsError status, 74, 101 

Log Trace Events, 57 

event log, 33 

filtering, 68 


purging, 69 

types of entries, 67 

viewing, 67 



Filter Event Log, 68 

Purge, 69 

execution context 

viewing, in XML format, 92 

Explorer, Internet, 3 

external connections 


F 

Failure Timeout field, 61, 62 

Filter Event Log command, 68 

filtering lists, 17 

business process instances, 93 

event log, 68 

message log, 79 

Finished status, 43, 43 

Foreground field, 57 

G 

graphics 

see color; diagrams 

H 

History command, 98 

Home page, 6 

Start Production, 42 

Stop Production, 43 

host classes, 22 

Host Monitor page, 95 

color indicators on, 96, 97 

History, 98 

Instances, 97 

I 

I/O archive, 34 

ID field, 29, 60, 62, 107 

Inactive status, 8, 57, 96 

Inactivity Timeout field, 57, 96 

inbound adapters, 59 

Info log entry type, 67 

Instances command, 97 

Internet Explorer, 3 

IsError status, 74, 101 

items 

see configuration items 

J 

jobs, system, 35 

Dequeuing, 36 

Error, 36, 96 

Inactive, 8, 96 


OK, 8, 96 

pool size, 52, 57, 59, 60 

Quiescent, 36 

Retry, 96 

Running, 36 

status of, 8, 35 

Jobs page, 35 


L 

listing 

see viewing 

log, business rule 

see business rule log 

log, event 

see event log 

log, message 

see message log 






Login page, 5 

Logout page, 10 

Log Trace Events field, 57 

Log Unassigned Trace Events field, 52 

Lookup Settings page, 109 

M 

Maintenance page, 103 

Archive Manager, 108 

Auto-Start Production, 104 


Default Settings, 110 

Enterprise Message Bank, 111 

Lookup Settings, 109 

Purge Management Data, 105 

Suspended Messages, 104 

management 

see Ensemble Management Portal 

Message Bank, 111 



Compare Messages, 75 

Contents, 75 

Details, 73 

filtering, 79 


Trace, 76 

message log 

and XML, 75, 92 

filtering, 79 

message details, 73 

viewing, 71 

messages, 36, 37 

and XML, 75 

Completed, 37 

Created, 37 

Deferred, 37 

Delivered, 37 

Discarded, 37 

IsError, 74, 101 

on specific queues, 99 

Queued, 37 

sending test messages, 117 

status of, 72 

Suspended, 37, 104 

visual trace of, 76 

Waiting, 118 

metrics, business 

see business metrics 



business processes, 91, 95 



event log, 65 

external connections, 65 

instantiated objects, 97 

jobs, 35 

levels of activity over time, 98 

messages on specific queues, 99 

productions, 65, 95 

queues, 65, 99 

N 

Name field, 56 

namespace, 6 

navigation path, 6 

O 

OK status, 8, 96 

operations, business 

see business operations 

outbound adapters, 61 

P 

Password field, 107 

passwords, 29 





pool, actor 

and jobs, 35 

and queues, 38 

size of, 52, 57, 59, 60 

Pool Size field, 52, 57, 59, 60 

portal 

see Ensemble Management Portal 

processes, business 

see business processes 


Actor Pool Size, 52 

and XML, 52 

automatic start or stop, 104 


dashboards for, 30 

diagram, 45 

documentation, 44 

instantiated objects, 97 


login credentials for, 107 

Log Unassigned Trace Events, 52 

long term archives, 108 

lookup tables, 109 

maintenance of, 103 

monitoring, 65, 95 

purging management data, 105 

Running, 42 

settings, 51 

starting, 42 

status of, 41 

Stopped, 42 

stopping, 43 

storing, 19 

Suspended, 42 

testing, 19, 117 

Testing Enabled, 52 

Troubled, 42 

viewing a list of, 41 

Productions page, 41 

Configure, 45 

Documentation, 44 

Finished, 43, 43 

Start, 42 

Stop, 43 

Purge Management Data page, 105 

Show Business Processes, 87, 91 

purging, 18 

all management data, 105 

business process instances, 93 

event log, 69 

Q 

Queue Contents page, 99 

Details, 73, 100 

Trace, 76 

Queued status, 37 

queues, 38 


status of, 38 

viewing a list of messages, 99 

viewing message contents, 99 

Queues page, 99 

color indicators on, 99, 100 

Contents, 99 

Quiescent status, 36 


R 

Reply Code Actions field, 61, 62 

resubmitting suspended messages, 105, 105 

Retry Interval field, 61, 62 

Retry status, 96 

routing process, 25 

rules, business 

see business rules 

Running status, 36, 42 

S 

Schedule field, 56 

searching 

log entries, 17 

selecting 

items to configure, 45 

main menu commands, 6 

maintenance tasks, 103 

management data to purge, 105 

services, business 

see business services 

SessionId 

and Visual Trace, 76 

sessions, 39 

recorded in the message log, 71 

visual trace of, 76 

settings 

business host, 54 

business operation, 61 

business process, 60 

business service, 59 

inbound adapter, 59 

outbound adapter, 61 


Show Business Processes, 91 

starting, 18 

automatic start and stop, 56 




resubmitting suspended messages, 104 

status 

business hosts, 57 


business processes, 91, 96 


configuration items, 50, 97 

event log entries, 67 

jobs, 8, 35, 36, 96 

messages, 37, 72, 74, 101 

messages on specific queues, 99 


queues, 38, 99 

suspended messages, 104 

test messages, 118 

status, color indicators for 




Host Monitor page, 96, 97 

Jobs page, 36 


Queues page, 99, 100 


Status log entry type, 67 

Stopped status, 42 

stopping, 18 

automatic start and stop, 56 




resubmitting suspended messages, 104 

storing, 19 

long term archives, 108 

lookup tables, 109 


Suspended Messages page, 104 

Details, 73 

Resend Editor, 105 

Resubmit, 105 

Trace, 76 

Suspended status, 37, 42, 104 

SVG Viewer, 4 



T 

testing, 19, 117 

Testing Enabled field, 52 

Testing Service page, 117 

Trace, 76 

Waiting, 118 

timeouts, 57 

trace, visual, of messages, 76 

Trace log entry type, 67 

Troubled status, 42 

U 

Username field, 107 

usernames, 29 





V 

versions 

Ensemble, 103 

Internet Explorer, 3 

SVG Viewer, 4 

Viewer, BPL, 88 

Viewer, SVG, 4 

viewing, 20 

business host setting, 54 

business operation settings, 61 

business process BPL diagram, 88 


business process settings, 60 

business service setting, 59 



event log entries, 67 

list of business processes, 87 

list of productions, 41 

list of rule definitions, 33 


message contents, 75 

message log, 71, 73 

message trace, 76 

production settings, 51 


Visual Trace page, 76 

W 

Waiting status, 118 

Warning log entry type, 67 

workflow, 39 


operations, 25 

Workflow Portal page, 40 

X 

XML 

message contents, 75, 92 

production settings, 52 

viewing the execution context, 92

Managing Ensemble Productions - InterSystems Documentation

Create successful ePaper yourself

Delete template?

Save as template?