T40.5: Management Portal Source Control Hooks

The Problem: Environment-Specific Configuration

When interoperability Productions are maintained under source control, the Production class definition must be identical across all environments (BASE, TEST, UAT, LIVE). However, certain configuration fields for business components naturally differ between environments. Common examples include:

• File paths (e.g., c:\BASE\In vs. c:\TEST\In vs. c:\LIVE\In)
• IP addresses for connecting to external systems
• Port numbers for services in different environments
• Failure timeout values that may vary between development and production

Since CCR enforces that the Production definition is the same everywhere, you cannot embed environment-specific values directly into the Production class. The solution is System Default Settings.

How System Default Settings Work

System Default Settings allow you to configure default values for business component settings outside of the Production class definition. Each environment maintains its own unique set of default values. When a business component starts, it reads its settings first from the Production definition and then overrides them with any matching System Default Settings configured locally in that environment.

For example, a business operation named "To_Lab" might need a FilePath setting. In BASE, the System Default Setting for FilePath is c:\BASE\In, while in TEST it is c:\TEST\In. The Production definition itself does not contain the FilePath value -- it is supplied by the environment's local System Default Settings. This ensures the Production class remains identical across environments while allowing environment-specific behavior.

Creating System Default Settings

System Default Settings are configured through the Management Portal at Configure > System Default Settings. The configuration form includes:

• Production: Select the target production (use * to match all productions)
• Item Name: The business component name (use * to match all items)
• Host Class Name: The class of the business host (use * to match all)
• Setting Name: The specific setting to configure (can be selected from a dropdown or dragged from the settings tree)
• Setting Value: The environment-specific value
• Description: Optional documentation
• Deployable: Checkbox to mark the setting as deployable

Exporting System Default Settings

System Default Settings can be exported for source control through: 1. Navigate to the source control menu > CCR Controls > Export Default Settings 2. Choose the Production and click Export 3. The export is saved to the /backup subdirectory 4. The exported file can be bundled and uploaded in BASE only 5. Add the file to source control using the itemsetsourcelink web application in the IDE

To find the exported file:

• VS Code (ObjectScript): Explorer > itemsetsourcelink_system > custom_ccrs > ...
• Studio: Namespace view > CSP Files > itemsetsourcelink_system > custom_ccrs > ...

After locating the file, right-click > Source Control > Add To Source Control > Yes, then bundle and upload to a CCR.

---

What Are Management Portal Hooks?

Management Portal source control hooks are embedded controls within specific Management Portal pages that allow users to interact with the source control system directly from the portal interface, without needing to switch to an IDE. These hooks provide the same functionality as the source control menu available in VS Code or Studio.

Visibility Requirements

The hooks are only visible when working in a namespace that has been configured for source control. If source control has not been configured for the current namespace, the hook icons will not appear on Management Portal pages. This is an important distinction -- if you do not see the hook icons, verify that the namespace is properly configured for CCR.

Automatic Import on Deployment

A key advantage of Management Portal hooks is that all items modified using these hooks are automatically imported during ItemSet Deployment. This means that when a CCR is progressed and the ItemSet is deployed to TEST, UAT, or LIVE, any interoperability components that were modified through portal hooks in BASE are automatically included in the deployment package.

---

Hook Commands

The command icon (appearing as a branch/merge symbol) provides access to the following source control operations:

• Add to source control: Registers the current item with the source control system, making it a tracked item
• Checkout: Checks out the item so you can make modifications. The item becomes locked to other users until checked in
• Undo checkout: Reverts your checkout, discarding any local changes and releasing the lock
• CCR controls: Access to CCR-specific operations such as exporting default settings, viewing CCR status, and other management functions
• Diff: Compare the current version of the item with the version in source control to see what has changed

Hook Output Indicators

The output icon (appearing as a notepad symbol) has two states:

• Unread output (notepad with lines icon): Indicates there is new output from a source control operation that has not yet been viewed
• All output viewed (notepad with checkmark icon): Indicates all source control output has been read

These output indicators help users stay aware of the results of source control operations performed through the portal.

Management Portal Pages with Hooks

The following interoperability pages include source control hooks:

Under Configure menu:

• Production -- The main production configuration page
• Business Partners -- Partner configuration
• Credentials -- Authentication credentials
• Schedule Specs -- Scheduling configurations
• Data Lookup Tables -- Key-value lookup tables
• System Default Settings -- Environment-specific defaults
• Enterprise Systems -- External system definitions

Under Build menu:

• Business Processes -- BPL business process designer
• Data Transformations -- DTL data transformation editor
• Business Rules -- Rule editor
• Record Maps -- Record map editor
• Complex Record Maps -- Complex record map editor

Additional:

• HL7 v2 Custom Schemas -- Only visible if the user has edit privileges

Each of these pages displays the source control hook icons when the namespace is configured for source control.

---

Production Decomposition (v2019.4+)

Starting with v2019.4, InterSystems introduced Production Decomposition, which fundamentally changes how Productions are managed under source control. With decomposition enabled, individual business hosts (services, processes, operations) and production-level settings can be checked out independently. This is a significant improvement over the pre-v2019.4 behavior where the entire Production had to be checked out as a single monolithic unit.

Key rules for decomposed productions:

• Individual components can be checked out without locking the entire Production
• Custom code must not be included directly in the Production class definition. Instead, make the Production class inherit from a super class that contains the custom code
• You can check out the entire Production in the IDE to edit its XML directly, but this requires that no individual components are currently checked out
• Client tools should be updated to the version released on or after December 10, 2024, to ensure compatibility with the latest decomposition features

Pre-v2019.4 Behavior

Before v2019.4, Production Decomposition was not available. The entire Production was treated as a single source-controlled item:

• Checking out any part of the Production required checking out the entire Production class
• Only one person could modify the Production at a time
• This created bottlenecks in team environments where multiple developers needed to make simultaneous changes

Enabling Production Decomposition with Existing Productions

For systems that already have existing Productions: 1. Progress any active CCRs changing the Production to LIVE 2. Create a Tier 1 CCR to document enabling Production Decomposition 3. Implementation Plan (BASE only):

• Run Do Configure^%buildccr
• Accept defaults until reaching the prompt: "Decompose Productions in Source Control to handle Business Host and Production settings individually?"
• Enter Yes to Decompose Productions
• Enter Yes to the following 2 prompts to decompose existing Productions

4. Non-BASE environments: Deploy the ItemSet 5. Bundle and upload changes to the CCR 6. Progress the CCR through to Closed (must be pushed to LIVE before changes to the Production can begin)

Enabling Production Decomposition without Existing Productions

For new systems without existing Productions: 1. Create a Tier 0 CCR to document enabling Production Decomposition 2. Implementation Plan for all Environments:

• Run Do Configure^%buildccr
• Accept defaults until reaching the decomposition prompt
• Enter Yes to Decompose Productions
• Enter No to the following prompt to decompose existing Productions (there are none)

3. Progress the CCR through to Closed (must be pushed to LIVE before Production changes can begin)

---

Temporarily Starting, Stopping, and Restarting Components

In v2019.4+ with Production Decomposition, you can temporarily start, stop, or restart individual business components without modifying the Production class definition. This is significant because:

• Normal enable/disable: Double-clicking a component to enable, disable, or restart it changes the Production class definition. This means it cannot be done in TEST, UAT, or LIVE (where the Production is read-only), and it requires checking out the component in BASE.
• Temporary actions: Using the Actions tab (select a component, then go to the Actions tab), you can:
• Start: Start a temporarily stopped item
• Stop: Stop a running item temporarily
• Restart: Restart a running item

Temporary actions are valuable because:

• They do not require unlocking the environment or checking out the Production
• They are available in all environments (BASE, TEST, UAT, LIVE)
• They provide operational flexibility for troubleshooting without making persistent changes
• However, a component that is disabled in the Production definition cannot be temporarily started -- the temporary start only works on components that are enabled but currently stopped

Color Coding of Setting Labels (v2019.4 through v2021.1)

When a Production is checked out in BASE, business component setting fields display color coding that indicates the source of each setting's value. This visual indicator helps developers understand where each setting value comes from:

• Settings from the Production definition may appear in one color
• Settings from System Default Settings may appear in another color
• Settings with default class values may appear differently

Important limitations:

• Color coding is only visible when the Production is checked out
• Since Productions cannot be checked out in TEST, UAT, or LIVE, color coding is not available in those environments
• Fields appear greyed out when the Production is read-only (not checked out)

Undo Capability

The v2019.4+ Production editor includes an undo capability that allows you to revert changes before saving them. This provides a safety net when making configuration changes through the Management Portal, ensuring that accidental modifications can be reversed before they are committed.

---

Identifying Items Without Portal Hooks

While many interoperability components have embedded Management Portal hooks, some items that need to be under source control do not have direct hook integration in their Management Portal pages. These items must be handled through an export-then-add workflow. System Default Settings are a prime example of this category -- they have a dedicated export mechanism through the CCR Controls menu but do not have the standard hook icons embedded in their configuration page.

The Export-Then-Add Workflow

For items without portal hooks that can still be exported:

1. Export the item: Use the source control menu > CCR Controls > Export function, or use programmatic export methods to generate an export file 2. Locate the exported file: The export typically writes to the /backup subdirectory within the source workspace. In VS Code, navigate through Explorer > itemsetsourcelink_system > custom_ccrs and drill down to the appropriate system, environment, and backup directories. In Studio, use the namespace view > CSP Files > itemsetsourcelink_system > custom_ccrs and navigate similarly 3. Add to source control: Right-click the exported file and select Source Control > Add To Source Control > Yes 4. Bundle and upload: Include the file in a CCR bundle and upload it to the appropriate CCR

This workflow is only performed in BASE. The exported files are then deployed to other environments automatically through the CCR ItemSet deployment process.

---

Items Editable Only Through the IDE

Certain interoperability-related items do not have Management Portal hooks but can be checked out and edited through VS Code (with the ObjectScript extension) or Studio. These include custom ObjectScript classes, include files, and other code-based artifacts that are part of the interoperability solution but do not have dedicated portal editors with embedded hooks.

For these items, follow the standard IDE-based source control workflow: 1. Check out the item from source control in the IDE 2. Make your modifications 3. Save and compile the item 4. Check the item back in to source control 5. Bundle and upload to the CCR

Best Practices for Interface Development

When developing new interfaces under CCR:

• Use an iterative process to configure new interfaces, making small changes and testing frequently
• Disable interfaces in development so they do not process messages prematurely while being configured
• Progress small, discrete CCRs to Closed rather than bundling many changes into a single large CCR
• When the interface is ready for Go-LIVE, create and progress a CCR that enables the finished components

When Source Control Is Not Feasible

For items that truly cannot be maintained in source control (e.g., certain runtime configurations, system-level settings, or items that do not have file-based representations):

• Use Tier 0 CCRs to document and manage the change
• This ensures the change is discoverable and traceable
• The Tier 0 workflow still enforces peer reviews and proper documentation
• Over time, aim to bring more items under Tier 1 source control as tooling improves

Version Considerations

Note that versions in the ICC530 slides refer to releases for InterSystems IRIS. HealthShare versions do not correlate directly to InterSystems IRIS versions. When determining which features are available (such as Production Decomposition), verify the feature availability based on the actual InterSystems IRIS version underlying the HealthShare installation.

---