You can add documents (Word, Excel, PDF documents, etc.) to the Library. You can do so using one of the following ways:
Documents will be uploaded to the library and made available from Workgroup.
Documents and folders will be uploaded to the library and made available from Workgroup.
Document(s) will not be uploaded to the server and will only be available from your computer. Other user from the same library will see the shortcut, but won’t be able to open it. This will act as a normal shortcut in Windows.
There are actions that can be performed on the library via the Main Menu’s Action section, the right-click contextual menu (right-click a node or blank space), and the Gear icon beside the search bar.
When there is no document highlighted, the available actions are:
When a document is selected, the available actions depends on the document type. Common actions are:
The foundation of Caristix software is profiles. Profiles are another word for interface specifications, specs, or conformance profiles. They are a way to capture the data formats and code sets you need for exchanging information between systems. Profiles provide a list of message types (or trigger events), segments, fields, components, sub-components, data types, and data tables that are specific to a system. The profiles you develop with Caristix software can be used to:
You can either build a spec manually by reading sample HL7 messages over the course of a few days, or you can use Caristix software to automatically build one for you, using the reverse-engineering functionality in our software. Learn about the tasks related to building, scoping, and updating specifications as follows:
In Caristix software, profiles serve as interface documentation. The Library is a repository for all interface specifications: HL7 reference specifications (which come built into Caristix Workgroup software), product specifications, and specifications for the customized mapping and configuration that must occur for working interfaces as well as any other type of documentation file.
There are several ways to create a profile or specification:
This method is useful when you have a large volume of message types and trigger events to document, based on a specific HL7 version. If your specification is more limited, consider building a profile from individual message elements.
You will need to edit the profile to reflect the specification. Go to Editing a Profile to learn more.
You can also build a profile from individual message elements. This method is useful when the specification you are building is limited to a small subset of an HL7 version and when customization is extensive
You can add a trigger event or message type from one of the HL7 references or from a previously built profile.
In the Documents pane, double-click on the profile you want to build out.
In the Profile Explorer, right-click on the first node.
| Mode | Why Choose This Option | Action | Example |
| Import only missing definitions | Choose this if you only want to import element that don’t already exists in your profile | This will import definitions that are not present in the current profile and all referenced elements. | Your profile doesn’t have a ADT_A01 trigger event you’d like to add from HL7 v2.6. |
| Replace all definitions | Choose this if you need to replace all existing definitions with the imported definitions. | Replace existing elements by imported elements. This means that you’ll overwrite current definitions. The segment definition will change to the imported definition. | Your profile has an ADT_A08 definition that would like to replace by the one from v2.6. |
| Blend definitions | Choose this if you need to import a definition from another profile, but also need to keep all definitions from both profiles. | This will import all selected and referenced definitions and will duplicated all elements that are different. | Your profile has a custom ADT_AZZ definition from one source system. A second source system uses a different definition. You need to code an interface for both definitions. |
You can add an event or message without segments, fields, associated data types, or tables. These elements must be defined later. Use this method when the event to be specified has not been formally defined in the HL7 standard.
In the Document pane, double-click on the profile you want to edit. Right-click on the first node and select Add, Trigger Event. A new trigger event is added.
Rename the trigger event and add a description.
Once you have added trigger events, you can edit segments, fields, and data types within your profile. See Editing a Profile for more information.
The Reverse Engineering tool enables you to create a profile from an HL7 log (or HL7 message file). A profile (also known as a specification or message definition) documents the message structure and content, including the use of Z-segments and custom data types.
To open the Reverse-Engineering tool, click PROFILE v2, New, With Reverse-engineerer Wizard... The tool opens to Choose Log Files.
Then click Next to go to the next step. You can also load messages by querying a database.
To begin building a profile based on the messages you just loaded, the software needs an established profile to compare against. Select a profile that most closely matches your messages, then click Next. (Note: the software picks up on the HL7 version specified in your messages, but you are free to choose another reference).
The messages load.
(If they load too slowly, you can click the Cancel button in the Loading dialog box and only messages that have loaded thus far will appear.)
If there are files, events, segments, or other data elements you don’t require for the profile, filter them out in this step (read Filter an HL7 Log to learn more), then click Next to go to the next step. To reverse-engineer all messages without filtering, simply click Next.
This step is optional. The software will detect all sending and receiving applications present in the messages. If only one combination is detected, this step is skipped.
You have two options here. You can either generate a single profile combining all applications represented in the message file, or you can create separate profiles for each sending and receiving application combination. The second option offers you the possibility to choose specific combinations; it will also run the next 5 steps consecutively for all selected combinations.
The software sets up the reference profile and messages you selected. Once the processing is complete, simply click Next to continue, as specified on-screen.
Choose between Basic and Advanced field analysis.
This choice lets you analyze fields and data values and assign known data types. If Conformance finds data values and fields that do not match known data types, an new data type will be assigned. You can manually edit the data types later, when the reverse-engineering profile appears in the Library.
Select Basic Field Analysis if:
you are not sure that data types are important to your analysis.
you want to speed up your analysis and focus on identifying details in other message elements such as events and segments.
This choice lets you fully analyze fields and data values. Data values and fields that do not match expected data types will be flagged. You will have the opportunity to either create custom data types to handle non-HL7-compliant data, or assign an existing data type.
Select Advanced Field Analysis if:
you need complete data type analysis for your interfacing project
you are comfortable creating new data types for further analysis
This section allows you to set more specific options for data and field analysis.
Once you make your selection in Step 2, click Next.
The software reads through the messages and segments to begin building the profile. When processing is complete, click Next to continue, as specified on-screen.
This step creates the field structure in your profile, assigns data values to user tables, and associates data types to fields and values.
If you selected Basic Field Analysis in Step 3, Basic Mode appears in Step 4. Workgroup processes the fields and data types automatically. When the processing is finished, click Next.
If you selected Advanced Field Analysis in Step 3, Advanced Mode appears in Step 4. Workgroup analyzes each segment for data values and fields that do not match expected data types. In other words, the software automatically performs a conformance check. When non-compliant elements are flagged, the software automatically suggests a data type and field structure. You can accept the suggestion, assign another data type, or create a new data type to handle the non-compliant values and fields.
Edit as needed to reflect maximum field length
Specify usage.
This tab provides a list of the data values that were flagged as non-compliant, as well as how many times they were found in the messages.
When processing is complete, click Next to continue.
This step will collect analyze the message flows in your logs (if you select this option at step 2). These message flows will be stored into the profile and available for future uses, to generate test messages for example.
This is the final step in the Reverse-Engineering wizard. Specify a folder to save the profile to or browse your computer to save it locally. Name the profile. And provide a description if needed. Click Save to close the Reverse-Engineering wizard and go to the Documents pane. (If multiple Sending and Receiving Applications were selected, the wizard will start a new analysis on Step 1)
When the reverse engineering wizard is run, you have the option of filtering out unneeded data values, trigger events, and segments. These data elements may not be needed for the profile you are creating, despite their presence in the HL7 message log.
Data filters let you set up queries to find messages containing specific data. Queries can filter on specific message building blocks: segments, fields, components, and subcomponents.
| Operator | Action |
| is | Includes messages that contain this exact data |
| is not | Excludes messages that contain this data |
| = < > =< >= | Filters on numeric values |
| like | Covers messages that include this data somewhere in the element (ex: 42 in 4342, 3421, 4286) |
| present | Looks for presence of a message element (such as segment, field, etc.) |
| empty | Looks for unpopulated message elements (such as a segment, field, etc.) |
| in | Filter on multiple data values in a message element rather than a single value |
| regex syntax | .NET regular expression syntax, equivalent to wildcard expressions |
The data sorting functionality lets you set up sort queries on data values.
You can use an existing Search and Filter Rules file or save newly created rules throughout the Reverse Engineering filtering step. To do so, right-click anywhere in the Data Filters, Sorts or Data Distributions section.
In order to use a profile created in another installation of the application, you will need to import the file.
In Caristix software, profiles serve as interface documentation. The Library is a repository for all interface specifications: HL7 reference specifications (which come built into Caristix Workgroup software), product specifications, and specifications for the customized mapping and configuration that must occur for working interfaces as well as any other type of documentation file.
There are two ways to add segments, depending on your needs. You can either add a segment defined in the profile you’re working on, or add one from a different profile.
Start here:
To create a new Segment definition, click on Add Segment, New. A new Segment definition appears at the bottom of the list.
You can also create a copy of an existing Segment definition by right-clicking on the source definition, select Copy and then right-click again and select Paste. A new Segment definition appears at the bottom of the list.
| Mode | Why Choose This Option | Action | Example |
| Import only missing definitions | Choose this if you only want to import element that don’t already exist in your profile. | This will import definitions that are not present in the current profile and all referenced elements. | Your profile doesn’t have a PID segment you’d like to add from HL7 v2.6. |
| Replace all definitions | Choose this if you need to replace all existing definitions with the imported definitions. | Replace existing elements with imported elements. This means that you’ll overwrite current definitions. The segment definition will change to the imported definition. | Your profile has an XPN definition that you would like to replace with the one from v2.6. |
| Blend definitions | Choose this if you need to import a definition from another profile, but also need to keep all definitions from both profiles. | This will import all selected and referenced definitions and will duplicate all elements that are different. | Your profile has a custom ZOD definition from one source system. A second source system uses a different definition. You need to code an interface for both definitions. |
This is useful when you need to add a new data type for a Z-segment or a custom field.
| Mode | Why Choose This Option | Action | Example |
| Import only missing definitions | Choose this if you only want to import elements that don’t already exist in your profile. | This will import definitions that are not present in the current profile and all referenced elements. | Your profile doesn’t have a TS (time-stamp) data type you’d like to add from HL7 v2.6. |
| Replace all definitions | Choose this if you need to replace all existing definitions with the imported definitions. | Replace existing elements with imported elements. This means that you’ll overwrite current definitions. The segment definition will change to the imported definition. | Your profile has an HD definition that would like to replace by the one from v2.6. |
| Blend definitions | Choose this if you need to import a definition from another profile, but also keep all definitions from both profiles. | This will import all selected and referenced definitions and will duplicated all elements that are different. | Your profile has a custom TS definition from one source system. A second source system uses a different definition. You need to code an interface for both definitions. |
This is useful when you need to add a new table for a Z-segment.
Edit segments and fields, so you capture the data elements pertinent to your specification. Due to the nature of the HL7 standard (HL7 is object-oriented), any changes made are global changes and affect the entire profile.
There are two ways to access segments and fields:
Click the “+” sign to expand a message, then edit the segment.
Right-click a message, and select Segment... A separate window displays the Segment Library. Expand the segment you wish to edit by clicking the plus sign.
To edit each field or individual component, click on the title. Under the Configuration tab, make the changes to each field attribute.
This is useful when you want to reduce the profile to relevant trigger events.
From the Validations tab, you can configure a set of rules that validate message content (data) is conform.
In the following example, the rule will validate (and raise conformance gaps) if the MSH.7 of a message does not conform to the format “yyyy-mm-dd hh:MM:ss”
Operators let you define validation rules whether they range from simple to complex.
| Operator | Action |
| is | Valid that contain this data |
| is not | Valid that does not contain this data |
| = | Valid with an exact match to this data (this is like putting quotation marks around a search engine query) |
| < | Less than. Covers validating on numeric values. |
| <= | Less than or equal to. Covers validating on numeric values. |
| > | Greater than. Covers validating on numeric values. |
| >= | Greater than or equal to. Covers validating on numeric values. |
| like | Valid if includes this data. Covers validating on numeric values. |
| present | Looks for the presence of a particular message building block (such as a field, component, or sub-component) |
| empty | Looks for an unpopulated message building block (such as a 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 Profile. |
| matching regex | Use .NET regular expression syntax to build validations. To be used by 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: |
The JavaScript engine allows you to create custom validation rules, which will be used during the conformance validation of your HL7 messages.
You can add custom javascript validation rules at the profile, trigger-event, segment and data-type levels. The javascript rules will be evaluated during the HL7 message validation, depending on the element of the message being validated.
Profile: Validation rules added at the Profile level will be evaluated first and only once per message.
Trigger-Event: Validation rules added at the Trigger-Event level will be evaluated only once per message and will only be evaluated for matching messages. The MSH.9 – Message Type is used to match messages and trigger-events.
Segment: Validation rules added at the Segment level will be evaluated for each instances of the segment in a message.
Data-Type: Validation rules added at the Data-Type level will be evaluated for each instances of the data-type in a message.
By using the callback() method, you can notify the message validator when an error has occurred. You can provide callback() with an error message as a string, or with a ValidationError object.
During HL7 message validation, the JavaScript engine context is updated, allowing you to access the current element being validated. The context has the following properties you can refer to:
The ValidationError allows you to return a customized validation error in the callback method. The ValidationError object exposes the following properties and methods:
Returns a new, empty ValidationError.
var validationError = new ValidationError();
callback(validationError);
// Returns a new ValidationError object in the callback method.
A summary of the error.
var validationError = new ValidationError();
validationError.summary = 'Invalid Medical Number';
// The validation error's summary should be 'Invalid Medical Number'
A detailed description of the error.
var validationError = new ValidationError();
validationError.description = 'PID.3 does not contain a valid MR - Medical Number for the patient';
// The validation error's description should be 'PID.3 does not contain a valid MR - Medical Number for
// the patient'
Methods
Returns the JSON string value of the ValidationError.
var validationError = new ValidationError();
validationError.description = 'PID.3 does not contain a valid MR - Medical Number for the patient';
var validationErrorString = validationError.toString();
// validationErrorString should be '{ "description":"PID.3 does not contain a valid MR - Medical Number for the patient"}'
When you publish a profile report to Word, you may need to edit descriptions in Word then save those edits to the corresponding profile. This is done using the Synchronize function.
The synchronization feature uses internal Word document markups so it can relate any change to the right profile section. When updating the document, make sure the document structure is preserved. It is suggested that you experiment with this functionality before starting document updates on a large scale. For instance:
When you publish a profile report to Word, you may need to edit descriptions in Word then save those edits to the corresponding profile. This is done using the Synchronize function.
The synchronization feature uses internal Word document markups so it can relate any change to the right profile section. When updating the document, make sure the document structure is preserved. It is suggested that you experiment with this functionality before starting document updates on a large scale. For instance:
Extra Content enables you build profiles that include more than the official HL7 content.
Basic profiles, without Extra Content, enable you to define message-related structure and content through trigger events, segments, fields, tables, etc. In turn, each of those elements are described through attributes such as Sequence, Name, Optionality, etc. software include set of attributes describing profiles and profile entities. Extra Content lets you add new elements and new attributes.
For instance, you may want to add a change history table to a profile, in order to track changes over time. Or you might want to add an extra column to store source descriptions for code set values. Both of these can be added using Extra Content. This content will be displayed as part of the profile, exactly the same way standard HL7-related elements and attributes are displayed.
An Extra Content Template is a set of extra elements and attributes that you bundle together.
The Extra Content template itself doesn’t contain any data. Instead it defines the containers (or placeholders) for your data. An Extra Content Template represents the structure of the content you add to a profile. You can set up a Template and use it across one or more profiles. Once a profile is associated with an Extra Content Template, you can enrich the profile definition by populating the Extra Content areas.
Please refer to the following sections for more information: