T40.2: ImplementCCR Routines and CCR Event Handlers

ImplementCCR Routines

ImplementCCR routines provide per-CCR custom logic that executes automatically when an ItemSet is deployed to any environment (TEST, LIVE, or any peer environment). They are ideal for tasks that are specific to a particular change and need to run once during deployment.

Common use cases include:

• Data migration: Running SQL statements or ObjectScript code to transform or migrate data as part of a code change
• Configuration updates: Setting global values, updating lookup tables, or adjusting system parameters that accompany a code change
• Cache clearing: Purging cached data that may be invalidated by the new code
• One-time initialization: Creating initial data records or setting up required structures for new functionality
• Environment-specific behavior: Using built-in functions like $$IsLIVE^%buildccr to prevent emails from being sent to actual users from BASE or TEST, or $$Env^%buildccr to display the environment name in UI headers or email footers

CCR Event Handlers

CCR Event Handlers provide per-System custom logic that executes during every ItemSet deployment for that system. Unlike ImplementCCR routines (which are specific to a single CCR), Event Handlers run for all CCRs within a system.

To create a CCR Event Handler: 1. Create a class that extends %Studio.SourceControl.CCREventHandler 2. Implement callback methods based on the method stubs in the parent class 3. Register the handler by setting: Set ^SYS("SourceControl","EventHandler","Class")="MyClassName"

Key callback methods include:

• ItemSetAfterLoadToOS(): Executed after ItemSet files are loaded to the source workspace (file system) but before they are imported into the namespace
• ItemSetAfterLoadToNS(): Executed after all items have been imported into the namespace, compiled, and the ImplementCCR routine (if any) has run

Common Event Handler use cases include:

• Production restart: Automatically restarting or updating a production after any code deployment to pick up new business logic
• Notification: Sending deployment notifications to operations teams so they are aware of changes reaching an environment
• Logging: Recording deployment events in a custom audit table for compliance and traceability
• Post-deployment validation: Running verification checks after every ItemSet load to confirm the environment is functioning correctly
• Environment cleanup: Clearing cached configuration data, temporary globals, or stale references that may not be covered by the ImplementCCR routine

Key Difference: Per-CCR vs Per-System Scope

The fundamental distinction between ImplementCCR routines and Event Handlers is their scope:

• ImplementCCR routines are tied to a specific CCR ID. They execute only when an ItemSet for that particular CCR is deployed. This makes them ideal for one-time tasks associated with a specific change, such as data migration or configuration updates that accompany new code.
• CCR Event Handlers are tied to the System. They execute for every ItemSet deployment across all CCRs in that system. This makes them ideal for recurring tasks that should happen with every deployment, such as production restarts or deployment notifications.

Both mechanisms can coexist. During a single ItemSet deployment, the Event Handler runs at its designated hook points and the ImplementCCR routine runs at its designated point in the sequence.

Tier 1 Transport Load to Namespace Flow

When a Tier 1 ItemSet is deployed to an environment, the following sequence occurs:

1. ItemSetAfterLoadToOS() -- If a CCR Event Handler is configured, this method executes first (after files reach the workspace) 2. Item loading -- Items in Tier 1 subfolders (/cls, /cspapp, /inc, /prj, /rtn) are automatically loaded into the namespace 3. Project compilation -- All items are added to a project named after the ItemSet and compiled in the proper order 4. ImplementCCR routine execution -- If an ImplementCCR routine exists for the CCR, it is executed 5. ItemSetAfterLoadToNS() -- If a CCR Event Handler is configured, this method executes last

Write statements in both ImplementCCR routines and Event Handler methods are directed to the Transport Log, which can be viewed and downloaded from the CCR Perforce Details section.

CCR Built-in Functions

CCR provides several built-in functions in the %buildccr routine that allow code to vary its behavior based on the current environment:

Function	Purpose	Example Use Case
$$IsLIVE^%buildccr	Returns whether the current environment is LIVE	Prevent test emails from being sent to real users in BASE/TEST
$$Env^%buildccr	Returns the environment type (BASE, TEST, UAT, LIVE)	Display environment in email footers or UI headers
$$EnvName^%buildccr	Returns the environment name	Perform customized logic for specific environments (e.g., TRAIN as a peer to TEST)
$$Sys^%buildccr	Returns the SystemCode	Include system identification in error logs
$$Org^%buildccr	Returns the Organization	Include organization details in email alerts to centralized monitoring

These functions can be used in any ObjectScript code, not just ImplementCCR routines, making them valuable for writing environment-aware production code.

---

Naming Convention

The naming convention for ImplementCCR routines is strict and case-sensitive:

• Format: ImplementCCR.<CCR_ID>
• The prefix "ImplementCCR" must use exact capitalization (capital I, capital C, capital C, capital R)
• The CCR_ID portion must exactly match the CCR record identifier
• Examples:
• CCR ID BEST0001 requires routine name ImplementCCR.BEST0001
• CCR ID ISCX12943 requires routine name ImplementCCR.ISCX12943
• CCR ID TRPHS0042 requires routine name ImplementCCR.TRPHS0042

The naming convention is validated during the bundle and upload process. If you attempt to upload a routine named ImplementCCR.BEST12345 to a CCR with ID BEST6789, the system will produce an error because the CCR ID in the routine name does not match the target CCR.

Creating the Routine

To create an ImplementCCR routine:

1. Open the IDE (Studio or VS Code) connected to the BASE environment 2. Create a new ObjectScript routine (MAC routine type) 3. Name it using the exact convention: ImplementCCR.<CCR_ID> 4. Write the implementation logic as standard ObjectScript code 5. Use Write statements for output that should appear in the Transport Log 6. Save and compile the routine 7. When prompted, add the routine to source control 8. Include the routine in the ItemSet bundle along with other changed items

Execution Behavior

When an ItemSet is deployed to any environment:

• The Client Tools check whether an ImplementCCR routine matching the CCR ID exists in the ItemSet
• If found, the routine is executed automatically after all other items in the ItemSet have been imported and compiled
• The routine runs in the target namespace of the deployment
• All Write output is captured in the Transport Log
• The routine executes on every deployment of that ItemSet (TEST, LIVE, and any peer environments)

Best Practices

• Test in BASE: Verify the ImplementCCR routine works correctly in BASE before progressing the CCR to ensure it will not fail during deployment to TEST or LIVE
• Use built-in functions: Leverage $$Env^%buildccr and $$IsLIVE^%buildccr to vary behavior by environment when needed (e.g., skip sending real notifications from BASE or TEST)
• Keep it focused: The routine should contain only the logic needed for this specific CCR's deployment; do not include logic that belongs in Event Handlers or in the application code itself
• Document in Implementation Plan: If the ImplementCCR routine performs significant actions (such as data migration or configuration changes), document this in the CCR's Implementation Plan so reviewers and deployers are aware
• Handle errors gracefully: Include error handling (Try/Catch or $ZTrap) to prevent deployment failures from unhandled errors in the routine
• Idempotent design: Where possible, design the routine so it can be safely re-executed without causing duplicate data or other side effects, since the same ItemSet may be deployed multiple times during troubleshooting

---