T40.4: Interoperability Components and CCR Considerations

Choosing the Right CCR Tier

Not all changes to interoperability components can be maintained in source control. Best practice dictates choosing the appropriate CCR tier:

• Tier 1 (Source Control): Use whenever possible. Tier 1 CCRs track changes in Perforce, provide automatic versioning, and enable ItemSet-based deployment. All custom ObjectScript classes, routines, DTL, business processes, business rules, record maps, and other code artifacts should be managed through Tier 1.
• Tier 0 (Documentation Only): Use when it is not feasible to maintain an item in source control. Tier 0 still makes the change discoverable and traceable, and it enforces workflow steps such as peer reviews. Examples include certain runtime configurations, manual system-level changes, or items that do not have file-based representations.

The key principle is that every change should go through CCR, even if source control is not available for that specific item type.

Iterative Interface Development

When building new interfaces under CCR, follow an iterative process rather than attempting to complete an interface in a single large CCR:

1. Disable interfaces in development: When creating a new interface, keep its business components disabled so they do not process messages prematurely while being configured 2. Make small, incremental changes: Each CCR should contain a discrete set of related changes that can be reviewed, tested, and deployed independently 3. Progress small CCRs to Closed: Rather than accumulating many changes in a single CCR, create and close multiple small CCRs as the interface takes shape 4. Enable on Go-LIVE: When the interface is fully configured and tested, create a final CCR that enables the finished components and progress it to LIVE

This approach reduces risk by ensuring each change is small enough to review effectively and easy to back out if problems arise.

Production Class Best Practices

The Production class definition has special constraints under CCR:

• No custom code in Production class: Custom ObjectScript code must not be placed directly in the Production class definition. The Production class is managed specially by CCR and Production Decomposition, and embedding custom code can cause conflicts during source control operations.
• Use inheritance: Instead, create a separate super class that contains the custom code and have the Production class inherit from it. The super class is managed as a normal Tier 1 source-controlled item with standard checkout and check-in procedures.
• Production Decomposition: With decomposition enabled (v2019.4+), individual business hosts and production settings can be checked out independently. This allows multiple developers to work on different parts of the same Production simultaneously.

Shared Code Across Namespaces

When code is shared across multiple namespaces within the same CCR system, all namespaces deploy from the same Perforce branch. This means:

• The same classes and routines are deployed to every namespace in the system
• Environment-specific behavior must be implemented using %buildccr functions or System Default Settings, not by maintaining separate code versions
• Code that references namespace-specific resources (databases, globals, web applications) should use the %buildccr functions to determine the correct resource names at runtime

---

The Environment Difference Problem

In a CCR-managed system, the Production class definition must be identical across all environments (BASE, TEST, UAT, LIVE). CCR enforces this through its source control and ItemSet deployment mechanisms -- when an ItemSet is deployed, the exact same Production definition is loaded into the target environment.

However, real-world interoperability configurations require values that naturally differ between environments:

• File paths: An inbound file service might read from c:\BASE\In in development but c:\LIVE\In in production
• IP addresses: TCP connections point to different hosts in different environments (test systems vs. production systems)
• Port numbers: Services may listen on different ports across environments
• Timeout values: Development environments may use shorter timeouts for faster iteration, while production environments need longer timeouts for reliability
• Email recipients: Alert notifications should go to developers in BASE/TEST but to operations staff in LIVE

If these values are embedded directly in the Production definition, they will be overwritten each time an ItemSet is deployed, causing the target environment to use the wrong values.

System Default Settings as the Solution

System Default Settings decouple environment-specific configuration values from the Production class definition. Each environment maintains its own local set of System Default Settings that override values at runtime.

How they work: 1. The Production definition does not contain the environment-specific setting value 2. When a business component starts, it reads settings first from the Production definition 3. It then checks for matching System Default Settings configured locally in that environment 4. If a match is found, the System Default Setting value overrides the Production value

This allows the Production definition to remain identical in all environments while each environment independently provides its own values for settings that must differ.

Creating System Default Settings

System Default Settings are configured through the Management Portal at Configure > System Default Settings:

• Production: Select the target production or use * to match all productions in the namespace
• Item Name: The business component name (e.g., BadMessageHandler) or * for all
• Host Class Name: The class of the business host or * for all
• Setting Name: Select from the dropdown or drag from the settings tree (e.g., FilePath, IPAddress, Port)
• Setting Value: The environment-specific value (e.g., c:\TEST\output)
• Description: Optional documentation
• Deployable: Checkbox indicating whether the setting should be included in CCR exports

Exporting and Deploying System Default Settings

System Default Settings are managed through a specific export workflow:

1. Navigate to Source Control menu > CCR Controls > Export Default Settings 2. Choose the Production and click Export 3. The export file is saved to the /backup subdirectory of the source workspace 4. Locate the file in the IDE under itemsetsourcelink_system > custom_ccrs 5. Right-click > Source Control > Add To Source Control > Yes 6. Bundle and upload to a CCR

This export is performed in BASE only. The exported System Default Settings are then deployed to other environments through the CCR ItemSet deployment process. Each environment should have its own locally configured System Default Settings that are not overwritten by deployments.

Example: System Default Settings in Practice

Consider a business service named To_Lab with a FilePath setting that must differ between environments:

Environment	To_Lab FilePath	Failure Timeout
BASE	c:\BASE\In	15
TEST	c:\TEST\In	15
LIVE	c:\LIVE\In	30

In this example, FilePath is configured as a System Default Setting in each environment with the appropriate local value. The Failure Timeout of 15 could be set in the Production definition for BASE and TEST, while LIVE uses a System Default Setting to override it to 30. The Production class itself contains neither value for FilePath, keeping it portable.

Combining with %buildccr Functions

System Default Settings and %buildccr functions serve complementary purposes:

• System Default Settings: Best for configuration values like file paths, IP addresses, ports, and timeout values that differ between environments but are used as standard business component settings
• %buildccr functions: Best for logic branching where the code itself needs to behave differently (e.g., suppressing emails in non-LIVE environments, routing to different endpoints based on environment type)

Use both mechanisms together to create fully environment-aware interoperability solutions that deploy identically across all environments while behaving correctly in each one.

---