Production Validator

Production Validator execution requires that the Production Validator code be installed in both the source system and the target system. The most recent version of the Production Validator code comes pre-installed in versions 2025.1 and later. If either your source system or your target system (or both) is older than 2025.1, you will need to download the code and install it as follows:

1. Go to the WRC Distribution page under ComponentsOpens in a new tab and search for Production Validator.

2. Download and unzip the Production Validator ZIP file. Make a note of the name of the extracted file and the path to where you save it. Execute the remaining steps for the source system and/or the target system, whichever are older than version 2025.1.

3. Log in to the IRIS terminal associated with the relevant system, and set the namespace to HSLIB.

   Set $namespace="HSLIB"
   

   

4. Write enable the HSLIB database to prepare for loading the Production Validator code.

   write ##class(%ZHSLIB.HealthShareMgr).UpdateReadWrite("HSLIB",0)
   

   

5. Set a string variable to identify the filename and path to the Production Validator code.

   set file="<filepath>\<extracted_prod_validator_file>"
   

   

6. Load Production Validator code.

   do $system.OBJ.Load(file,"ck")
   

   

7. Reset read/write permissions for the HSLIB database.

   write ##class(%ZHSLIB.HealthShareMgr).UpdateReadWrite("HSLIB",1)
   

   

Follow these steps to create and export a JSON object describing production data stored in the source system database.

1. In the terminal, switch to the namespace associated with the existing production system. For example, if the production name is TESTING:

   Set $namespace="TESTING"
   

   

2. Fetch any paths within the production that have an HL7 service and an HL7 operation, and store them within a template object, to be used for production message comparison.

   set template=##class(HS.InteropTools.HL7.Compare.ProductionExtract).GetServiceList()
   
   

   

3. Optional. After creating a template object for production message comparison, you can manipulate the object to configure your eventual results, by setting element values at the terminal command line or by streaming the JSON output into a text file, editing it, and re-importing. See Advanced Options for details.

4. Using the template object, export source production data to the database in tempDatabaseDir.

   write ##class(HS.InteropTools.HL7.Compare.ProductionExtract).Run(template)
   

   

   This should return 1, indicating successful data export.

Set stream = ##class(%Stream.FileCharacter).%New()
Write stream.LinkToFile(filename)
Do template.%ToJSON(stream)

Set stream = ##class(%Stream.FileCharacter).%New()
Write stream.LinkToFile(filename)
Set template={}.%FromJSON(stream)

{"name":"ADT_OPERATION","exclude":1}

Follow these steps to generate analogous messages in your upgraded system and compare them to the messages generated in your source system.

Prerequisites

• If you are upgrading from an InterSystems Cache-based system, rename the Cache.DAT file to IRIS.DAT.

• IMPORTANT: Copy your IRIS.DAT to a new location available to the target system. This will allow you to re-execute the steps on the target if something goes wrong.

Steps

1. Log in to the IRIS terminal associated with the target system, and set the namespace to HSLIB.

   Set $namespace="HSLIB"
   

   

2. Create the namespace for your comparisons, and begin reprocessing messages. Later, the reprocessed messages will be compared to the original messages from the source system.

   set sc = ##class(HS.InteropTools.HL7.Compare.ProductionExtract).ConfigureAndImport(<Testing_Namespace>,<Full_Path>)
   

   

   Full_Path is the full path to the directory that contains the IRIS.DAT database.

   Testing_Namespace is the name of the testing namespace.

   This process switches you into the new testing namespace.

   Note:

   If the user code is mapped elsewhere or a production item requires additional globals, the code/globals must be brought manually into this instance. In this case, instead of executing the ConfigureAndImport() method, follow these instructions:

   1. Configure the new testing namespace:

      set sc = ##class(HS.InteropTools.HL7.Compare.ProductionExtract).ConfigureNamespace(<Testing_Namespace>,<Full_Path>)
      

      

   2. Load your code and/or globals manually into the testing namespace.

   3. Switch into the newly created testing namespace and begin reprocessing messages. Later, the reprocessed messages will be compared to the original messages from the source system.

      Set $namespace="<Testing_Namespace>"
      set sc = ##class(HS.InteropTools.HL7.Compare.ProductionExtract).Import()
      

      

3. Ensure that the import succeeded by checking the value of the status code variable sc. The value should be 1.

   write sc
   

   

4. Execute the comparison of messages from the source system to messages from the upgraded system, and store the results in a variable.

   set stats=##class(HS.InteropTools.HL7.Compare.Compare).Run("Source","Target")
   

   

5. View the comparison results.

   zwrite stats
   

   

   The output includes the following data:

   • compareStartTime—The beginning of the timespan of the comparison.

   • count1—The number of messages in the output from the source system.

   • count2—The number of messages in the output from the upgraded system.

   • missingFiles—The number of messages present in the source system output that are absent in the upgraded system output.

   • newFiles—The number of messages present in the upgraded system output that are absent in the source system output.

   • differences—The number of messages that exist in the output of both systems but that have different contents.

   • kpi—Percentage representing how close the upgraded system’s output is to the output from the source system.

   • compareEndTime—The end of the timespan of the comparison.

   • output—A link to the Visual Comparison page in the management portal, which displays a detailed listing of the differences between the two sets of messages.

6. To view the output of the comparison on the Visual Comparison page in the management portal, click the link in the output field. This page displays each message in tabular form with issues highlighted. There is also a link to the visual trace. You can use these tools to identify issues. Certain issues may be inevitable or uncorrectable, and the Visual Comparison page features links to filter some of these out of the output.

7. Optional. You can insert items to be ignored into a skip list table. Items in this table will not be included in the comparison output. Instead, if a field is included in the skip list, the field value is replaced in the output with SLV, which indicates a skip list value. For example, if the only difference between a message from the source system and the corresponding message from the upgrade system is that one is from production and the other is from testing, you might reasonably wish to skip that difference.

   To add an item to the skip list table, execute the following command in the testing namespace:

   Set rs = ##class(%SQL.Statement).%ExecDirect(,"insert into HS_InteropTools_HL7_Compare.Skiplist (Segment,Field) Values (?,?)","<segment_name>",<position>)
   

   

   In addition to skipping specified differences in a field, you can skip entire rows if they are empty. To skip empty segments, insert into HS_InteropTools_HL7_Compare.Skiplist( Segment,Field,IgnoreEmptySegment) Values ('PV1','*',1). Entering these values will only skip the identified segments in which all fields are completely empty.

   Note:

   The skiplist can be used to skip specific fields within a segment, but will require entering the value of the field names in the skiplist field.

   See HS.InteropTools.HL7.Compare.SkiplistOpens in a new tab in the class reference for additional position options provided by other properties of the Skiplist class.

8. Optional. If you added rows to the skip list, recompute and refresh the Visual Comparison page to see the new results. In the testing namespace, execute this command:

   do ##class(HS.InteropTools.HL7.Compare.Compare).Recompute("Source","Target")