Caristix Test is designed to help interface analysts and engineers validate HL7 interfaces. The software provides the following features and functionality:
If you have a trial version, you will need to purchase a license to continue using Test after the end of the trial period.
Suites are analogous to a test plan. A suite contains all of the test scenarios and workflows that you will run in order to validate that an interface works. A suite manages a collection of test scenarios (test cases).
Suites are files with the .cxs extension and are represented in the document library by the
icon.
On the Configuration tab, you set timing and execution parameters for your suite.
These settings let you run scenarios contained in a suite several times, in a loop. For instance, you can set a scenario to execute 100 times with 100 different patient names.
After the scenario suite has been executed once, a new tab will be displayed (Results). The Results tab contains the detailed information about what was executed for any specific execution. If variables were used in configuration or validation, you will see their instantiated values.
Select a result to see the detailed information. You can also perform action (right-click) with a result, such as:
Scenarios are analogous to a test case. A scenario is are a sequence of steps to test the behavior of the interface. Suites contain one or more scenarios. An example of a scenario would be a med pass, which would include a patient arrival, a series of lab orders and results, medication orders, etc.
A new scenario representing the workflow and containing several actions and tasks is created. The scenario can be updated as needed.
On the Configuration tab, set timing and execution parameters at the Scenario level.
These settings let you run tests several times, in a loop.
After the scenario has been executed once, a new tab will be displayed (Results). The Results tab contains the detailed information about what was executed for any specific execution. If variables were used in configuration or validation, you will see their instantiated values.
Select a result to see the detailed information. You can also perform action (right-click) with a result, such as:
A scenario consists of a series of actions. An action represents a single step in a specific workflow — for instance, the arrival of a patient.
On the Configuration tab, set timing and execution parameters at the Action level.
These settings let you run tests several times in a loop.
After the action has been executed once, a new tab will be displayed (Results). The Results tab contains the detailed information about what was executed for any specific execution. If variables were used in configuration or validation, you will see their instantiated values.
Select a result to see the detailed information. You can also perform action (right-click) with a result, such as:
Actions are made up of tasks. A task represents the smallest unit of work contained in a scenario. It could be an HL7 message exchange (an admit/visit notification), a database interaction (a query to the patient table), or a manual step requiring the user to interact with a 3rd party application.
Your test cases are based on a sequence of tasks.
There are several types of tasks. Each task type has its own behavior.
After the task has been executed once, a new tab will be displayed (Results). The Results tab contains the detailed information about what was executed for any specific execution. If variables were used in configuration or validation, you will see their instantiated values.
Select a result to see the detailed information. You can also perform action (right-click) with a result, such as:
The Javascript engine allows you to inject custom Javascript at different steps of a Task execution.
You can toggle the “Fake Execution” mode on each task, which executes your custom Javascript code instead of performing the task as configured. That way, you can mock, for instance, a web service result to quickly develop your test cases, even if the real web service that would be used in tests is not ready to be used yet.
To use Fake Execution, call the “callback(result)” method, providing a string containing the fake result you want your task to have.
For each task type, a default fake execution script is provided. The default scripts are as follows.
This script fakes the task’s execution as if the messages were successfully sent, and the configured connection endpoint returned an HL7-ACK.
callback(`MSH|^~\&|GHH LAB, INC.|GOOD HEALTH HOSPITAL|ADT1|GOOD HEALTH HOSPITAL|20210305104622||ACK^A01^ACK|ACK-MSG00001|T|2.5.1
MSA|AA|MSG00001
`);
This script fakes the task’s execution as if it received/read the HL7v2 messages provided in the callback method.
callback(`MSH|^~\&|ADT1|GOOD HEALTH HOSPITAL|GHH LAB, INC.|GOOD HEALTH HOSPITAL|198808181126|SECURITY|ADT^A01^ADT_A01|MSG00001|T|2.5.1
EVN||200708181123||
PID|1||PATID1234^5^M11^ADT1^MR^GOOD HEALTH HOSPITAL~123456789^^^USSSA^SS||EVERYMAN^ADAM^A^III||19610615|M||2106-3|2222 HOME STREET^^GREENSBORO^NC^27401-1020
NK1|1|JONES^BARBARA^K|SPO^Spouse^HL70063||||NK^NEXT OF KIN
PV1|1|I|2000^2012^01||||004777^ATTEND^AARON^A|||SUR||||7|A0|
`);
This script fakes a database query result. A JSON Array with 2 entries is provided as a result. This mocks the following dataset
callback(`[
{
"column1": "value 1",
"column2": "value 2"
},
{
"column1": "value 3",
"column2": "value 4"
}
]`);
| Column 1 | Column 2 |
| Value 1 | Value 2 |
| Value 3 | Value 3 |
This script fakes the execution of the task as if an HTTP result is returned. A JSON object is provided, allowing you to mock the HTTP Response Status Code (200, 404, 500) and the response Body. The above script would return an OK – 200 status code with a JSON value in the response body.
callback(`{
"responseStatusCode": "200",
"responseBody": {
"resourceType": "operationOutcome"
},
}`);
HTTP Response Status: 200 (OK)
HTTP Body: { "resourceType": "operationOutcome" }
A JavasScript task executes JavaScript code using our JavaScript API.
Right-click the name of the parent Action the new task will be created in, and select Add New Task –> Execute JavaScript Task.
A new Task appears under the parent Action. Edit the task name as needed. Drag and drop to change the task order.
Any valid JavaScript can be executed in this task. Simply add the code you wish to execute to the code textbox in the configuration tab. You can also use our JavaScript API to manipulate Caristix-related resources.
To return a result for validation, use the callback() method. The callback() method takes a string as an argument and sets the value returned by the task when called.
The following is an example of a JavaScript task’s code. In the example, a GET request is sent to a public FHIR server, and the resulting bundle is returned for validation.
//Create an HTTP request using the provided HTTP GET method and full resource url,
// https://daas.caristix.com/fhir/Patient.
var request = HTTP.create('GET', 'https://daas.caristix.com/fhir_r4/Patient/');
//Add the Accept header with the value application/fhir+json to the request.
request.setHeader(‘Accept’, ‘application/fhir+json’);
//Send the HTTP request.
var result = request.send();
//Obtain the HTTP result’s body – a Bundle of Patient Resources.
var body = result.body;
//Return the body.
callback(body);
A Send HL7 Message task simulates a system sending HL7 messages to a host on a specific TCP port. The HL7 messages are defined directly in the task. Validation can be done on the acknowledgment (ACK) messages that are sent back.
A new task is added at the end of the current action. Drag and drop to change the task order.
There are several options to control message format and destinations.
Note: If you’re using the XML format, you will need to open the XML Editor (click the Edit.. button) to be able to insert variables or edit the document.
If the receiving system is configured to return message acknowledgement, each sent message would be responded to with an ACK or a NACK message. Validations can be added to the task to confirm the ACK/NACK response is as expected. Several validation types can be added:
A Send HL7 File task simulates a system sending HL7 messages from a file to a host on a specific TCP port. Validation can be done on the acknowledgment messages that are sent back.
A new task is added at the end of the current action. Drag and drop to change the task order.
There are several options to control where the messages in the file are sent.
If the receiving system is configured to send back message acknowledgement, each message sent would be responded to with an ACK or a NACK message. Validations can be added to the task to confirm the ACK/NACK response is as expected. Several validation types can be added.
A Receive HL7 Message task simulates a receiving system listening for HL7 messages on a specific TCP port. Validation can be done on the messages received.
There are several options to control message listening.
In both cases, validation rules will apply to all received messages.
Note: During test execution, Receive HL7 Message tasks will start to listen at the beginning of the parent Action so there can only be one task that listens to a specific port per Action.
Validations rules can be added to confirm the received messages are as expected. Several validation types can be added.
A Read HL7 File task simulates a receiving system listening for HL7 messages on specific files. Validation can be done on the messages received.
A new task is added at the end of the current action. Drag and drop to change the task order.
There are several options to configure:
Validations rules can be added to confirm the received messages are as expected. Several validation types can be added.
An Execute Web Service task allows you to interact with a Web Service during a test.
Validations rules can be added to confirm that the query result is as expected.
A Query Database task is for querying a database and validating the result. Examples of databases to query include a clinical application database or the internal integration engine database.
There are several options available.
You can retrieve HL7 or XML messages from a database and perform HL7 v2.x or XML validations. To do so, your SQL Query must return only one column (the HL7 or XML message). Then, in the Validation tab, select the appropriate Validation type.
Validations rules can be added to confirm the query result is as expected. Several validation types can be added:
An Execute Command task allows you to interact with other applications during a test using command-line commands. For instance, call a cmd script to delete files or prepare content for subsequent tasks.
Validations rules can be added to confirm that the execution result is as expected.
Manual tasks pause the execution of the scenario and wait for a manual intervention from the user. A manual task can be an interaction with a 3rd party application or just a way to pause the execution so extra manual validation can be done. It’s up to the user to confirm whether the task succeeds.
Manual tasks are very easy to configure. Just enter instructions to the user explaining what to do. The instructions will be displayed on the screen when the scenario executes this task. Once displayed, the execution will pause and wait for feedback from the user, based on whether the task succeeds or fails. This feedback is integrated in the test execution report.
Each time the Manual Task is executed, a popup will be shown. From there, you can mark the task as succeeded, skipped or failed. If you set the task as failed, you can use the comment area to type what went wrong. The text will be added to the task validation errors.
Validation is the fundamental test activity. Without validation, you can’t prove that an interface works unless you bring it into production and wait for defects to emerge. Validation ensures that the interface meets requirements and behaves as expected without defects.
As a testing activity, validation is a set of rules applied to a message or a task response to verify the message or the response behaves as expected.
After a task is executed, you can validate the task result with different validation types. One of them is Javascript Validation, which allows you to code multiple validation rules using Javascript.
By using the callback() method, you can notify the task when an error has occurred during one of the validations. You can provide callback() with an error message as a string.
All your Validation Rules are executed independently.
Task Validation Context
The Javascript validation context object allows you to access the task result, as well as a map that is shared between different validations in the same task.
The context object contains the following properties.
The result returned by the task. Using the task result, you can use the HL7, XML, or JSON parser to parse the text result as a queryable object and build sophisticated validations with it.
var result = context.taskResult;
A Map that is shared between different validations in the same task.
context.map.set("PID.5.1", "Smith");
callback("PID.5.1: " + context.map.get("PID.5.1"));
// PID.5.1: Smith
The Map object is a collection of key-value (string-object) pairs that can be added and updated.
The Map object exposes the following methods.
Updates the key’s value to the provided value. If the key does not exist in the map, adds the key-value pair to the map.
Returns the value associated with the key in the map. If the key does not exist in the map, returns null.
map.set("PID.5", { family: "Smith", given: "John" });
callback("PID.5 Given: " + context.map.get("PID.5").given);
// PID.5 Given: John
Returns whether or not the key exists in the map.
map.set("PID.5", { family: "Smith", given: "John" });
callback("Contains PID.5: " + map.has("PID.5"));
// Contains PID.5: true
Some tasks return content using a string representation. In those cases, basic string-comparison validations can be applied.
This area contain the string representation of an execution result. The default value displayed is the latest task’s result. You can display a previous result, if available, using the Right-Click menu item “Previous Results”. You can also use this text area to add validation rules. Highlight the text you want as the VALUE for your validation, then Right-Click and select “Add Validation”.
Configure a set of rules to be validated manually by the user.
At run-time, a dialog listing validations will be shown. Users will have to set the status for each rules, and a reason if needed.
Configure a set of rules to ensure SQL Query results conforms to expected values.
This area contain the grid representation of an execution result. The default value displayed is the latest task’s result. You can display a previous result, if available, using the Right-Click menu item “Previous Results”. You can also use this area to add validation rules. Right-Click a value you want as the VALUE for your validation, then select “Add Validation”.
HL7 v2.x Validation configures a set of rules that validate message content is as expected. Rules are associated to messages fields or components.
You can create your validation from an existing message, which simplifies the process, or manually.
To create from a message:
To create manually:
You can edit the criteria by clicking on the cell to set a basic text value. In addition, you have access to the Variable Editor and the Criteria Editor which are opened by right-clicking on the criteria cell. From there you can insert a Variable or a Field Value criteria by specifying its location.
It may be necessary to temporarily disable a validation rule so it is no longer evaluated during test execution. To disable a rule, uncheck the check box in the very first column of the Segment-Field Validation table. To re-enable it, recheck the check box to the initial state.
In Advanced Mode, you can also select a specific field repetition to which the validation will apply.
You can use And, Or and Parentheses to perform more advanced conditions for your validations.
Data filters and operators let you define validation rules. The operators let you build filter queries, ranging from simple to complex. The most basic operator set consists of the use of “is” and “=”.
These are the default operators in the Add Data Filter command, available on the right-click dropdown menu in the Last Result area.
The other data filter operators let you build sophisticated filters for analyzing HL7 data.
| Operator | Action |
| is | Includes messages that contain this data |
| is not | Excludes messages that contain this data |
| = | Covers messages with an exact match to this data (this is like putting quotation marks around a search engine query) |
| < | Less than. Covers filtering on numeric values. |
| <= | Less than or equal to. Covers filtering on numeric values. |
| > | Greater than. Covers filtering on numeric values. |
| >= | Greater than or equal to. Covers filtering on numeric values. |
| like | Covers messages that include this data. Covers filtering on numeric values. |
| present | Looks for the presence of a particular message building block (such as a segment, field, component, or sub-component) |
| empty | Looks for an unpopulated message building block (such as a segment, field, component, or sub-component) |
| in | Builds a filter on multiple data values in a message element rather than just one value. |
| in table | Looks if the data is in a specific table of the referenced Profile. |
| matching regex | Use .NET regular expression syntax to build filters. For advanced users with programming backgrounds. Learn more about regular expressions here:
This is also a quite good utility to hep you create complex regular expressions: |
Validation rules can be exported to file so they can be reused for validation in some other tasks. They are exported in files with .csf extension.
To export every validation rules for a task:
The same way, validation rules can be imported from file so validation rules can be reused. By default, validation rule files have .csf extension.
To import validation rules from a file and add them to the already existing rules:
During the validation phase, you compare transformed messages with another set of messages you already know are valid (golden message set). The highlighted differences will indicate any issues in your code or any missing transformations. This is a quick and easy way to validate that your code fulfills the requirements.
For a more detailed view of a message pair or message differences, double-click the message pair you want to compare. Navigate through the tree view, field by field, to see the differences.
Click on the gray zone at the bottom of the screen to view more details about each difference. Double-clicking on a grid row helps you navigate through the differences.
You may want to exclude fields from the comparison so they are simply not considered in the comparison. This allows you to ignore differences in fields you don’t need to consider.
To exclude fields from comparison:
Alternatively, you can:
icon on the upper-right corner)It can be easier to provide a list of fields to include instead of excluding a large number of fields. The procedure is similar. In the Filter tab, be sure Include (instead of Exclude) is selected.
To set a large number of fields in one operation, use the 1-on-1 message comparison screen. For example, if you want to compare fields PID.2 to PID.13:
The comparison will refresh using the new field set.
After the comparison is completed, message pairs can have one of the following statuses:
On the bottom left of the screen, the message pair count for each status is listed.
Message pairs can be shown/hidden based on their status. For instance, to hide identical messages:
Identical messages are filtered so only changed and unmatched messages are listed.
During the validation phase, you compare transformed messages with another set of messages you already know are valid (golden message set). The highlighted differences will indicate any issues in your code or any missing transformations. This is a quick and easy way to validate that your code fulfills the requirements.
For a more detailed view of a message pair or message differences, double-click the message pair you want to compare. Navigate through the tree view, field by field, to see the differences.
Click on the gray zone at the bottom of the screen to view more details about each difference. Double-clicking on a grid row helps you navigate through the differences.
You may want to exclude fields from the comparison so they are simply not considered in the comparison. This allows you to ignore differences in fields you don’t need to consider.
To exclude fields from comparison:
Alternatively, you can:
icon on the upper-right corner)It can be easier to provide a list of fields to include instead of excluding a large number of fields. The procedure is similar. In the Filter tab, be sure Include (instead of Exclude) is selected.
To set a large number of fields in one operation, use the 1-on-1 message comparison screen. For example, if you want to compare fields PID.2 to PID.13:
The comparison will refresh using the new field set.
After the comparison is completed, message pairs can have one of the following statuses:
On the bottom left of the screen, the message pair count for each status is listed.
Message pairs can be shown/hidden based on their status. For instance, to hide identical messages:
Identical messages are filtered so only changed and unmatched messages are listed.
The Message Conformance validation lets you compare a received HL7 message against a profile in order to flag conformance gaps. This is useful when you need to troubleshoot data flow in a live interface where the conformance profile has been documented.
Validations are done on:
A list of warnings is produced. Each row is a broken profile conformance rule.
The Message Conformance validation lets you compare a received HL7 message against a profile in order to flag conformance gaps. This is useful when you need to troubleshoot data flow in a live interface where the conformance profile has been documented.
Validations are done on:
A list of warnings is produced. Each row is a broken profile conformance rule.
XML Validation configures a set of rules that validate that message content is as expected. Rules are associated to X-Path values.
You can create your validation from an existing message, which can simplify the process, or manually.
To create from a message:
To create manually:
You can edit the criteria by clicking on the cell to set a basic text value. In addition, you have access to the Variable Editor and the Criteria Editor, which are opened by right-clicking on the criteria cell. From there, you can insert a Variable or a Field Value criteria by specifying its location.
It may be necessary to temporarily disable a validation rule so it is no longer evaluated during test execution. To disable a rule, uncheck the check box in the very first column of the X-Path Validation table. To re-enable it, recheck the check box to the initial state.
You can use And, Or and Parentheses to perform more advanced conditions for your validations.
The Message Conformance validation lets you compare a received XML message against a profile in order to flag conformance gaps. This is useful when you need to troubleshoot data flow in a live interface where the conformance profile has been documented.
Validations are done on:
A list of warnings is produced. Each row is a broken profile conformance rule.
The Message Conformance validation lets you compare a received XML message against a profile in order to flag conformance gaps. This is useful when you need to troubleshoot data flow in a live interface where the conformance profile has been documented.
Validations are done on:
A list of warnings is produced. Each row is a broken profile conformance rule.
This is the most popular representation of an HL7 message using message, segment, field, component and sub-component delimiters. This encoding is usually referred to as a “pipe delimited” message.
Example:
The other allowed encoding uses HL7-XML.
This is a basic XML representation of an HL7 message where XML elements represent HL7 messages constructs like segments, fields and components.
Example:
<ADT_A01>
<MSH>
<MSH.1>|</MSH.1>
<MSH.2>^~&</MSH.2>
<MSH.3>
<MSH.3.1>MegaReg</MSH.3.1>
</MSH.3>
<MSH.4>
<MSH.4.1>XYZHospC</MSH.4.1>
</MSH.4>
<MSH.5>
<MSH.5.1>SuperOE</MSH.5.1>
</MSH.5>
<MSH.6>
<MSH.6.1>XYZImgCtr</MSH.6.1>
</MSH.6>
<MSH.7>
<MSH.7.1>20060529090131-0500</MSH.7.1>
</MSH.7>
<MSH.9>
<MSH.9.1>ADT</MSH.9.1>
<MSH.9.2>A01</MSH.9.2>
<MSH.9.3>ADT_A01</MSH.9.3>
</MSH.9>
<MSH.10>
<MSH.10.1>01052901</MSH.10.1>
</MSH.10>
<MSH.11>
<MSH.11.1>P</MSH.11.1>
</MSH.11>
<MSH.12>
<MSH.12.1>2.5 </MSH.12.1>
</MSH.12>
</MSH>
<EVN>
<EVN.2>
<EVN.2.1>200605290901</EVN.2.1>
</EVN.2>
<EVN.6>
<EVN.6.1>200605290900 PID</EVN.6.1>
</EVN.6>
<EVN.9>
<EVN.9.1>56782445</EVN.9.1>
<EVN.9.4>UAReg</EVN.9.4>
<EVN.9.5>PI</EVN.9.5>
</EVN.9>
<EVN.11>
<EVN.11.1>KLEINSAMPLE</EVN.11.1>
<EVN.11.2>BARRY</EVN.11.2>
<EVN.11.3>Q</EVN.11.3>
<EVN.11.4>JR</EVN.11.4>
</EVN.11>
<EVN.13>
<EVN.13.1>19620910</EVN.13.1>
</EVN.13>
<EVN.14>
<EVN.14.1>M</EVN.14.1>
</EVN.14>
<EVN.16>
<EVN.16.1>2028-9</EVN.16.1>
<EVN.16.3>HL70005</EVN.16.3>
<EVN.16.4>RA99113</EVN.16.4>
<EVN.16.6>XYZ</EVN.16.6>
</EVN.16>
<EVN.17>
<EVN.17.1>260 GOODWIN CREST DRIVE</EVN.17.1>
<EVN.17.3>BIRMINGHAM</EVN.17.3>
<EVN.17.4>AL</EVN.17.4>
<EVN.17.5>35 209</EVN.17.5>
<EVN.17.7>M~NICKELL’S PICKLES</EVN.17.7>
<EVN.17.8>10000 W 100TH AVE</EVN.17.8>
<EVN.17.9>BIRMINGHAM</EVN.17.9>
<EVN.17.10>AL</EVN.17.10>
<EVN.17.11>35200</EVN.17.11>
<EVN.17.13>O </EVN.17.13>
</EVN.17>
<EVN.24>
<EVN.24.1>0105I30001</EVN.24.1>
<EVN.24.2/>
<EVN.24.3/>
<EVN.24.4>99DEF</EVN.24.4>
<EVN.24.5>AN </EVN.24.5>
</EVN.24>
</EVN>
<PV1>
<PV1.2>
<PV1.2.1>I</PV1.2.1>
</PV1.2>
<PV1.3>
<PV1.3.1>W</PV1.3.1>
<PV1.3.2>389</PV1.3.2>
<PV1.3.3>1</PV1.3.3>
<PV1.3.4>UABH</PV1.3.4>
<PV1.3.8>3</PV1.3.8>
</PV1.3>
<PV1.7>
<PV1.7.1>12345</PV1.7.1>
<PV1.7.2>MORGAN</PV1.7.2>
<PV1.7.3>REX</PV1.7.3>
<PV1.7.4>J</PV1.7.4>
<PV1.7.7>MD</PV1.7.7>
<PV1.7.8>0010</PV1.7.8>
<PV1.7.9>UAMC</PV1.7.9>
<PV1.7.10>L</PV1.7.10>
</PV1.7>
<PV1.9>
<PV1.9.1>678 90</PV1.9.1>
<PV1.9.2>GRAINGER</PV1.9.2>
<PV1.9.3>LUCY</PV1.9.3>
<PV1.9.4>X</PV1.9.4>
<PV1.9.7>MD</PV1.9.7>
<PV1.9.8>0010</PV1.9.8>
<PV1.9.9>UAMC</PV1.9.9>
<PV1.9.10>L</PV1.9.10>
</PV1.9>
<PV1.10>
<PV1.10.1>MED</PV1.10.1>
</PV1.10>
<PV1.15>
<PV1.15.1>A0</PV1.15.1>
</PV1.15>
<PV1.17>
<PV1.17.1>13579</PV1.17.1>
<PV1.17.2>POTTER</PV1.17.2>
<PV1.17.3>SHER MAN</PV1.17.3>
<PV1.17.4>T</PV1.17.4>
<PV1.17.7>MD</PV1.17.7>
<PV1.17.8>0010</PV1.17.8>
<PV1.17.9>UAMC</PV1.17.9>
<PV1.17.10>L</PV1.17.10>
</PV1.17>
<PV1.44>
<PV1.44.1>200605290900 </PV1.44.1>
</PV1.44>
</PV1>
<OBX>
<OBX.1>
<OBX.1.1>1</OBX.1.1>
</OBX.1>
<OBX.2>
<OBX.2.1>NM</OBX.2.1>
</OBX.2>
<OBX.3>
<OBX.3.2>Body Height</OBX.3.2>
</OBX.3>
<OBX.5>
<OBX.5.1>1.80</OBX.5.1>
</OBX.5>
<OBX.6>
<OBX.6.1>m</OBX.6.1>
<OBX.6.2>Meter</OBX.6.2>
<OBX.6.3>ISO+</OBX.6.3>
</OBX.6>
<OBX.11>
<OBX.11.1>F </OBX.11.1>
</OBX.11>
</OBX>
<OBX>
<OBX.1>
<OBX.1.1>2</OBX.1.1>
</OBX.1>
<OBX.2>
<OBX.2.1>NM</OBX.2.1>
</OBX.2>
<OBX.3>
<OBX.3.2>Body Weight</OBX.3.2>
</OBX.3>
<OBX.5>
<OBX.5.1>79</OBX.5.1>
</OBX.5>
<OBX.6>
<OBX.6.1>kg</OBX.6.1>
<OBX.6.2>Kilogram</OBX.6.2>
<OBX.6.3>ISO+</OBX.6.3>
</OBX.6>
<OBX.11>
<OBX.11.1>F AL1</OBX.11.1>
</OBX.11>
<OBX.12>
<OBX.12.1>1</OBX.12.1>
</OBX.12>
<OBX.13/>
<OBX.14>
<OBX.14.2>ASPIRIN DG1</OBX.14.2>
</OBX.14>
<OBX.15>
<OBX.15.1>1</OBX.15.1>
</OBX.15>
<OBX.17>
<OBX.17.1>786.50</OBX.17.1>
<OBX.17.2>CHEST PAIN, UNSPECIFIED</OBX.17.2>
<OBX.17.3>I9</OBX.17.3>
</OBX.17>
<OBX.20>
<OBX.20.1>A</OBX.20.1>
</OBX.20>
</OBX>
</ADT_A01>
Variables are symbolic names to which a value can be assigned. Variables can be used to:
Variable are in the ${variable_name} format
There are 2 variable types:
System variables are quite useful to get contextual information regarding the suite execution. This variables can be used to improve tasks reusability and speed up test definition. Use them to build:
Here is the list of system variables:
| Variable Name | Description |
| ${CxScenarioSuiteName} | Name of the Scenario Suite |
| ${CxScenarioName} | Name of the task’s parent Scenario |
| ${CxScenarioIteration} | Current running iteration number for the Scenario |
| ${CxActionName} | Name of the task’s parent Action |
| ${CxActionIteration} | Current running iteration number for the Action |
| ${CxTaskName} | Name of the Task |
| ${CxToday} | The current Date |
| ${CxNow} | The current Date and Time |
Using system variables, the last inbound and outbound messages are also accessible:
[Deprecated] – Use Criteria Editor
| Variable (including example) | Description |
| ${CxLastOutboundMessage[%FIELD%]} | |
| ${CxLastOutboundMessage[%MSH.3%]} | Returns content of MSH.3 from the last outbound message (last message sent) |
| ${CxLastOutboundMessage[%OBX[2].5[3]%]} | OBX segment and OBX.5 being both repeatable, it returns content of 3rd repetition of OBX.5 in the 2nd OBX segment of the last outbound message |
| ${CxLastInboundMessage[%FIELD%]} | |
| ${CxLastInboundMessage[%PID.3%]} | Returns content of PID.3 from the last inbound message (last message received) |
| ${CxLastInboundMessage[%PID.3[3].4%]} | PID.3 being repeatable, this expression returns content of the 4th component of the 3rd repetition of PID.3. |
User-defined variables are variables managed by the test scenario builder. Variables allow the application to create message content and field values at run time, so that you can perform tests without having to create multiple messages yourself. Values assigned to user-defined variables are managed by generators.
| Variable Type Name | Description |
| String | A set of characters |
| Char | A single character |
| Boolean | True or False |
| Int | Number between -2,147,483,648 and 2,147,483,647 |
| Long | Number between –9,223,372,036,854,775,808 and 9,223,372,036,854,775,807 |
| Double | A 15 digit number between ±5.0 × 10−324 and ±1.7 × 10308 |
| Date Time | Calendar date between January 1, 0001 and December 31, 9999 |
| Mapping Table | A 2-column table where each row contains an initial value and its equivalent mapping value |
| Environment Variable | A set of values for which the used value is determined by the active environment. |
| Generator | Recommended Use |
| Boolean | Insert a Boolean value (true or false). |
| Date Time | Insert a randomly generated date-time value. You can set the range, time unit, format, and other parameters. |
| Directory Listing | Iterate through files in a specified directory. |
| Excel File | Pull random data from an Excel 2007+ spreadsheet — for instance, a list of names, addresses, and cities. |
| Numeric | Insert a randomly generated number. You can set the length, decimals and other parameters. |
| SQL Query | Pull data from a database based on an SQL query. You’ll be able to configure a database connection. |
| String | Insert a randomly generated string or static value. You can set the length and other parameters. |
| Substring | Insert a part of another variable. |
| Table | Pull data from HL7-related tables stored in one of your profiles, useful for coded fields. |
| Text File | Pull random data from a text file — for instance, a list of names. Several file formats can be used: txt, csv, etc |
Note: Advanced Mode allows you to combine several generators to generate complex value formats. For instance, a patient ID with the format XXX-9999-M can be generated by combining Excel, numeric and string generators.
Generators are algorithms or data sources used to assign variables with values. Several generators are available:
In Advanced Mode, you can generate data with complex data formats by combining generators for a single variable. For instance, a patient ID with the format XXX9999M (3 random characters, a number between 0000 and 9999 plus a static character at the end) can be generated by combining Excel, numeric, and string generators.
To combine generators:
Change the generator order by dragging and dropping them in the generator chain.
Use the Generator formatting field to add more formatting. You can create sophisticated values that mimic unstructured data using this functionality. Formatting can be quite powerful.
| Generator | Formatting | Generated Value | Description |
| Numeric 0-99 | He is {0} years old | He is 34 years old He is 17 years old He is 88 years old | {0} is replaced with the generated value |
| Numeric 0-99 | {0} + {0} = 2*{0} | 34 + 34 = 2*34 17 + 17 = 2*17 88 + 88 = 2*88 | A generator can be used several times |
| Numeric 0-99 | {0:D5} | 00042 93277 03007 15432 | Adding leading zeros so the values has 5 digits |
| String (length=1) Numeric 0-99999 | {0} – {1} | P – 22 C – 42 I – 1 L – 82 | Generators are combined and formatting is added |
| Excel (first name) Excel (last name) | {1}^{0} | Doe^John Smith^Suzan | Generators are combined to create a field value having 2 components (subfields) |
This generator creates a Boolean (True or False) value.
| Example #1: | Generated Values |
| True True False True False |
This generator uses user-defined environments and allows you to map values specific to those environments for a given variable. This allows for efficient re-use of tests that are based on different development environments (Development, Production, etc.)
To use this generator, you first need to define environments to which you will map the variables. To do so, open the environment editor.
This will create default environments to work in. You can modify or delete these environments, and you can define your own environments if you want.
Now, you can create a variable of type Environment Variable and define it with the Environment Variable value generator.
To make use of this variable, you need to assign values to existing environments in the value generator.
Finally, select an environment in which you run the scenario suite.
In this case, running with the Development environment will assign the value mysite.dev.mydomain.com to the ${HL7ConnectorUrl} variable.
This generator uses user-defined environments and allows you to map values specific to those environments for a given variable. This allows for efficient re-use of tests that are based on different development environments (Development, Production, etc.)
To use this generator, you first need to define environments to which you will map the variables. To do so, open the environment editor.
This will create default environments to work in. You can modify or delete these environments, and you can define your own environments if you want.
Now, you can create a variable of type Environment Variable and define it with the Environment Variable value generator.
To make use of this variable, you need to assign values to existing environments in the value generator.
Finally, select an environment in which you run the scenario suite.
In this case, running with the Development environment will assign the value mysite.dev.mydomain.com to the ${HL7ConnectorUrl} variable.
This generator creates date and time values.
| Example #1: | Generated Values | Description | ||||||||||
|
| |||||||||||
| Example #2: | Generated Values | Description | ||||||||||
|
| |||||||||||
| Example #3: | Generated Values | Description | ||||||||||
|
| |||||||||||
When the generator exceeds the maximum value (30), the sequence is reset starting at the minimum value (0). | ||||||||||||
| Example #4: Manipulate date of birth | Original field Value | Generated Value | ||||||||||
|
| |||||||||||
This generator pulls data from an Excel 2007+ file (*.xlsx).
Note: If more than one field is configured using the same worksheet, the same row will be applied across a message. In other words, you can use an Excel file to ensure that several values will be used together. This is useful when you need to link a city with a zip code or a first name with a gender.
The examples below use the following content from a file named C:MyDocumentsmyExcelFile.xlsx
| 1 | Road Runner | M | ACME | Anycity | 12345 |
| 2 | The Coyote | M | ACME | Anycity | 12345 |
| 3 | Sylvester The Cat | M | ACME | Anycity | 12345 |
| 4 | Tweety Bird | M | ACME | Anycity | 12345 |
| 5 | Jane Doe | F | Anothercity | 98765 | |
| 6 | John Smith | M | Anothercity | 98765 |
Example #1: | Generated Values |
| John Smith Jane Doe Road Runner The Coyote Tweety Bird |
| Example #2: | Generated Values |
| M M M M F M |
This generator creates a number.
| Example #1: | Generated Values |
| 10.34 15.2 20.85 25.39 30.12 |
| Example #2: | Generated Values |
| 353 942 359 626 967 |
This generator pulls data from an SQL-accessible database.
| Example #1: | Generated Values |
| John Smith Jane Doe Road Runner The Coyote Tweety Bird |
This generator creates a uppercase character string to be used to set a static value.
How to use the “String” generator to set a static value:
| Example #1: | Generated Values |
| XDZ VOJHZ BFAR |
| Example #2: | Generated Values |
| MyNewValue |
This generator retrieves a part of another variable value.
The following examples use a pre-defined variable:
| Example #1: | Generated Values |
| FacilityA |
| Example #2: | Generated Values |
| cility |
This generator lists files in a directory, where the name of the files match a specified pattern.
This generator pulls data from HL7-related tables stored in a profile. Read how to set the profile.
| Example #1: | Generated Values |
| N M A F A |
| Example #2: | Generated Values |
| A F M N O |
This generator pulls data from a text file (*.txt, *.csv, etc).
Note: If more than one field is configured using the same text file, the same line will be used within the same message. In other words, you can use a text file to ensure several values will be used together. This can be useful when linking a a city with a zip code or a first name with a gender.
The examples below use the following content in a file C:MyDocumentsmyFile.txt
| 1 | Road Runner | M | ACME | Anycity | 12345 |
| 2 | The Coyote | M | ACME | Anycity | 12345 |
| 3 | Sylvester The Cat | M | ACME | Anycity | 12345 |
| 4 | Tweety Bird | M | ACME | Anycity | 12345 |
| 5 | Jane Doe | F | Anothercity | 98765 | |
| 6 | John Smith | M | Anothercity | 98765 |
| Example #1: | Generated Values |
| John Smith Jane Doe Road Runner The Coyote Tweety Bird |
| Example #2: | Generated Values |
| M M M M F M |
The Criteria Editor is used to construct string-value using Carlang expressions.
Carlang is an excel-like function language. With Carlang, you are able to retrieve HL7/XML/JSON/DataSet values from a specified task/field. Currently, there are some functions available:
This function is used to convert a date value from any executed task in the scenario suite. The function has 3 parameters.
EX: @ConvertDateTime(“20200428011122-0500”, “HL7”, “FHIR”) 🠖 2020-04-28T01:11:22-05:00
@ConvertDateTime(“2021-04-20”, “yyyy-MM-dd”, “MM-dd-yyyy”) 🠖 04-20-2021
This function is used to retrieve a value from an SQL Query result-set. The function has 4 parameters:
This function is used to encode a raw value to a base64 value from any executed task in the scenario suite. The function has 1 parameter.
This function is used to retrieve an HL7 field value from any executed task in the scenario suite. The function has 2 parameters.
Hl7 Field syntax is SEGMENT_NAME[SEGMENT_REPETITION].FIELD_POSITION[FIELD_REPETITION].COMPONENT_POSITION.SUB_COMPONENT_POSITION
This function is used to retrieve a JSON-Path value from any executed task in the scenario suite. The function has 2 parameters.
This function is used to retrieve an X-Path value from any executed task in the scenario suite. The function has 2 parameters.
This function is used to retrieve a string value from any executed task in the scenario suite. The function has 1 parameter.
When finished, click on insert to add it to the criteria. You can then insert another Field Value or text. When you are done editing, click on Apply to close the editor and apply the changes.
To check that PID.2 and PID.4 of a sending task named “Send Task 1”, have been properly merged and separated by a dash in the Z01.1 field of the current task:
So, if PID.2 is “ABC” and PID.4 is “123”, then the runtime validation would be: Z01.1 is = ABC-123
Right-click the name of the Scenario suite, the Scenario, the Action or the Task you wish to execute. Click Run.
You can stop a test mid-way or at any time. Simply right-click on a node and select Stop.
After a test is executed, you can generate an execution report:
The generated report is an Excel document containing descriptions of the test and all results.
| Column Name | Description |
| Name | The name of the suite, scenario, action or task executed. |
| Status | Status of the node. A node inherits status from its children. If a task fails, the parent action, scenario and suite status will also fail. |
| Documentation | Any documentation added to the node and last execution time. |
| Configuration | Network connection parameters that were used. Messages specified in the Configuration tab (including variables), if any. |
| Execution | Message Sent where all variables are instantiated. It’s exactly what was sent on the port. |
| Validation | Last Result Validation rules and statuses for each of them |
| Time | Execution elapse time spent on the task, action, scenario or suite |
You can also run your Scenario Suite using the command line application (TestConsole.exe) located in the Test installation folder (%PROGRAMFILES(X86)%CaristixCaristix Test or %PROGRAMFILES%CaristixCaristix Test). Simply call the application by providing the Scenario Suite to run in argument:
TestConsole.exe “C:MyScenarioSuite.cxs”
Use TestConsole.exe -h for more information.
Use the Message Maker tool to create test messages to PLACE INTO a scenario or to copy to another application. The messages you generate will be based on a specific profile (an HL7 version based on the reference standard, or a profile created in Caristix Conformance or Caristix Workgroup software).
In most of your test automation work, you will want to use variables to populate test workflow with data. But if you need to generate HL7 messages to copy to another application, use Message Maker. Also use Message Maker if you want to use the same test data over and over again in a test scenario created with Caristix software.
Before starting to use Caristix Test, review Options to ensure your setup is appropriate for your testing and validation.
From the Main Menu, click Tools, then Options in the drop-down menu that appears.
A new Options window opens. 4 tabs are available: Logging, Reference Profile, Default Connections and Preferences.
Enabling this configuration activates internal execution log storage. Internal execution logs are actually xml files and can be open as a test suite so the test can be run again using the exact same configuration, meaning that variables are replaced with the actual values generated at run time.
This is the default profile used to validate and create new messages. Reference conformance profiles based on the HL7 standard are located here. Also, any other profile the organization may have created would be listed here too.
To know more about how to create new customized profiles (including Z-segments and customized fields), refer to the Caristix Conformance or Caristix Workgroup products.
This is where connections to integration engines (or other HL7 systems) and databases are configured. Configuring a default connection for each category has a few advantages:
Database ConnectionsCaristix Test can perform tasks against a database. For instance, you can execute a SQL query to validate against expected results; or you can instantiate a variable from a data set. These settings enable you to set up database connection library and select a default database.
Caristix Test can interact with an integration engine or a system sending HL7 messages. These settings enable you to set up the network connection library and select one as the default.
Choose the default receiving network connection from the list of network connections. To configure a new network connection:
| Property | Description | Example |
| Name | This is the name of the network connection. Later, network connection can be selected using the name. | EMR Simulator Local Listener |
| Host | IP address or hostname listener will listen to. Note: Make sure firewalls are configured so traffic from the message sender computer can reach the host and port the listener is listening to | 127.0.0.1 127.0.0.0 192.168.10.210 |
| Port | Port listener will listen to. Note: Make sure firewalls are configured so traffic from the message sender computer can reach the host and port the listener is listening to | 6661 6543 |
| Timeout | Listener stops listening to the address/port after this period of time (in seconds) even if it did not receive anything | 30 |
Caristix Test can interact with an integration engine or a system receiving HL7 messages. These settings enable you to set up the network connection library and select one as the default.
Choose the default sending network connection from the list of network connections. To configure a new network connection:
| Property | Description | Example |
| Name | This is the name of the network connection. Later, network connection can be selected using the name. | ADT Simulator Local Sender |
| Host | IP address or hostname messages wil be sent to. Note: Make sure firewalls are configured so traffic from the computer running tests can reach the host and port | 192.168.10.210 dev.myorg.com 127.0.0.1 |
| Port | Port messages will be sent to. Note: Make sure firewalls are configured so traffic from the computer running tests can reach the host and port | 6661 6543 |
| Timeout | Connect will stop waiting for acknowledgment messages after this period of time (in seconds) if it didn’t receive anything | 30 |
There is a lot of test automation power under the hood with Caristix Test. Looking for examples to get started with the application? Here are a few to illustrate what to do and how to do it.
Feel free to contact us if you are looking for more How To article that are not included here. We love hearing from our users. The best way to reach us is: support@caristix.com.
Some tutorials to help you with some common tasks.
These examples walk you through a series of typical validation activities.