Workflows
At Retrohook, our fundamental unit of work is something we call a Workflow. The task at hand for a workflow is ingesting healthcare data, performing some mappings, and making the data available to your application.
In computer science, there is a common, well-understood design pattern for this type of workflow called Extract, Transform, and Load, or ETL. And indeed, our Workflows are built using this familiar pattern.
Configuration with Retrohook
Overview
In the Retrohook platform, the 'Details' page is where you begin configuring the specifics of a Workflow. A Workflow is a process that handles the ingestion, transformation, and loading of healthcare data for use by your application. This section guides you through setting up the foundational details of your Workflow.
Workflow Details Configuration
-
Naming Your Workflow
Enter a unique and descriptive name for your Workflow in the 'Name' field, such as "Patient Admission Processing" or "Lab Results Distribution". This will help you and your team identify the Workflow's purpose at a glance. -
Selecting an Extract Event
Use the dropdown menu to select the event type that will trigger your Workflow. For example, if you're using the MLLP Adapter, this means the Workflow will start when a message is received over an MLLP connection. -
Choosing a Load Action
Determine what should happen to complete the Workflow. If you select 'HTTP POST', for example, Retrohook will forward the processed data to a specified endpoint URL. -
Sample Message
The 'Sample Message' field provides an area to input a typical message that your Workflow is expected to handle. This helps in testing and ensures your Workflow can process actual data formats you will use. Paste a relevant HL7 message or other data format into this field. This might be an HL7 v2.x admission message, lab order, or result message, depending on your Workflow's purpose. -
Saving Your Workflow
Once you have filled in all the details, click 'Create' to record your changes. It's a good practice to verify the details before saving to ensure that the Workflow will function as intended. -
Navigating Through Workflow Configuration
After saving your Workflow details, you can continue configuring your Workflow by navigating to the 'Event', 'Mapping', and 'Action' tabs, which will be covered in subsequent documentation sections.
Configuring Workflow Extract Events in Retrohook
Overview
The 'Extract' page in the Retrohook platform is where you define the criteria for triggering a Workflow. This involves specifying which types of messages will initiate the Workflow, based on various HL7 message segments and their respective fields. Proper configuration ensures that only relevant messages prompt the Workflow to execute its tasks.
You'll notice the sample message you uploaded has been mapped to the appropriate segment and place in the HL7 message.
Event Configuration
-
Specifying Trigger Condition
Input or confirm the unique identifier for messages that should trigger the Workflow, such as a specific ID in the MSH.8 field. This filter is required. All messages sent to Retrohook must have this code included for the Workflow to trigger. You may customize this trigger in your Workspace trigger, but you must include one. It's recommended to make it highly unique when utilizing our Free tier to avoid any collisions. -
Applying Additional Filters (Optional)
For more refined control, apply filters to each field by inputting filter criteria. This can be useful for including or excluding specific messages based on advanced criteria like regex patterns. For instance, to process only ADT messages, go to the appropriate segment (often MSH.9.1) and type in ‘ADT'. Your sample message would have the value loaded in the Sample column, so this will not require much thought. -
Saving the Event Configuration
After setting up the event triggers and filters, click 'Save' to apply the configuration to your Workflow. Ensure that all fields are correctly filled in to prevent any unintended Workflow behavior.
Support and Troubleshooting If you encounter any issues with configuring events or if the Workflow is not triggering as expected, please consult our detailed documentation or reach out to Retrohook support for assistance.
Transforming Data Fields in Retrohook Workflows
Overview
The 'Transform' section of a Retrohook Workflow is where you define how data from incoming messages is translated or transformed to fit the needs of your system or application. This crucial step ensures that data is correctly interpreted and utilized downstream in your processes.
Data Mapping Configuration
Understanding the Mapping Interface
The interface lists the HL7 fields in your sample message, such as MSH.2 (Encoding Characters), MSH.3 (Sending Application), etc. Each field has a corresponding 'Specification' and 'Sample' column, illustrating the location in the HL7 data format and the sample value, respectively.
Specifying Target Keys
For each HL7 field, input the corresponding target key in the 'TARGET KEY' column. This is the key under which the data will be stored or referenced in your application or system. Utilize the same values across workflows to standardize or normalize your data for ingestion from the Load Action. Use the gear icon to access advanced options for each field if you need to apply specific transformations or custom logic to the data.
Saving Your Mappings
After configuring the mappings for each field, click 'Save' to preserve your settings. It's essential to verify each mapping to ensure data will flow correctly from the source message to the target system.
Iterating on Your Mappings
As you test your Workflow with actual data, you may need to return to this section to tweak and refine your mappings. This iterative process ensures that data integration remains accurate and efficient as your systems evolve.
Best Practices
Ensure that the 'Target Key' names are consistent with the naming conventions used within your application or database schema. Consider edge cases and data variability when mapping fields to ensure robust data handling. Document each mapping, including any transformations or logic applied, to maintain clarity and facilitate troubleshooting.
Support and Troubleshooting
If you're experiencing issues with data not appearing as expected in your application, re-visit your mappings to confirm accuracy. For complex transformations or challenges with data mapping, consult Retrohook's detailed documentation or reach out to support for guidance.
Using Advanced Mapping Features in Retrohook Workflows
Overview
The advanced mapping features in Retrohook allow for precise control over how data is transformed during the integration process. The gear icon in the mapping interface opens up options for local code mapping and lookups, enabling you to customize how specific data fields are processed based on your local codes and requirements.
Opening Advanced Mapping Settings
Click on the gear icon next to any field in the mapping interface to open the advanced mapping options for that field.
Configuring Local Code Mappings
The advanced settings panel provides several methods for mapping local codes:
- Default Value: Set a Default Value for the field if there should be a consistent value when the source data is not available or does not require transformation.
- CSV Lookup: Use the CSV Lookup feature to map mulinfole source values to their corresponding replacements in bulk. Click on Choose File to upload a CSV file containing two columns: the first column with the source values and the second column with the replacement values.
- Quick Lookup: For on-the-fly mappings, use the Quick Lookup section. Input a Source Value and its corresponding Replacement value. Add mulinfole mappings by clicking the + button and remove them with the - button.
Saving Advanced Mappings
Once you have configured your mappings, click Close to return to the main mapping interface. Remember to save your overall mapping settings to apply the advanced configurations.
If you encounter issues with local code mappings not functioning as expected, review the advanced settings to confirm the configurations. For complex code systems or mapping challenges, consult Retrohook's detailed documentation or reach out to support for assistance.
Configuring Workflow Load Actions in Retrohook
Overview
The Load page is where you define the output behavior of a Workflow within the Retrohook platform. After a Workflow is triggered and the data is processed through the specified mappings, the 'Load' configuration determines where and how the data is sent to its final destination.
Load Action Configuration
Accessing Workflow Actions
On your Retrohook dashboard, navigate to the 'OG Workflow Action' tab within your Workflow configuration.
Entry Point
The 'Entry' field should be pre-filled with the entry point provided by Retrohook. It's typically the URL or endpoint where your Workflow is listening for incoming data. Ensure that this URL is correct and accessible. You can use the 'Copy To Clipboard' button to quickly copy the payload format, which can be useful for testing or providing a template to the receiving system for integration purposes.
Defining the Destination
Enter the URL where the processed data will be sent in the 'Destination' field. This could be an API endpoint, a web service address, or any other destination that can accept HTTP POST requests.
Reviewing the Sample Payload
Review the JSON structure in the 'Sample Payload' section that illustrates how your data will be formatted when sent to the destination. This should align with the destination's requirements for data ingestion.
Saving the Load Configuration
After you've verified the entry point and destination URL, and reviewed the sample payload, click 'Save' to commit your configurations.
Tips for a Successful Action Setup
- Ensure the destination endpoint is active and correctly configured to receive data in the format provided by the Workflow.
- If the destination requires authentication, ensure that any necessary headers or credentials are included with the outbound data.
- Test the action with a sample payload to confirm that the destination system is receiving and properly handling the data.
If the data fails to reach the destination or if you receive errors, confirm that the destination URL is correct and that any security settings, such as firewalls or CORS policies, permit the connection. If the issue persists, consult the logs for detailed error messages or contact Retrohook support for assistance.