INTERSYSTEMS LEARNING SERVICES

InterSystems Change Control

InterSystems Change Control

Confidential - Do Not Duplicate

COPYRIGHT NOTICE© 2020 InterSystems Corporation, Cambridge, MA. All rights reserved.
InterSystems is a registered trademark of InterSystems Corporation.

InterSystems, InterSystems Caché, InterSystems Ensemble, InterSystems HealthShare, HealthShare, InterSystems TrakCare,
TrakCare, InterSystems DeepSee, and DeepSee are registered trademarks of InterSystems Corporation.

InterSystems IRIS data platform, InterSystems IRIS for Health, InterSystems IRIS, InterSystems iKnow, Zen, and Caché Server Pages
are trademarks of InterSystems Corporation.
All other brand or product names used herein are trademarks or registered trademarks of their respective companies or organizations.
This document contains trade secret and confidential information which is the property of InterSystems Corporation, One Memorial
Drive, Cambridge, MA 02142, or its affiliates, and is furnished for the sole purpose of the operation and maintenance of the products ofInterSystems Corporation. No part of this publication is to be used for any other purpose, and this publication is not to be reproduced,
copied, disclosed, transmitted, stored in a retrieval system or translated into any human or computer language, in any form, by anymeans, in whole or in part, without the express prior written consent of InterSystems Corporation.
The copying, use and disposition of this document and the software programs described herein is prohibited except to the limited extent
set forth in the standard software license agreement(s) of InterSystems Corporation covering such programs and related
documentation. InterSystems Corporation makes no representations and warranties concerning such software programs other thanthose set forth in such standard software license agreement(s). In addition, the liability of InterSystems Corporation for any losses ordamages relating to or arising out of the use of such software programs is limited in the manner set forth in such standard software
license agreement(s).
THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY INTERSYSTEMSCORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER SOFTWARE. FOR COMPLETE
INFORMATION REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE LICENSE AGREEMENT(S) OF
INTERSYSTEMS CORPORATION, COPIES OF WHICH WILL BE MADE AVAILABLE UPON REQUEST.
InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves the right, in its sole
discretion and without notice, to make substitutions and modifications in the products and practices described in this document.
For Support questions about any InterSystems products, contact:
InterSystems WorldWide Response Center
Telephone: +1-617-621-0700
Tel: +44 (0) 844 854 2917
Email: support@InterSystems.com

Confidential - Do Not Duplicate

ICC 450: CCR Transport –Best Practices &Debugging Techniques

0 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Overview Additional changes past BASE phase.
 Revision History.
 Transport Logs.
 Manual integration within CCR.
 Perforce integration conflicts.
 Backing out.
 Fixing workflow issues.
 Updating Client Tools.

1 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Part 1: Additional Changes Past BASE Phase

2 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Additional Changes Past BASE Phase Reasons need to make or upload additional changes past
BASE include: Neglected to bundle and upload all changed items.
 Minor typos or fixes necessary in code.

 Cannot bundle and upload changes against CCR in or past
BASE_Complete.
 Enforced in current client tool version (2019-Dec-12).
 Reasons include: Changes not peer reviewed in BASE.
 If past authorizeAndStartMoveToTEST, changes not automatically integrated.
3 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Additional Changes Past BASE Phase (cont.) Solution, either: Backwards transition(s) to return to BASE.
 Requires backout if past BASE phase.

 Use concept of catch-up CCR.
 No special type of CCR, only conceptual.
 Ensures additional changes follow proper workflow, including peer review andintegration.

4 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Additional Changes Past BASE Phase (cont.)
 Similar to progressing changes, backing out changes cancause merge conflicts.
 Resolving merge conflicts time consuming and, depending
complexity, introduces risk.
 Makes catch-up CCR more desirable.

 If do not want to use catch-up CCR:
 Do preview backout and verify no merge conflict before performing
any backwards transition.

5 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

How To: Use Catch-up CCR
1. Create new CCR or clone original CCR and trim details as
required.
 Specify original CCR as Prerequisite CCR.
 Consider using Title field to designate as catch up.

2. Progress to In_BASE state.
3. Make and upload changes.
 Or upload changed items left behind.

4. Document, test, and progress catch-up CCR to same state
as original CCR.
6 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

How To: Use Catch-up CCR (cont.)
5. Merge catch-up CCR into original CCR.
 Source is catch-up CCR, target is original CCR.
 Documentation and Perforce changelists from catch-up associatedwith original CCR.

6. Progress original CCR.
 Will integrate all Perforce changes from original and catch-up CCR.

7 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Quiz: Catch-up CCRs
Question:
Backout from TEST is always an easy, low-risk task.
True or False?

Answer:False. Cannot easily backout if changes made in BASE on topof changes that need to be backed out.
8 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Part 2: Leveraging Revision History

9 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Revision History
 For file chosen, enumerates:
 Each revision to item.
 CCR ID associated with each changelist.
 Whether that CCR is active, along with other CCR details.
 Active = not in Closed, Merged, or Cancelled state.

 Useful for:
 Identifying other active CCRs which may collide with current CCR.
 Understanding how frequently an item is changed.
 Spotting anomalies in the Revision History.
 Example: changelist without job which could break future integration.
10 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Access Revision History from CCR
1. Open CCR of interest.
2. Click Submitted Changes tab.
3. Clicknext to item of interest.

11 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Access Revision History from IDE
1. Open file of interest in IDE.
2. Source Control menu > Show CCR File History.

12 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Revision History Functionality
 Color-coded, with the legend at top.
 Click diff link to diff that revision versus previous revision.
 Links to CCR that changelist is associated with.
 Click BASE link to view revision history of corresponding item
in BASE.

13 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Understanding Revision History
 Notice yellow revision #4 is CCR used to accesshistory.
 Not concerned about revision #1.
 Not highlighted.
 Assuming proper procedures followed, should have left
all branches in clean state.

 Possible #2 and #3 block #4 from progressing
to TEST.
 Would block if overlapping changes.
 Pink, therefore active and not progressed all the way toLIVE.
 Chronologically before #4 therefore overlappingchanges must progress before #4.
14 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Quiz: Using Revision History and Transport Logs
Question:
The ‘history’ link under show submitted changes has links toshow diffs of the current version against every other version.
True or False?
Answer: False.
Revision History only has diffs between versions, not thecurrent version against all other versions. Within CCR, it is
only possible to diff any version against any other version fromthe view page.
15 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Part 3: Using Transport Logs

16 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Transport Logs
 Contain record of Perforce and ItemSet activity for that CCR.
 ItemSet uploads / commits.
 Perforce integrations.

 ItemSet creation for download.
 ItemSet load log (uploaded from the client).

 To access Transport Log, click View or Download in Perforce Details.

17 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Viewing Transport Log
 Click [jump to bottom]
hyperlink to access endof log.
 Typically most recent error
at bottom.

 Reviewing log great way
to better understand CCR
automation.

18 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Clear CCR Transport Alerts from Perforce Details
 Alerts in Perforce Details usually cleared through corrective action,such as successful integration.
 For alerts not cleared automatically, clear manually after corrective
action completed: Open transport log > click [clear alert].

 Cleared alerts:
 Still available in transport log.

 Inform other users that the alert is no longer an issue.

19 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Quiz: Using Revision History and Transport Logs
Question:Transport Logs includes all logging which occurred by
Perforce-related actions which occurred against that CCR or its
ItemSets. True or False?

Answer: True.

20 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Quiz: Perforce Alerts
Question:
It is an acceptable practice to leave Perforce Alerts displayedon a CCR and to learn to overlook them when they appear.
True or False?
Answer: False.
Perforce Alerts mean something unexpected occurred and the
CCR Owner has the responsibility to understand what occurred
and whether corrective action is required; engage Support if
necessary to understand what took place.
21 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Part 4: Manual Integration

22 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Manually Integrate Changes
 2 use cases: Part of process of resolving merge conflict on
authorizeAndStartMoveToXXXX.
 Manually trigger preview before performing
authorizeAndStartMoveToXXXX.

23 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

How To: Manually Integrate Changes
1. Perforce Details > Perforce Integration.
2. Verify menu for integration environments correct.
3. Select or clear Preview checkbox appropriately.
Preview will not commit integration but rather return any predicted conflicts.

4. Click Integrate.

24 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Part 5: Perforce Integration Conflicts

25 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Quiz: Merge Conflicts
Question:
The following will cause a merge conflict. Change #1 is madebut not progressed before #2 is made and progressed to
TEST. True or False?
#2
#1

#2

?

Answer: True.
26 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Perforce Integration Failed Alert When 1 CCR ID specified, that CCR is definitely the problem.
 When 2+ CCR IDs specified, at least 1 of them is the problem.

Warning from preview
integration

Error from
authorizeAndStartMoveToTEST

27 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Perforce Integration Failed (cont.) Non-preview integrations shelved for InterSystems support.
 Shelving = temporarily stored but not committed.
 Can safely ignore shelved changelists.

28 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Transport Log for Perforce Integration Errors
 Transport log contains additional information on perforce errors.
 Indicates number of conflicting diff chunks for Perforce integration
errors.

29 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Merge Conflict: Solution
 For this example, merge conflict occurred when CCR A
performed authorizeAndStartMoveToTEST.
 CCR B specified as blocking CCR A.

1. Edit CCR A to specify CCR B as prerequisite.
2. Progress CCR B.
3. Use Perforce controls on CCR A to perform manual
integration from BASE to TEST.
 Make sure to clear preview only box.
 If this integration fails again, contact InterSystems support.

30 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Merge Conflict: Solution (cont.)
4. Deploy generated ItemSet to TEST.
5. Progress CCR A and B normally.
 CCR B must progress ahead of CCR A.

31 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Merge Conflicts Causes
 Merge conflicts can occur due to: A stale CCR that has sat for too long.
 A cancelled CCR which wasn’t properly backed out.
 A circular dependency between two CCRs.
 diff chunks #1, #3 from CCR-A and #2 from CCR-B.

 Lack of proper baselining (discussed later in this course).

32 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Circular Dependency
 Cause: 2+ CCRs dependent on each other.
 2 CCRs both in In_BASE state and the following happens
chronologically.
 CCR A makes change.
 CCR B makes overlapping change.
 CCR A makes change that overlaps with a change in CCR B.

 Solution:
 Merge CCRs.
 To continue progress CCRs individually, manual intervention by
InterSystems support might be possible.
33 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Class Definition Descriptions and Merge Conflicts
 Do not use class descriptions for change documentation.
 Class descriptions with change documentation can cause merge conflicts.
 Keep all change documentation within CCR.

 Example of bad usage of class descriptions for change documentation:

34 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Progressing Edit before Add
 Cause.
 2 different CCRs where 1 adds an item and the other edits the sameitem.
 Will see an error if attempt to integrate the CCR with the edit before
the add.

35 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Progressing Edit before Add (cont.) Reason this is problematic:
 Integrating edit before add causes edit action to become branchaction (similar to add action).
 Backing out branch action causes deletion.
 Therefore, allowing edit to progress first would cause unintentionaldeletion of item if backout necessary.
 Only CCR intending to add item should be able to delete item during
backout.

 On error, Prerequisite CCR field of CCR with edit action
automatically contains ID of CCR with add action.
36 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Progressing Edit before Add (cont.) Error on preview integration:
 WARNING: Prerequisite CCR detected.
 Will not be able to perform authorizeAndStartMoveToXXXX until
progress CCR with add action.

 Error on authorizeAndStartMoveToXXXX:
 Critical error occurred. Another CCR has been detected as aprerequisite and marked as such. Aborting ItemSet creation.
 Must manually integrate changes after progressing prerequisite CCR
to next phase.

37 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Editing Item that Does Not Exist in Perforce ItemSets identify whether changes are edits, adds, or deletes to items.
 Perforce changes edit to add if item does not exist in Perforce.
 Warning message appears on CCR.
 Warning: Misalignment between Perforce branch and environment detected. Any
backout of this change must be performed manually. Please contact support forassistance.

38 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Editing Item that Does Not Exist in Perforce(cont.)
 Does not block progression of CCR towards Closed.
 Progressing CCR risky because cannot backout without
knowledge of change.
 Perforce has no version history to identify changes.
 Backout would cause deletion from Perforce and Environment.
 Automatic backout blocked.

 Contact support if warning shown on any CCR.
 May need to create a new baseline.
 Proper baseline prevents ever seeing this warning.

39 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Part 6: Backing Out

40 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Backout Overview

Perforce
Branches

SystemEnvironments

ItemSet of changes brought from
Perforce to TEST

Integratechanges to BASE
branch Back out changelists fromhighest Perforce branch to which
the change progressed.
 Integrate to other Perforce
branches.
 Create ItemSets based on
Perforce branches for eachenvironment.
 Deploy ItemSets for eachenvironment.

Integratechanges to TEST
branchItemSet of changes brought from
Perforce to LIVE41 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

ItemSet of changes brought from
Perforce to LIVEBackout Overview (cont.)

Perforce
Branches

SystemEnvironments

ItemSet of changes brought from
Perforce to LIVE Automatically triggered.
 Perforce Details section of CCR.

 Direct Perforce intervention.

Integratechanges to TEST
branch 3 ways to backout:

ItemSet of changes brought from
Perforce to TEST

Integratechanges to BASE
branch Covered in ICC460.

ItemSet of changes brought from
Perforce to LIVE42 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Automatic Backout CCR automatically backs out all changes from allenvironments for:
 Tier 1 CCRs only.
 cancel and changeSpec transitions.

 ItemSets for each affected environment generated if Perforce
backout successful.
 Deploy all generated ItemSets like any other ItemSet.

 Progress CCR through next transition after successful
ItemSet deployment.
43 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Back Out Without Automatic Backout For Tier 2 CCRs, see additional considerations in ICC615.
 For markValidationFailed transition on Tier 1 CCRs, must use
manual controls in Perforce Details pane.
 Successful backout using these controls generates ItemSets for allaffected environments.
 Make sure to deploy all ItemSets!

 In the event of backout errors, contact support.
 They may need to intervene using p4v.

44 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Manual Backout Perforce Details > Perforce Backout.

45 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Manual Backout (cont.) Choose furthest Environment to which changes progressed Default usually appropriate.
 Automatically integrates backout to prior environments and creates
ItemSets for all affected Environments.
 Example: Choosing TEST will backout from and create ItemSets for TEST and
BASE.

 Can choose Preview Only to check for merge conflicts.

46 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Manual Backout: Restore to BASE Flag Cleared.
 Removes changes related to this CCR from all environments.
 Use for cancel or changeSpec.

 Selected.
 Maintain changes related to this CCR in BASE.
 Integrates backout changelist to BASE then backs it out toreintroduce change.
 Use for markValidationFailed.
 Still generates ItemSet that must be deployed.
 Version information of items updated.
47 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Quiz: Back out
Question:
Which 1 of the following is FALSE about backing out a CCR
correctly?
A. Requires updating the corresponding Perforce branches.
B. Requires deploying ItemSets, including an ItemSet for BASE.
C. It is not necessary when cancelling a CCR that did not enter
LIVE phase.
D. Requires performing transitions on a CCR.
E. Only users with adequate CCR knowledge should backout
CCRs.
48 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Quiz: Back out (cont.)
Answer:C. It is not necessary when cancelling a CCR that did not enter
LIVE phase.
It is always necessary when cancelling a CCR.

49 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Part 7: Fixing Workflow Issues

50 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Reassigning Tier Level
 Workflow differs between CCR Tiers.
 Click pencil icon to fix CCR Tier if wrong Tier specified during creation.

51 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Upload to Wrong CCR
 Perforce changelists associated with CCRs using Perforce Job
field.
 Job for each changelist set to ID of CCR.

 CCR application does not have functionality to change job ofchangelists.
 Possible using p4v or Swarm.
 Requires access to internal InterSystems network.

 Therefore, customers must contact InterSytems when
specify wrong CCR ID on Bundle and Upload screen.

52 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Quiz: Reassigning Tier Level
Question:
You have to be the CCR owner in order to change the Tierlevel. True or False?
Answer:False.
There is no requirement to assign a CCR to one's self to edit it.
The Tier can be edited and changed by anyone. However, it isprobably best to have the owner make changes to CCRs.
53 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Part 8: Updating Client Tools

54 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Maintaining CCR Client Tools
 Always update CCR Client Tools through same System.
 Maintains accurate version history in Perforce.

 Best practice to configure separate System for %SYS
namespace for:
 Changes that affect entire instance such as hardware or memory
allocations.
 Maintaining CCR Client Tools.

 Alternatively, choose 1 existing System for such updates.
 Example: HSCUSTOM on HealthShare systems.

55 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

How To: Update CCR Client Tools
 Go to appropriate System Details page.
 Click Update Client Tools button.
 Can only be actioned by Perforce users.
 Creates Tier 1 CCR and integrates current client tools to BASE
branch of System.

 Progress generated CCR through normal workflow.
 Make sure to deploy generated ItemSet to BASE.

56 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0

Summary What are the key points for this module?

57 | InterSystems Change Control | CCR Transport – Best Practices & Debugging Techniques | ICC450 v5.0