Introduction

This chapter introduces the process of developing productions. It contains the following topics:

For an introduction to Ensemble concepts and options, see Introducing Ensemble. For information on how Ensemble processing works, see the first chapter in Monitoring Ensemble.

Environmental Considerations

You can use Ensemble only within an Ensemble-enabled namespace that has a specific web application. When you create classes, you should avoid using reserved package names. The following subsections give the details.

Ensemble-enabled Namespaces

An Ensemble-enabled namespace is a namespace that has global mappings, routine mappings, and package mappings that make the Ensemble system classes and data available to it. For general information on mappings, see “Configuring Namespaces” in the chapter “Configuring Caché” in the Caché System Administration Guide. (You can use the information in that section to see the actual mappings in any Ensemble-enabled namespace; the details may vary from release to release, but no work is necessary on your part.)

Of the system-provided namespaces, only ENSEMBLE and ENSDEMO are Ensemble-enabled.

Once you have successfully installed Ensemble, any new namespace that you create is by default Ensemble-enabled. If you clear the Make this an Ensemble namespace check box when creating a namespace, Ensemble creates the namespace with Ensemble disabled.

Important:

Except for the ENSEMBLE and USER namespaces, all system-provided namespaces are overwritten upon reinstallation or upgrade. For this reason, InterSystems recommends that customers always work in the ENSEMBLE namespace, the USER namespace (not suitable for Ensemble use), or in a new namespace that you create. For information on creating a new namespace, see “Configuring Data” in the chapter “Configuring Caché” in the Caché System Administration Guide.

Web Application Requirement

Also, you can use Ensemble in a namespace only if that namespace has an associated web application that is named /csp/namespace, where namespace is the namespace name. (This is the default web application name for a namespace.) For information on defining web applications, see “Applications” in the Caché Security Administration Guide.

Reserved Package Names

In any Ensemble-enabled namespace, avoid using the following package names: Demo, Ens, EnsLib, EnsPortal, or CSPX. These packages are completely replaced during the upgrade process. If you define classes in these packages, you would need to export the classes before upgrading and then import them after upgrading.

Also, InterSystems recommends that you avoid using any package names that start with Ens (case-sensitive). There are two reasons for this recommendation:

When you compile classes in packages with names that start with Ens, the compiler writes the generated routines into the ENSLIB system database. (The compiler does this because all routines with names that start with Ens are mapped to that database.) This means that when you upgrade the instance, thus replacing the ENSLIB database, the upgrade removes the generated routines, leaving only the class definitions. At this point, in order to use the classes, it is necessary to recompile them.
In contrast, when you upgrade the instance, it is not necessary to recompile classes in packages with names that do not start with Ens.
If you define classes in packages with names that start with Ens, they are available in all Ensemble-enabled namespaces, which may or may not be desirable. One consequence is that it is not possible to have two classes with the same name and different contents in different Ensemble-enabled namespaces, if the package name starts with Ens.

A Look at a Production Definition

Although you create and configure productions in the Management Portal, it is instructive to get started by looking at the definition of a production in Studio. This following shows a simple example of a production that is defined in the ENSDEMO namespace:

Class Demo.FloodMonitor.Production Extends Ens.Production
{

XData ProductionDefinition
{
<Production Name="Demo.FloodMonitor.Production">
  <ActorPoolSize>1</ActorPoolSize>
  <Item Name="Demo.FloodMonitor.BusinessService" 
        ClassName="Demo.FloodMonitor.BusinessService" 
        PoolSize="1" Enabled="true" Foreground="false" InactivityTimeout="0">
  </Item>
  <Item Name="Demo.FloodMonitor.CustomBusinessProcess" 
        ClassName="Demo.FloodMonitor.CustomBusinessProcess" 
        PoolSize="1" Enabled="true" Foreground="false" InactivityTimeout="0">
  </Item>
  <Item Name="Demo.FloodMonitor.GeneratedBusinessProcess" 
        ClassName="Demo.FloodMonitor.GeneratedBusinessProcess" 
        PoolSize="1" Enabled="true" Foreground="false" InactivityTimeout="0">
  </Item>
  <Item Name="Demo.FloodMonitor.BusinessOperation" 
        ClassName="Demo.FloodMonitor.BusinessOperation" 
        PoolSize="1" Enabled="true" Foreground="false" InactivityTimeout="0">
  </Item>
</Production>
}
}

Note the following points:

The production is a class, specifically is a subclass of Ens.ProductionOpens in a new tab.
The XData ProductionDefinition block holds the configuration information for the production.
Each <Item> is a business host; these are also called configuration items.
Each business host refers to a class. ClassName specifies the class on which this host is based. This means that when the production creates an instance of this business host, it must create an instance of the specified class.
The Name of an business host is an arbitrary string. Sometimes, it can be convenient to use the class name for this purpose, as in this example. This convention does not work when you create a large number of business hosts that use the same class.
It is important to establish naming conventions at an early point during development. See Ensemble Best Practices. An absence of naming conventions will lead to confusion.
The other values in the XData block are all settings. At the top, <ActorPoolSize> is a setting for the production. Within the business host definitions, PoolSize, Enabled, Foreground, and InactivityTimeout are settings for those business hosts.

Development Tools and Tasks

Ensemble productions consist primarily of class definitions and some supporting entities. The process of creating a production can require a small amount of programming or possibly a large amount, depending on your needs. As noted earlier, Ensemble provides graphical tools that enable nontechnical users to create business logic visually. These tools generate class definitions as needed.

While you develop a production, you use both the Management Portal and Studio as follows.

Portal Tasks

In the Management Portal, you use wizards to define and compile the following:

The production class. See Configuring Ensemble Productions.
When you apply changes to the production, Ensemble automatically saves them and compiles the production class.
BPL business process classes. See Developing BPL Processes.
DTL transformation classes. See Developing DTL Transformations.
Business rule classes. See Developing Business Rules.

You also use the Management Portal for the following additional tasks:

Defining reusable items for use in settings; these include Ensemble credentials, business partners, and so on. See Configuring Ensemble Productions.
Starting and stopping the production. See Managing Ensemble.
Examining the message flow, as part of your testing and debugging process. See Monitoring Ensemble.
Test specific business hosts. See the chapter “Testing and Debugging.”

Studio Tasks

In Studio, you define and compile the following classes:

Message classes. See “Defining Ensemble Messages.”
Business service classes. See “Defining Business Services.” Note that Ensemble provides business service classes that directly use specific adapters. You might be able to use one of them rather than create your own.
Custom business process classes. See “Defining Business Processes.”
Business operation classes. See “Defining Business Operations.” Note that Ensemble provides business operation classes that directly use specific adapters. You might be able to use one of them rather than create your own.
Custom data transformation classes. See “Defining Data Transformations.”
Custom adapter classes. See “Less Common Tasks.”

Also see other topics in the chapter “Less Common Tasks.”

Available Specialized Classes

Ensemble provides many specialized adapter and business host classes that can reduce your development and testing time. For a summary of the most common options, see “Overview of Ensemble Options” in Introducing Ensemble. Rather than listing the specific classes, that chapter describes scenarios for which Ensemble provides tools. It provides references to the applicable books.

Using Studio in Ensemble

This section briefly discusses additional Studio features and notes that apply when you are creating an Ensemble production. It contains the following sections:

Ensemble Features in Studio

The Ensemble features of Studio become active whenever Studio is connected to an Ensemble-enabled namespace. These features are as follows:

An additional tab in the Workspace window
Additional items in the Other folder in the Workspace window
An option to generate a project that contains all the code for a production
Additional wizards for the File > New menu, not discussed here

Production Tab

For an Ensemble-enabled namespace, the Workspace window includes the Production tab. This tab lists classes related to Ensemble productions. This has the following folders:

Folder	All classes in this folder are subclasses of...
Adapters	Ens.AdapterOpens in a new tab, including inbound and outbound adapters
Business Operations	Ens.BusinessOperationOpens in a new tab.
Business Processes	Ens.BusinessProcessOpens in a new tab.
Business Services	Ens.BusinessServiceOpens in a new tab.
Data Transformations	Ens.DataTransformOpens in a new tab.
Messages	Ens.RequestOpens in a new tab or Ens.ResponseOpens in a new tab.
Productions	Ens.ProductionOpens in a new tab.

Additional Items in Other

The Other folder in the Workspace window can contain additional items that may be unfamiliar to you. These include the following:

Schema definitions for use with EDI (electronic document interchange) documents. The names of these definitions end in .HL7, .ASTM, .X12, and so on. For information, see Ensemble Virtual Documents.
Dashboard definitions. Their names end in .dfi. For information, see “Creating Dashboards” in Configuring Ensemble Productions.
Note that dashboards are not restricted to Ensemble-enabled namespaces. This item is listed here because .dfi items might be unfamiliar to you.

Option to Create a Project from a Production

Ensemble makes it easy to create a Studio project from a production, so that you can easily export a production from one system and import it into another. Use the following procedure:

In the Workspace window, right-click a production.
Click Create Project from Production.
Enter a project name and click OK. A project file is saved in the current namespace. The project includes all the detectable items for this production. This includes:
- The production class
- Each business host class
- Each adapter class
- Routing rules
- HL7 schemas
- Subclasses of routing engines
- Subtransforms

Exporting and Importing Productions

You can either use the management portal or Studio to export and import a production. The management portal makes it easier to include all required components in the export. For information on using the management portal to export and import a production, see Deploying a Production.

To export a production and then export it into another namespace or instance, do the following in Studio.

Create a project from the production. See the previous topic.
Export the project as an XML file.
Import the XML file into another namespace or instance.

For information on importing and exporting projects, see Using Studio.

If the production requires data that is stored directly in globals, see “Managing Globals” in Using Caché Globals; this provides information on exporting and importing globals.

You can also export productions from the Management Portal. See Configuring Ensemble Productions.

Notes on Editing the Production Class

It is generally best to edit the production class within the Management Portal. By doing so, you can avoid introducing syntax errors and you take advantage of the type validation that the portal provides.

There are a couple of reasons, however, in which you might want to edit the class in Studio:

You might want to change the order of <Item> elements in the XData block.
You might want to add other class members, particularly methods, properties, and parameters.

The order of <Item> elements in the XData block controls one of the sorting options on the Production Configuration page. On this page, when you sort by number, the items are displayed in the order they are listed in the XData block, which is (initially) the order in which they were added to the production.