T40.1: Tier 1 CCRs for Safe Change Progression

Overview

In CCR Tier 1, the checkout mechanism is the cornerstone of concurrency control within an InterSystems environment. Before any modification can be made to a controlled source item, that item must be checked out. Checkout guarantees that only one user can modify a given item at any time, preventing conflicts where multiple users edit the same class, routine, or other source item simultaneously.

Why Checkout Is Required

If multiple users could edit an item simultaneously without checkout, several problems would arise:

• All changes would be submitted to a single CCR, meaning that changes from other users could be incomplete at the time of upload
• The diff comparison would show changes from other users, and the user who made a particular change would not be highlighted
• The user submitting a change would need to carefully inspect diffs for modifications they did not make, increasing the risk of errors

When Checkout Occurs

Checkout is required whenever a developer needs to modify an existing controlled item. There are two ways to trigger checkout: 1. Start making a change -- When a developer begins editing a controlled item, a popup message prompts them to confirm checkout 2. Use the Source Control menu -- Open the item in the IDE and select the Check Out option from the Source Control menu

An item that is already checked out to another username cannot be checked out by a different user. The checkout status is removed when the changes are submitted (checked in).

BASE Environment Restriction

Only the BASE environment allows editing of items. Non-BASE environments (TEST, LIVE) are locked:

• Existing items are read-only in the IDE and cannot be checked out
• New items cannot be created in the IDE on non-BASE environments
• This restriction ensures that all changes flow through the proper CCR workflow

Backup File Creation

On checkout, the system exports the current version of the item as an XML file and creates a duplicate .bak file. This backup file serves two critical purposes:

• Revert changes: If the developer needs to undo their modifications, the .bak file restores the original version
• Diff changes: The .bak file provides the baseline for comparing what has changed

Do not manually change the read/write status of any files in the source workspace, as this will break the source control integration.

---

Source Control Menu Access

The Source Control menu is available when the IDE (Studio, VS Code with ObjectScript extension, or Atelier) is connected to a CCR-configured namespace. The menu options differ slightly between disconnected and connected BASE configurations:

Disconnected BASE (customer environments outside InterSystems network):

• Check Out, Undo Check Out, Check In, Get Latest, Add To Source Control, Diff Against Last Version, Show CCR Controls

Connected BASE (InterSystems internal applications):

• Same as disconnected plus: Disconnect from Perforce, Reconnect to Perforce

VS Code: Source Control button appears when viewing any item. Options include Check Out, Show CCR File History, and Show CCR Controls.

Check Out Operation

When checking out an existing item:

• The system guarantees only the current user can make changes to that item
• A backup file (.bak) is created to enable revert and diff functionality
• For connected BASE environments, the item is also checked out in Perforce
• The item becomes writable in the source workspace

Add To Source Control (Creating New Items)

When creating a new item:

• On first save, the IDE prompts whether to add the item to source control -- choose yes
• Alternatively, use the Add To Source Control menu option explicitly
• On add, the item is exported as writable XML (routines are exported as .rtn RO files for legacy reasons)
• The item is checked out to the current username
• The item is added to the Uncommitted Queue with an "add" action

Diff Against Last Version

The diff operation compares the current exported XML file with the .bak version, highlighting changed lines. There are two equivalent ways to access the Quick Diff page: 1. From IDE: Source Control Menu > Show CCR Controls > ItemSet Bundle > click diff link for the appropriate item 2. With item open in IDE: Source Control Menu > Diff Against Last Version

The diff is critical because it indicates exactly what will be uploaded to the CCR. If expected changes are missing from the diff, the most likely cause is that the code did not compile successfully -- changes are only exported to the source workspace upon successful compilation.

Undo Check Out (Revert)

To revert all changes made to a checked-out file that has not yet been uploaded:

• Open the item in the IDE and use the Undo Check Out menu option
• This restores the item from the .bak file, discarding all modifications

To delete a new item that has not been uploaded to CCR:

• Simply delete the item in the IDE

Delete Existing Item

When deleting an existing controlled item from the IDE:

• A popup message prompts to remove the item from source control -- choose yes
• The item is deleted from both the database and the source workspace
• A delete action is added to the uncommitted queue
• For disconnected BASE: the delete is bundled and uploaded to CCR
• For connected BASE: the delete is submitted to Perforce

---

Bundle and Upload Workflow (Disconnected BASE)

For disconnected BASE environments (customer sites outside the InterSystems network), changes are submitted through the Bundle and Upload ItemSet screen:

1. Access the Bundle screen from the IDE via: Source Control > Commit Changes via ItemSet (in newer client tools), or Source Control > Show CCR Controls > Bundle ItemSet 2. The screen displays the Uncommitted Queue showing all pending changes with columns for Last Changed, Source, CCR, Changed By, Action, Name, Internal Name, and Diff 3. Use the diff link to review changes for each item before bundling 4. Select which items to include in the bundle using checkboxes 5. Copy the Access Token from the CCR Perforce Details section 6. Enter the CCR ID from the CCR record 7. Click "Bundle and Upload Changes" to submit

The filters at the top of the Bundle screen (Source, Changed By, CCR) are for display purposes only and have no effect on what is actually bundled. Always review the diff before uploading to ensure you know exactly what changes are being submitted.

Validation During Upload

The Bundle and Upload screen validates several items before allowing upload:

• Access key: Validated against the CCR server; an invalid token shows an "x" next to the field
• CCR ID existence: Confirms the specified CCR record exists
• CCR state: Upload is only allowed when the CCR is in In_BASE or BASE_Pending_Peer_Review state
• System match: The system code of the CCR must match the system code of the current environment

Common errors and solutions:

• Invalid Access Token: Usually a typo; re-copy from the CCR
• Invalid State (e.g., In_PREP): Perform the markPREPComplete transition first to move to In_BASE
• Invalid System: Either the wrong CCR ID was entered, the CCR was created for the wrong system, or changes were made in the wrong namespace

Connected BASE Workflow (Check In to Perforce)

For connected BASE environments (InterSystems internal applications), changes are submitted directly to Perforce: 1. From IDE, Source Control > Check In 2. If prompted, enter Perforce password 3. Click diff link for each item to verify changes -- always diff before submitting 4. Select item(s) to check in 5. Copy and paste the CCR ID and Title from the CCR into the Description field 6. Copy the CCR ID into the Perforce Job field (required) 7. Click "Submit"

Verify Submitted Changes

After submitting changes (via either method), always verify the correct items are listed in the CCR:

• Navigate to the Perforce Details section of the CCR
• Click the Submitted Changes tab
• Confirm that all expected items appear with the correct actions (edit, add, delete)

---

Moving to TEST

When the CCR is ready to progress from BASE_Complete to the TEST environment:

1. Perform the transition: Use authorizeAndStartMoveToTEST (combines authorization and start) or the two-step process of authorizeFutureMoveToTEST followed by startMoveToTEST 2. ItemSet creation: The transition into Pending_Manual_Move_To_TEST triggers Perforce integration and automatic creation of a deployment ItemSet 3. Deploy immediately: Click the "deploy to TEST" link under Perforce Details of the CCR

• This opens a web page on the TEST environment
• Log in using credentials for the TEST environment
• After login, the ItemSet download and item import process begins automatically

4. Do not delay deployment: Delaying or abandoning ItemSet deployment will cause problems in later workflow steps

Automatic Transition After TEST Deployment

The markMoveToTESTComplete transition occurs automatically when two conditions are met:

• No changes have been made to the default Implementation Plan
• The ItemSet has been successfully deployed to all TEST environments that have "Require ItemSet" configured

When this automatic transition occurs, a row in the Transition History notes: "{transition occurred automatically due to successful ItemSet load in TEST}."

If the Implementation Plan has been edited to include manual steps, the CCR user must perform the markMoveToTESTComplete (or markMoveToLIVEComplete) transition manually after completing those manual steps.

Moving to LIVE

The LIVE deployment follows the same pattern as TEST:

• Integration from TEST to LIVE occurs on *StartMoveToLIVE transitions
• An ItemSet is automatically created and made available for deployment under Perforce Details upon successful integration
• Deploy using the same link-based mechanism as TEST

Alternative Deployment: Downloading ItemSets via IDE

If deploy links are not configured, ItemSets can be downloaded manually via the IDE: 1. Select Source Control > Show CCR Controls 2. Click the ItemSet Download link 3. Enter the CCR ID and Access Token 4. Click "List ItemSets" to view available ItemSets 5. Select and download the appropriate ItemSet

---

Change Type Differences

CCR tiers are distinguished by the type of change they manage:

Tier 0 changes include:

• File system path changes
• Memory settings
• User creation
• Patching and upgrades
• Any manual change to the environment or system

Tier 1 changes include:

• Classes
• Routines
• Reports
• CSP Pages
• JavaScript
• Integration logic
• DTL (Data Transformation Language)
• Productions

Tier 2 changes (for reference) include:

• Layouts
• Security groups
• Code table changes
• Workflow

Workflow Differences

The Tier 1 workflow adds several capabilities beyond Tier 0:

• Source control integration: Changes made via Studio, Atelier, or VS Code are automatically tracked and versioned within the Perforce source control system
• ItemSet transport: Items are bundled into ItemSets for transport between environments, rather than manual implementation
• Automatic versioning: Every change is recorded with version history in Perforce

Documentation Differences

Tier 1 CCRs differ from Tier 0 in their documentation approach:

• Implementation Plan: Auto-populated with standard text assuming changes will be implemented via ItemSet deployment. It is critical to modify this plan if any manual steps are required beyond ItemSet deployment.
• Backout Plan: Also auto-populated with standard ItemSet-based backout procedures
• Modified Items: The list of modified items is usually auto-populated from submitted changes and should match the list of items in the Uncommitted Queue

Perforce Branch Synchronization

A critical Tier 1 requirement is keeping the Perforce branch synchronized with the TEST and LIVE environments. Proper use of the CCR process (including all transitions and deployments) maintains this synchronization automatically. Failing to deploy ItemSets promptly or skipping workflow steps can cause the Perforce branch to diverge from what is actually running in TEST or LIVE.

Target Audience

CCR Tier 1 training (ICC5nn courses) is focused on hands-on technical topics and is most relevant to:

• Users who write custom integration code using InterSystems Studio or VS Code
• Users who work on custom DTL within InterSystems HealthShare or Ensemble
• Users who develop classes, routines, or other source items

Non-technical users (e.g., TrakCare Application Specialists) should focus on Tier 2 training, which covers TrakCare configuration changes. All users should complete the Introduction course (ICC500) for general awareness.

---