T40.6: CCR Workflows in HealthShare

What Are Secondary Environments?

In a standard CCR workflow, changes flow from BASE to TEST to LIVE in a linear progression. However, HealthShare deployments frequently involve multiple instances that need to receive the same changes simultaneously. Secondary environments address this requirement by allowing additional environments to receive changes at the same time as their corresponding primary environment.

For example, a HealthShare Unified Care Record (UCR) deployment may include a central Registry, an Access Gateway, and multiple Edge Gateways. When a CCR progresses from BASE to TEST, all the secondary TEST environments (e.g., Edge Gateway 1 TEST, Edge Gateway 2 TEST) receive the deployment at the same time as the primary TEST environment (e.g., Registry TEST).

HealthShare Secondary Edge Gateways

The most common use case for secondary environments in HealthShare is deploying to multiple Edge Gateways. The architecture looks like this:

• BASE phase: The primary BASE (e.g., Repository) and secondary BASE environments (E1, E2) all receive the ItemSet during In_BASE
• TEST phase: The primary TEST and secondary TEST environments all receive the deployment simultaneously
• LIVE phase: The primary LIVE and secondary LIVE environments all receive the deployment simultaneously

Each phase deploys to the primary and all its secondary environments together, ensuring consistency across the entire HealthShare network.

CCR System Architecture Options for HealthShare UCR

There are two architectural approaches for managing CCR with HealthShare UCR:

1. Separate CCR Systems: Create distinct CCR Systems for Edge Gateway, Access Gateway, and Registry. Use secondary environments to link multiple gateways of the same type. This approach provides the most granular control and is appropriate when different gateway types have significantly different change sets.

2. Instance-wide CCR: Use a single CCR System with a shared code database for all namespaces on the instance. This approach is simpler to manage when all components on an instance generally receive the same changes.

Deployment Behavior

When deploying ItemSets to environments with secondary configurations:

• ItemSet deployment opens a new browser tab for each environment being deployed to
• Tabs automatically close upon successful deployment
• If a deployment fails, the tab remains open with error information
• See ICC440 for more detailed information on secondary environment configuration and deployment

---

HealthShare Health Connect Components (Tier 0 Only)

HealthShare Health Connect includes many components that are candidates for Tier 0 CCR management only, meaning they cannot be maintained through Tier 1 source control and CCR Transport. These include:

• Facility Registry -- Defines healthcare facilities in the network
• HealthShare Service Registry -- Registers available services
• OID Registry -- Object Identifier registry for standards compliance
• Assigning Authority Registry -- Manages patient identifier assigning authorities
• Configuration Registry -- System-wide configuration settings
• XUA Configuration Registry -- Cross-enterprise User Assertion configuration
• Coded Entry Registry -- Manages coded entries
• Exclude Audit Events table -- Defines which events are excluded from auditing
• FHIR CSP Configuration -- FHIR endpoint configuration

All of these items lack file-based representations that can be versioned in source control. Changes to these components should be documented and managed using Tier 0 CCRs to ensure traceability and peer review.

HealthShare Unified Care Record Components (Tier 0 Only)

The UCR adds even more Tier 0-only components beyond those in Health Connect:

• User/Clinician Registry -- Manages clinical user definitions
• Gateways Registry -- Configures gateway connections
• Consent Registry (multiple tables) -- Manages patient consent rules
• Program Registry -- Defines care programs
• Relationship Registry -- Manages entity relationships
• Clinician Group Registry -- Groups clinicians for access control
• PIX Notification Registry -- Patient Identifier Cross-referencing notifications
• Query Instance Registry -- Manages query instances
• Security Domains -- Defines security boundaries
• Consent Groups -- Groups consent rules
• Push Notification settings (Delivery Management) -- Configures push notification delivery
• Terminology settings (multiple tables) -- Manages terminology mappings and configurations

HealthShare Health Insight

HealthShare Health Insight is notable because its Analytics Management Portal does support Tier 1 source control hooks. This means that analytics artifacts managed through the Health Insight Analytics portal can be checked out, modified, and checked in using the standard Tier 1 source control workflow, unlike the registry components listed above.

Best Practices for HealthShare CCR

• Use Tier 0 CCRs for all registry and configuration changes that cannot exist in source control
• Tier 0 CCRs still provide significant value: they make changes discoverable and enforce workflow such as peer reviews
• Consider Tier 1 CCR with the ImplementCCR routine for changes that can be automated by calling documented APIs
• Watch for HealthShare Change Control (HCC), which is designed to enable export of configuration changes for CCR Transport automation, bringing more HealthShare components under automated change control

---

Why HealthShare Configuration Is Difficult to Source Control

The fundamental difficulty with HealthShare configuration and settings is that many components store their data in database tables rather than in flat files. Source control systems like Perforce are designed to version flat files (classes, XML exports, configuration files). When configuration is stored directly in database globals and tables, there is no straightforward file to check in and check out.

This creates several challenges:

• No native export format: Many registry items do not have a standard export mechanism that produces a file suitable for source control
• Multi-table dependencies: Some configuration changes span multiple interrelated tables. For example, the Consent Registry involves multiple tables that must be updated consistently. Exporting and importing individual tables without their related entries can lead to inconsistencies
• Order-dependent operations: Some configuration changes must be applied in a specific order, which is difficult to capture in a simple file-based deployment
• Environment-specific values: Registries like the Facility Registry and Gateways Registry contain environment-specific connection details that differ between BASE, TEST, and LIVE

Version Confusion

An additional difficulty is that HealthShare versions do not correlate directly to InterSystems IRIS versions. Feature availability (such as Production Decomposition, portal hooks, or new export capabilities) depends on the underlying InterSystems IRIS version, but HealthShare product releases follow their own versioning schedule. When evaluating which CCR features are available in a HealthShare environment, you must determine the actual InterSystems IRIS version underlying the HealthShare installation rather than relying on the HealthShare product version number.

Mitigation Strategies

• Tier 0 CCRs: Use for all registry changes to maintain documentation, peer review, and traceability even when source control automation is not possible
• ImplementCCR routine: For changes that can be scripted, create a Tier 1 CCR with an ImplementCCR routine that calls documented APIs to make registry changes programmatically
• HealthShare Change Control (HCC): When available, use HCC to enable export of configuration changes for CCR Transport automation
• Detailed Implementation Plans: Write particularly thorough Implementation Plans for registry changes, since manual steps are required in each environment

---

Linkage Definitions in Source Control

HealthShare Patient Index uses linkage definitions to control how patient records are matched and linked across the enterprise. The linkage definition is stored as an ObjectScript class that can be maintained in source control using the IDE (VS Code with ObjectScript extension or Studio).

Since there are no Management Portal hooks for linkage definitions, follow the procedure described in ICC530 for items that lack portal hooks but are editable in the IDE: 1. Check out the linkage definition class from source control in the IDE 2. Make the necessary modifications to matching algorithms, thresholds, or field weights 3. Save and compile the class 4. Check the modified class back in to source control 5. Bundle and upload to the appropriate CCR

Important: Do Not Add Generated Classes

When a linkage definition is compiled, it generates additional classes automatically. These generated classes should not be added to source control because:

• They are automatically regenerated every time the linkage definition is compiled
• Adding them to source control creates unnecessary version conflicts
• The generated classes will be recreated correctly when the linkage definition is compiled during deployment

CCR Event Handler for Linkage Definition Changes

Linkage definition changes require additional implementation steps beyond simply deploying the class file. The standard ItemSet deployment imports and compiles the class, but the following additional steps are needed: 1. Stop the production -- The production must be stopped before the linkage definition can be properly activated 2. Compile the linkage definition -- Ensure the class is compiled after import 3. Start the production -- Restart the production with the new linkage definition 4. Rebuild linkage data -- Rebuild the linkage data to apply the new matching rules to existing patient records

These steps can be automated by configuring a CCR Event Handler. The Event Handler is a custom class that executes additional logic during ItemSet deployment, ensuring that the production is stopped, the linkage definition is compiled, the production is restarted, and the linkage data is rebuilt -- all without manual intervention.

This automation is particularly important for consistency across environments. Without the Event Handler, implementers must remember to perform each step manually in BASE, TEST, and LIVE, creating opportunities for errors and inconsistencies.

---