Configuration Management Using BRIM®
Configuration management is a very important topic in any business rules environment. There are several questions that must be addressed as you go from one set of rules that govern the system to a different set of rules:
1. How do you handle the existing data?
2. Some classes in the new version may not even exist. What do you do with the data in those classes?
3. What about business event objects that are in states that no longer exist?
4. There may be hundreds or even thousands of rule changes from one version of a system to another. How do you move all of those rule changes into the existing production system with a minimum of disruption to your production system?
This document discusses the BRIM® configuration management environment including:
· Utilities used in configuration management
· How to use those utilities to perform various configuration management tasks.
1.BRIM® Utilities
BRIM® includes four very powerful utilities to support configuration management. The utilities described in this document should not be used by junior members of your design team. These routines will update whole portions of your system with a single command and must be used very carefully.
The four BRIM® utilities are as follows:
- Clone: Copies a rule or part of a rule into a new rule in the same repository
- Update: For two rules in the same repository, this utility updates one rule with all or part of the other rule
- Export: Takes a rule or part of a rule and generates an XML file
- Import: Takes an export file and imports it to a new or existing rule
Each utility will be discussed separately.
1.1. Clone Utility:
The Clone utility will take a rule or part of a rule and copy it. The copy is placed in the same repository as the original. New IDs are assigned to each object, but all links between logical components are maintained.
In addition, a link is generated between elements in the source and clone rule by using a clone ID. Each element in the repository is given a clone ID, the clone of the element is then given the same clone ID so that if any modifications to that element (including its name), we will still know that the clone and the original are the same logical component. The clone ID is generated via a complex routine that guarantees that clone IDs will be unique between systems.
PROCEDURE Uml_clone.P_clone
(SourceElementType_CD varchar2,
SourceElement_ID number,
STE_YN varchar2 := ‘N’,
UMLSecure_YN varchar2 :='N',
STESecure_YN varchar2 :='N')
Parameter Discussion:
There are 3 possible values for SourceElementType:
· uml_system.UmlRule
This is will clone all classes in the rule and all diagrams.
· uml_system.Diagram
This will only clone all the classes in the passed diagram ID.
· uml_system.Class
This will clone a single class.
SourceElement_ID must be consistent with SourceElementType_CD, e.g. if SourceElementType_CD is uml_system.Diagram then you must pass a diagram ID.
STE_YN will indicate if STE diagrams and states are cloned.
STESecure_YN will determine if STE security information is cloned.
UMLSecure_YN will determine if class level security is cloned.
1.2. Update Utility
This procedure will update one rule with all or part of another rule in the same repository. Items from the two rules are matched using the clone ID. If the clone ID in the source is not found in the target, it is a new item and is added. If the clone ID is found, the item is modified to match source item.
If the item is in the target but not the source, it is deleted. For example, if you have a class in the target rule but not the source rule and the update is at the rule level, the class will be deleted.
If there is a class by the same name in both the source and the target, but the clone IDs do not match or are null, then the procedure will fail.
PROCEDURE
Uml_clone.P_update
(SourceElementType_CD varchar2,
SourceElement_ID number,
TargetRule_ID number
:=Null,
STE_YN varchar2 := ‘N’,
UMLSecure_YN varchar2 :='N',
STESecure_YN varchar2 :='N')
PushOption_YN varchar2 :=
uml_ddl.GetActivePushOption,
ValidationOption_YN varchar2 :=
uml_ddl.GetActiveValidationMode);
Parameter Issues
There are 3 possible values for ElementType
· uml_system.UmlRule
This will update all classes in the rule.
· uml_system.Diagram
This will only update all the classes in the passed diagram ID.
· uml_system.Class
This will update a single class.
STE_YN will update states if ‘Y.’
UMLSecure_YN will update class security if ‘Y.’
STESecure_YN will update state security if ‘Y.’
PushOption_CD, and ValidationOption_CD are passed directly to the API commands. See the UML package for details. These are only important if you are updating an instantiated rule. If PushOption_YN is ‘N’, only classes with no data will be updated. If ValidationOption_YN is ‘Y’, the APIs will ensure that existing data does not violate the new rules. If any piece of data violates any rule, the procedure will fail. ValidationOption_YN = ‘N’ is similar to Oracle’s “enable no validate” option.
1.3. Clone Utility
This procedure will take a rule or part of a rule and generates several XML files. These files can then be taken to another BRIM® repository and imported. Since multiple files are generated, the procedure asks for a directory folder to know where to store the files. This directory must be empty prior to running P_Export.
PROCEDURE
XML_CLONE.P_EXPORT
(SourceElementType_CD varchar2,
SourceElement_ID number,
Path_TX
varchar2,
STE_YN varchar2 :='N'
UMLSecure_YN
varchar2 :='N'
STESecure_YN varchar2 :='N'
Parameter Issues:
There are 3 possible values for SourceElementType
· uml_system.UmlRule
This is will export all classes in the rule and all diagrams.
· uml_system.Diagram
This will only export all the classes in the passed diagram ID.
· uml_system.Class
This will export a single class.
SourceElement_ID must be consistent with SourceElementType_CD, e.g. if SourceElementType_CD is uml_system.Diagram then you must pass a diagram ID.
STE_YN will indicate if STE diagrams and states are exported.
STESecure_YN will determine if STE security information is exported.
UMLSecure_YN will determine if class level security is exported.
Path_TX is where the export file will be written. It is
limited by the value of the UTL_FILE_DIR
parameter in INIT.ORA
1.4. Import
This procedure takes a set of UML files and imports them into a new rule.
PROCEDURE
XML_CLONE.P_IMPORT
Path_TX varchar2,
Parameter Discussion
File_TX is the name of the import file.
Path_TX is the location of the import file. It is limited by the value of the UTL_FILE_DIR parameter in the INIT.ORA file.
2. Using the configuration management utilities
The configuration management utilities can be used for a number of tasks. Some example tasks are included here along with explanations of how the BRIM® utilities can be used to support them.
Sample Task 1: Combine the work from two teams in a development environment.
Imagine that you have two teams working in different repositories, building and testing their rule sets. Both sets have matured and you are ready to merge the work.
You have identified that there is little overlap between the two sets but that they do share a few key classes.
You decide to establish one of the rule sets as the base rule, and you will update that rule with the other (updating rule). The rule that is LEAST complete should be the base rule since the updating rule will overwrite the parts of the rule set that overlap.
Use the following steps:
1) Export the updating rule using p_Export
2) Import the updating rule XML file into the base rule repository
3) Ensure that there are no classes or diagrams from the two rule sets with the same name.
4) Use p_update to merge the two rule sets.
5) Manually move associations if necessary and delete extra elements.
Sample Task 2: Modify the attributes of a class in a production environment
You are in a production environment and you want to add, modify, or delete several attributes from a particular class.
Assume that the original class has the following structure:
Emp
Lname VC40
Fname VC40
EmpNo Num
EmpType Num
And the new structure will be
Emp
LastName VC40
FirstName VC40
BirthDate Date
EmpNo Num
EmpType EmpType
Assume the following:
VC40 is a simple text domain
Num is a simple number domain
Date is a simple date domain
EmpType is a textual value list domain
The problem with this sample task is that there is no way to directly migrate from the old structure to the new one because of the change in datatype and values in the Type attribute.
Use the following steps:
1) Clone the entire rule and place it in a test environment. Call the rule “ProdTest”
2) Export the class without states or security and import it into the test environment in a rule called “EmpClass”
3) Modify the Emp class in the EmpClass rule
4) In the test environment, add the old (numeric) and new (text) values to the EmpType domain.
5) Update ProdTest with EmpClass using the update with “Class” as the SourceElementType_CD with security and STE parameters set to ‘N’.
6) Write a SQL script to change the EmpType values from numeric to text.
7) Delete the old numeric parameters from EmpType in the test environment.
8) Test the behavior of the system to make sure that all changes were correct.
9) Export the EmpClass rule from test and import it into the production repository.
10) Rerun steps 4-7 in the production environment.
The idea is to always make changes to a production system in a test environment first. Test thoroughly before moving back into the production environment.
Sample Task 3: Full versioning of the system with many rule changes, but no data migration is necessary
Here the environment is quite complex. The strategy is to first copy the production system and place it in both development and test repositories. Then, make changes to the development repository and test the ability of the system to update the changes in the test repository. Once this process has been validated, you can replicate the migration process in the production instance.
The steps in the process are shown in Figure 1.
Figure 1: Configuration Management process
Sample Task 4: Full versioning of the system with many rule changes; data migration is necessary
In some instances the situation can be even more complex. It may be that there is no way to move directly from the old system to the new system without a substantive data migration. In this case, you will need to use a two step process.
- Migrate to an intermediate database that holds both the old structures and the new structures in the same repository.
- Perform an internal data migration from the old structures to the new structures.
- Delete the old structures.
The diagram for this would be exactly the same as in the previous example, except that as a final step, you need to delete the deprecated classes and associations.