HL7 Production Generator
With the Production Generator, you can enter all of your HL7 interface routes in a CSV file to produce a skeleton interoperability production that contains all of the components (services, routers, rules, transformations, and operations) needed for each route. Once generated, you still need to fine-tune the production to fit your needs, but the Production Generator speeds up the initial implementation. You can also use the Production Generator to update an existing production.
The Production Generator is an InterSystems Terminal utility that uses CSV files to create production components. These files can be delimited by commas or semicolons, but both files need to use the same delimiter. The required CSV files are:
-
Configuration file - Defines the naming conventions of the generated components.
-
Items file - Provides the Production Generator with information about the production's components.
The business host Ens.Activity.Operation.Local that is automatically added to the production by the Production Generator is used for activity monitoring, and can be removed if you do not need this functionality.
Running the Production Generator
To run the Production Generator:
-
Open the InterSystems Terminal.
-
Enter set $namespace="namespace" to navigate to the namespace where the production will be created.
-
Enter:
set status = ##class(EnsLib.InteropTools.HL7.ProductionGenerator).Load("configuration.csv","items.csv",.out)
Where:
-
configuration.csv is the path and filename of your configuration file.
-
items.csv is the path and filename of your items file.
-
out captures data issues reported by the Production Generator.
-
-
To check for errors, enter:
write status
The result should be 1.
For sample CSV files that you can use to generate a simple production, see Example CSV Files.
Configuration File
The configuration file defines the naming conventions of the components, such as business services or transformations, that are part of the generated production. The component names are built from a combination of literal values and placeholders; the syntax for placeholders is { }. The Production Generator populates placeholders with values from three places:
-
Other records in the configuration file.
-
Values from the items CSV file. To populate a placeholder with values from the items CSV file, you specify the column name that contains the values. For example, suppose the items file has a column named BusinessServiceName, and the first record specifies SourceA in that column. If the value of the ServiceName key in the configuration file is {BusinessServiceName}, then the Production Generator creates a service named SourceA. If the items file contained a second record with the value SourceB under the BusinessServiceName column, the Production Generator would create another service called SourceB.
-
The namespace where you run the Production Generator utility. When you run the Production Generator in the MyArea namespace, any component using the {Namespace} placeholder contains MyArea in its name.
The following is an example of a configuration file that contains all the required records. The first record containing Key, Value, and Description is required. In this example, {BusinessServiceName} comes from a column in the items file and {Namespace} comes from the namespace where you ran the Production Generator utility.
Key | Value | Description |
---|---|---|
ProductionClassName | MyBasePackage.MyProduction | Name of the generated production, which will be MyBasePackage.MyProduction. |
ServiceName | {BusinessServiceName} | Defines the naming convention of services. |
RouterName | {BusinessServiceName}Router | Defines the naming convention of router processes. |
OperationName | {BusinessOperationName} | Defines the naming convention of operations |
RuleName | {BasePackage}.{Namespace}.Rules.{BusinessServiceName}Rule | Defines the name convention of rules. |
TransformationName | {BasePackage}.{Namespace}.Transforms.{BusinessServiceName}Transform | Defines the naming convention of transformations. |
In addition to these required records, you can add the following optional records to the configuration file:
Key | Description |
---|---|
ConstrainRule | Default is 1, which means that in the definition of a rule, the constraint field sets “source” to the name of the business service. Other constraints do not get set. When set to 0, the rule’s constraint field is left empty. |
Override_componentID:setting |
Populates componentID:setting with the values from the specified column of the items file. For example, if the Key is Override_S:H:MessageSchemaCategory and the Value is {SourceDocVersion}, then the Message Schema Category setting will be set to the value in the SourceDocVersion column of the items file. This avoids having to add a column in the items file when the value of the setting is always shared with an existing column. Alternatively, you can specify a fixed value in the Value column. This is the same as adding a column in the items file named componentID:setting, and then giving every record in the column the same fixed value. For more information about the syntax of componentID:setting, see Specifying Component Settings. |
You can also define rows in the configuration file with the sole purpose of naming other values of the configuration file. In these cases, the Key can be any user-defined string. For example, suppose your configuration file includes:
Key | Value | Description |
---|---|---|
EnvironmentType | Test | Optional record used to populate Value of ProductionClassName |
ProductionClassName | MyProduction.{EnvironmentType} | Name of the generated production, which will be MyProduction.Test. |
Items File
Each record in the items CSV file corresponds to an interface route in the generated production, and determines which components are created along with their attributes. If multiple routes use the same component, the Production Generator creates a single component. For example, if the same business service is part of multiple routes, only one business service is created in the production.
The order of the columns in the items CSV file does not affect the Production Generator’s behavior. Each column accomplishes one of the following:
-
Provides values for placeholders in the configuration CSV file. These column names cannot contain special characters or punctuation.
Specifying Component Settings
The items file allows you to specify the initial value of settings for a component. Most settings are identified by using a special syntax in the column name: componentID:settingName. For example, the Enabled setting for an operation is identified with a column name O:Enabled. The componentID can be one of the following:
ComponentID | Component |
---|---|
S: | Business Service |
S:A: | Service Adapter |
S:H: | Service Host |
O: | Business Operation |
O:A: | Operation Adapter |
O:H: | Operation Host |
P: | Router Business Process |
R: | Rule |
T: | Transformation |
The settingName is the name of the component setting you want to define. You can obtain the correct setting name in two ways:
-
If you already have a production with this setting defined, open the production class in your IDEOpens in a new tab and find the setting name. You can see whether you have to specify “host”, “adapter” or neither.
-
You can also create a dummy production in the Management Portal and add the component. Then, navigate to the setting in the right-hand pane and click on the icon for the system default settings to see the name and host/adapter. If you have a non-English system, you can point the mouse on the local name to display the English setting name. Only host and adapter values are listed.
For settings that can have multiple values, separate values in the record with commas without any spaces. For example, to set the Category setting of the new service to Test1 and Test2, specify Test1,Test2 under the S:Category column of the items file. If you are manually editing the CSV file with a text editor using comma as the delimiter, specify "Test1,Test2" .
Settings get defined in one of the following:
-
The class definition of the component
-
The adapter class definition of the component
-
A superclass of these class definitions
-
Class Ens.Config.ItemOpens in a new tab (for example, the Enabled or PoolSize settings)
HL7 Message Settings
Settings that define the characteristics of source and target HL7 messages do not use the componentID:settingName syntax. Rather, you can specify the type (e.g., ADT_A01) and schema (e.g., 2.7.1) of the source and target HL7 messages using the SourceType, SourceSchema, TargetType, and TargetSchema columns.
Specifying the Type of Component
The items file must include columns, ServiceType and OperationType, that determine the type of business service and business operation created by the Production Generator. Possible values under ServiceType and OperationType are: TCP, File, FTP, HTTP and SOAP. The underlying class of the service or operation is based on the specified value of ServiceType or OperationType. You can specify a custom class for the service or operation by specifying a fully qualified class name such as MyProduct.MyFileService in the ServiceType or OperationType column.
Optionally, the items file can include a column RouterType that specifies the class name of a custom router associated with the interface route. Without this column, the class EnsLib.HL7.MsgRouter.RoutingEngine is used.
Special Instructions
Certain predefined column names provide special instructions to the Production Generator. A boolean value (0 or 1) in the record under the column indicates whether the Production Generator should execute the instruction. You can specify special instructions using the following columns:
Column Name | Description |
---|---|
RuleDisabled | Set value to 0 to enable the rule or 1 to disable the rule. Without this instruction, the Production Generator disables the rule. |
NoTransformation | Set value to 1 to prevent the Production Generator from creating a transformation. If you are updating a production, adding this column will not delete already existing transformations. |
T:Create | By default, the outbound message of a transformation is a copy of the inbound message. If you add a T:Create column and set its value to new, the outbound message of the transformation will be an empty object. |
Example CSV Files
The following are examples of a configuration CSV file and items CSV file that work together to create a basic production. You can copy and paste the following into CSV text files and input them into the Production Generator. You can also open them up in a spreadsheet application to view the columns. The Production Generator also accepts files with a semicolon as the delimiter.
Key,Value,Description
BasePackage,MyPackage,Base package name of all classes
ProductionClassName,{BasePackage}.MyProduction,Definition of the production name
ServiceName,{ServiceName},Definition of service name
RouterName,{ServiceName}_Router,Definition of process name
OperationName,{OperationName},Definition of operation name
RuleName,{BasePackage}.{Namespace}.Rules.{ServiceName}Rule,Definition of rule name
TransformationName,{BasePackage}.{Namespace}.Transforms.{ServiceName}Transform,Definition of transformation name
ServiceName,ServiceType,ReceivingApplication,OperationType,OperationName,O:Enabled,S:A:FileSpec,S:H:MessageSchemaCategory,O:H:FailureTimeout,P:Category,NoTransformation
Service1,Op1,File,File,0,*,2.7.1,60,Cat1,0
Service2,Op2,TCP,FTP,1,,2.7.1,,,1
Updating an Existing Production
You can rerun the Production Generator after making changes to the CSV files to alter the generated components without using the Management Portal. To clear out the value of a setting, use "" in the record under the setting’s column. Columns that previously included the delimiter in the value (e.g., FTP,Hospital under the Categories column) cause an issue when trying to clear out the value. In this case, you must use """""" to clear the value. Records with null data do not alter the generated components.
To prevent the loss of substantial logic, the Production Generator will not delete certain items when you update a production:
-
If you remove a row from the items file, the services and operations defined in that row will not be deleted from the production.
-
Once a transformation exists and is assigned to a rule, it will not be deleted if you add the NoTransformation column to the items file.
-
Once a routing rule is created, it will not be deleted.