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 510: CCR Tier 1 –Usage Basics

0 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Objectives
 Demonstrate the CCR process to develop and progress a CCR
Tier 1 (Source-Controlled) change through a CCR managed
System.
 Describe the programmatic tools available to tailor code to
CCR environments.
 Explain the differences between submitting changes from a
Connected vs a Disconnected BASE environment.
 Progress Tier 1 CCRs through systems with secondary
environments.
1 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Review: Client Tools
 Most functionality discussed comes from Client Tools.
 Library of code shared by all namespaces in instance.

 Client Tools improved several times per year.
 If your functionality or screens differ from slides, most likely
need to update client tools.
 Low-risk change.

 To update: Choose 1 system to always maintain Client Tools.
 Click update Client Tools on system details page.
 Follow implementation and testing plan of generated CCR.
2 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Part 1: CCR PREP Phase

3 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Tier 1 Considerations: In_PREP
 Confirm Tier field set to “1 – Source Control.” Modified Items: Usually matches list of submitted changes.
 Perform markPREPComplete transition before checking out
files.
 Only make changes while in In_BASE state.

4 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Quiz: In_PREP for Tier 1
Question:
When planning work during In_PREP for a Tier 1 CCR, a user
should ‘check out’ any files from BASE which they think they
will change in order to ensure that others know the scope of
the work they intend to do. True or False?

Answer:False. Nothing in BASE should be touched while a CCR is still in
the PREP phase.
5 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Part 2: CCR BASE Phase: Making Changes

6 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Progressing a Tier 1 CCR…
createIn_BASEIn_PREP

ItemSetactivity
Perforce
activity

PREP

BASE

7 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Tier 1 Considerations: In_BASE Work performed via IDE and/or the Management Portal.
 In order to progress, record must have either: Changelist.
 Uncommitted ItemSet.

 Implementation Plan and Backout Plan have default values
 Only change if manual steps needed.

8 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Using VS Code - ObjectScript with CCR
 Use server-side mode to connect to BASE.
 Can download workspace definition from System Details page in CCR.

 Source Control button appears when viewing items in CCR configured
namespace.

9 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Using Studio with CCR
 Source Control menu available when connected to CCR configured
namespace.

Disconnected BASE

10 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Connected BASE (InterSystems
Internal Applications)

Working with Controlled Items
 Source Control menu used for interacting with source control
hooks.
 Non-BASE environments locked.
 Existing items read-only in IDE and cannot be checked out.
 Cannot create new items in IDE.

11 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Concurrency Control within Instance Must guarantee user has exclusive access to edit item.
 Controlled by checking out an item before editing it.
 Checkout status removed when submit changes.

 If multiple users could edit an item simultaneously: All changes submitted to one CCR.
 Changes from other users could be incomplete at time of upload.

 Diff changes would show other user’s changes.
 User who made change not highlighted.
 User submitting change would need to notice diffs they did not cause.

12 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Environment Source Control Summary
 Exports code as xml files to source workspace.
 System controls whether exported files are read-only or
read/write.
 Do not manually change R/W status of any files.
 Will break source control integration.

 On checkout, duplicates file to create .bak file.
 Used to: Revert changes.
 Diff changes.

13 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Create New Item On first save, IDE prompts whether to add to source control.
 Choose yes.

 Can also use Add To Source Control menu option.
 Either way, on add:
 Item exported as writable XML.
 Routines are exported as .rtn RO files for legacy reasons.

 Item checked out to your username.
 Item added to Uncommitted Queue with add action.

14 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Edit Existing Item Cannot checkout item checked-out to another username.
 2 ways to checkout:
 Start making change.
 Popup message prompts to confirm checkout.

 Open item, then use checkout menu option.

 Check out action:
 Guarantees only your user can make changes.
 Backup file created to enable revert.
 For connected BASE, checks out item in Perforce as well.
 InterSystems internal applications.
15 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Identify Changes Made to Checked Out File Compares current exported file with .bak version,
highlighting changed lines.
 Important because indicates exactly what will be uploaded.

 If changes missing, most likely did not compile code.
 Changes exported with successful compilation.

16 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Diff Changes
 2 equivalent ways to reach Quick
Diff page.
 From IDE, Source Control Menu >Show CCR Controls > ItemSet
Bundle > Click diff link forappropriate item.
 With item open in IDE, go to Source
Control Menu > Diff Against Last
Version.

 Client tools before 2019-Sep-20,
click Compute Diff.
 Current client tools automaticallycompute.
17 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Delete Existing Item On delete from IDE, popup message prompts to remove
from source control.
 Choose yes.

 Deletes item from database and source workspace.
 Adds delete action to uncommitted queue.
 Disconnected BASE: Bundle and upload to CCR.
 Connected BASE: Submit to Perforce.

18 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Revert Changes Not Uploaded to CCR
 To delete new item (not uploaded to CCR): Open item then use Undo Add menu option.
 Delete item in IDE.
 Choose no in popup message asking to remove from source control.

 To undo all changes made to checked out file (and not yet
uploaded): Open item then use Undo Check Out menu option.

19 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Quiz: Quick Diff
Question:
Which of the following is true about the Quick Diff functionality
in the client tools in disconnected BASE environments?
A. It compares the Perforce head revision to the version in theIDE.
B. It compares the Perforce head revision to the exported
version in the source workspace.
C. It compares the .bak version in the source workspace to theexported .xml version in the source workspace.
D. It compares the .bak version in the source workspace to theversion in the IDE.
20 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Quiz: Quick Diff (cont.)
Answer:C. It compares the .bak version in the source workspace tothe exported .xml version in the source workspace.

21 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Quiz: Concurrency Controls
Question:
Who can edit, or bundle and upload a class definition that has
been checked out to John Smith?
A. Only John Smith.
B. Whoever owns the CCR.
C. Anyone from John Smith’s organization.
D. John Smith and anyone with the %ALL role in theenvironment.

22 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Quiz: Concurrency Controls (cont.)
Answer:A. Only John Smith.

23 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Part 3: CCR BASE Phase: Tools for Developers

24 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Advanced Tip: CCR Built-in Functions
 Allow your code to vary its behavior based on the current
environment.
 $$IsLIVE^%buildccr.
 Prevent emails from being sent to actual users from BASE or TEST.

 $$Env^%buildccr.
 Display the environment in email footers, UI headers, etc (BASE, TEST, UAT or
LIVE).

 $$EnvName^%buildccr.
 Test the environment name to perform customized logic (e.g. for TRAIN, which
is a peer to TEST).

25 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Advanced Tip: CCR Built-in Functions (cont.) Allow your code to vary its behavior based on the current
environment.
 $$Sys^%buildccr.
 Put SystemCode in error logs.

 $$Org^%buildccr.
 Include organization details in email alerts to centralized monitoring system.

26 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Automating Deployment Tasks
 ImplementCCR routines are per CCR custom ItemSet load
logic.
 Case-sensitive naming requirement: ImplementCCR.<CCR_ID>.
 Example: CCRID of BEST0001 would require routine name
ImplementCCR.BEST0001.
 Client Tools automatically run routine during ItemSet deployment, if exists.
 Run after importing and compiling all code in ItemSet.

27 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Automating Deployment Tasks (cont.) CCR Event Handlers are per System custom ItemSet load
logic.
 Create class that extends %Studio.SourceControl.CCREventHandler.
 Create callback methods.
 See method stubs in %Studio.SourceControl.CCREventHandler.

 Set ^SYS("SourceControl","EventHandler","Class")="MyClassName." Write statements directed to Transport Log.

28 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Quiz: ImplementCCR Routines
Which of the following is true about ImplementCCR Routines.
A. They are executed automatically on ItemSet deployment.
B. The name is not case-sensitive.
C. You will get an error if you try to upload a routine named
ImplementCCR.BEST12345 to CCR BEST6789.
D. They cannot contain CCR built-in functions such as$$Env^%buildccr.
Answer: A

29 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Part 4: CCR BASE Phase: Submitting Changes

30 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Review: Sending Items from Disconnected BASE

Upload31 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Bundle Screen From IDE, Source Control > Show
CCR Controls > ItemSet Bundle.
 Filters have no effect on what isbundled.
 Diff link discussed on previous
slide.
 Select what to bundle.
 Access Token and CCR ID from
CCR.
 Confirm CCR Details.
 Validates CCR state and System.

 Click Bundle and Upload.

32 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Review: Sending Items from Connected BASE

33 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Connected: CCR Client  Perforce
 To submit changes from a
Connected BASE:
1. From IDE, Source Control > Checkin.
2. If prompted, enter Perforce
password.
3. Click diff link for each item to besubmitted.
 Always diff changes; know whatchanges you submit!

4. Select item(s) to check in.

34 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Connected: CCR Client  Perforce
 To submit changes from a
Connected BASE:
5. Copy and paste <CCR ID> <Title> from CCR title bar to
Description. Include additional
details if desired.
6. Copy CCR ID and paste into Job
field (required).

7. Click “Submit.”

35 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Verify Submitted Changes
 After submit changes, always verify correct items listed in CCR.
 Under Perforce Details of CCR, click Submitted Changes tab.

36 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Bundle and Upload Validation(Client tools 2019-Dec-12)
 Bundle and Upload screen for Tier 1 systems validates: Access key.
 Whether CCR ID exists.
 State of CCR.
 System for CCR vs current namespace.

 Revalidation triggered by: Changing access key.
 Changing CCR ID.
 Clicking
icon at end of error message.

37 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Bundle and Upload: Invalid Access Token Indicated by x next to Access Token field.
 Most likely a typo.

38 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Bundle and Upload: Invalid State Valid states: In_BASE.
 BASE_Pending_Peer_Review.

 Solution:
 If current state In_PREP perform
markPREPComplete transition.
 If current state past
BASE_Pending_Peer_Review, either: Use catch-up CCR to progress change
to original CCR (preferred method).
 Use backwards transitions to returnto In_BASE, backing out changes
appropriately.

39 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Bundle and Upload: Invalid System
 System of CCR does not match
System of environment.
 Causes and solution:
 Wrong CCR.
 Enter correct CCR ID.

 Created CCR for wrong system.
 System field editable until upload
first ItemSet.
 Edit CCR to change System.

 Made change in wrong namespace.
 Revert and make change in correct
namespace.

40 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Part 5: Moving to TEST Environment

41 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Quiz: Automatic Integration
Question:
The passPeerReview will kick off the automatic integration tomove the diff chunks into the next branch and create an
ItemSet. True or False?
Answer:False. passPeerReview will start an “Integration Preview” (ifthe peer reviewer is a Perforce User), but it will not submit the
integration nor create an ItemSet. Automatic integration takes
place when the CCR owner performs a transition including thephrase “startMove”.
42 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

(authorizeAnd)StartMoveToTEST Only perform authorizeAndStartMoveToTEST or startMoveToTEST when
ready to move change.
 Immediately deploy ItemSet.
 Delaying or abandoning ItemSet deployment will cause problems later.

43 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Review: Transport Walkthrough - Integrating from
BASE

startMoveToTEST

44 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Review: Transport Walkthrough - Sending To
TEST
Download

45 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Pending_Manual_Move_To_TEST
 ItemSet created by transition into this state.
 Deploy using deploy to TEST link under Perforce Details of CCR.
 Opens web page on TEST Environment.
 Log in using credentials for TEST Environment.
 After log in, ItemSet download and item import process begins automatically.

46 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Downloading an ItemSet via IDE
 If ‘deploy’ links are notconfigured, ItemSets can be
downloaded via IDE:
1. Select “Source Control” menu >Show CCR Controls.
2. Click ItemSet Download link.
3. Type the CCR ID into the Download
ItemSet form.
 Make sure it is accurate!

47 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Downloading an ItemSet via IDE (cont.)
 If ‘deploy’ links are notconfigured, ItemSets can be
downloaded via IDE:
4. Copy the “Access Token” from the
Perforce Pane on the CCR and paste
it into the Download ItemSet form.
5. Click “List ItemSets.”
6. A list of available ItemSets willappear, select “download”
on the newest one (the last one in
the list).
 If only one exists, it willautomatically begin to download.
48 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Automatic markMoveToTESTComplete markMoveToTESTComplete automatically occurs if:
 No changes made to default Implementation Plan.
 ItemSet successfully deployed to all TEST environments that haveRequire ItemSet.

 Row in Transition History has note “{transition occurred
automatically due to successful ItemSet load in TEST}”.

49 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Quiz: Automatic Transitions
Question:
Tier 1 CCRs with a default (unedited) Implementation Plan will
have the markManualMoveToTEST transition occur
automatically once the ItemSet has been deployed to allenvironments in TEST which require ItemSets.
True or False?

50 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Quiz: Automatic Transitions (cont.)
Answer:
True.
Editing the Implementation Plan to add manual steps will
mean that the CCR user must perform themarkManualMoveToTEST/LIVE manually after completing themanual pieces of the Implementation Plan.

51 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Part 6: Test, Review, Deploy, Repeat

52 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Progress CCR to LIVE Perforce integration and ItemSet creation workflow same asmoving to TEST.
 Integration from TEST to LIVE occurs on *StartMoveToLIVE
transitions.
 ItemSet automatically created and available for deployment under
Perforce Details upon successful integration.

53 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Class List Exercises
Class

MethodPersonDetails.Teacher01

OutputHTML

Do ##class(PersonDetails.ClassList).RegisterStudent(“Teacher01”, “OutputHTML”)

54 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Exercise ICC510-1 through ICC510-6

55 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Part 8: Additional Information

56 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Tier 1 Transport Load To Namespace Flow
 After Tier 1 items are loaded to the workspace, a number of
additional things occur.
1. If a CCR Event Handler is configured, the ItemSetAfterLoadToOS()
method is executed.
2. Any items in Tier 1 SubFolders are automatically loaded into thenamespace: /cls (class files).
 /cspapp (web files e.g. JavaScript, CSP, CSS).
 /inc (include files).
 /prj (project files).
 /rtn (routines).
57 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Tier 1 Transport Load To Namespace Flow (cont.)
 After Tier 1 items are loaded to the workspace, a number of
additional things occur.
3. As they are loaded, all items are added to a project named after the
ItemSet.
4. The project is compiled (which compiles all items in the properorder).
5. If an ImplementCCR routine exists for that CCR, it is executed.
6. If a CCR Event Handler is configured, the ItemSetAfterLoadToNS()
method is executed.

58 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2

Summary What are the key points for this module?

59 | InterSystems Change Control | CCR Tier 1 – Usage Basics | ICC510 v4.2