T2.3: Uses Source Control with InterSystems IRIS

Knowledge Review - InterSystems IRIS Development Professional

1. Understands source control system integration options (client-side vs. server-side)

Key Points

  • Client-Side Integration: VS Code and IDEs manage source files locally with Git workflows
  • Server-Side Integration: %Studio.SourceControl hooks execute on IRIS server during compile/save
  • REST API Foundation: Source Code File REST API enables modern client-side tooling
  • Hybrid Approach: Combine client Git repositories with server-side validation hooks
  • Development Models: Server-first (traditional) vs. client-first (modern) development patterns

Detailed Notes

Overview

InterSystems IRIS supports two primary source control integration architectures, each with distinct characteristics and use cases.

Client-Side Integration

  • Tools: VS Code with the ObjectScript extension using the Source Code File REST API
  • Workflow: Developers maintain Git repositories on their local workstations, edit code in text editors, and synchronize changes to IRIS
  • REST API Methods: GetDoc, PutDoc, GetDocNames, and Compile for retrieving, updating, and compiling code remotely
  • Benefits: Aligns with contemporary development practices, supports standard Git workflows (branching, merging, pull requests)

Server-Side Integration

  • Framework: %Studio.SourceControl class framework with hooks executing within the IRIS server
  • Event Hooks: Intercept events such as before/after save, before/after compile, before/after delete, and check-in/check-out
  • Capabilities: Direct access to IRIS internals, policy enforcement before allowing operations
  • Limitations: Requires developers to work primarily within IRIS-centric tools

Hybrid Approach

  • Developers use Git and VS Code for their daily workflow
  • Server-side hooks provide additional validation, logging, or integration with enterprise systems
  • Example: Client-side Git for version control with server-side hooks preventing deployment of classes without proper documentation

Choosing a Model

Development teams must choose their model based on:

  • Team size
  • Existing tooling
  • CI/CD requirements
  • Organizational standards

Modern IRIS development increasingly favors client-side integration due to its alignment with DevOps practices and cloud-native development patterns.

Documentation References

2. Implements mitigation strategies for updated class/schema imports

Key Points

  • Compilation Order: Class compiler generates dependency lists and compiles dependencies first
  • Import Directive: Use Import directive to resolve package dependencies during compilation
  • Incremental Compilation: Compile modified dependencies automatically with /compile flag
  • Schema Conflicts: Address table/column changes with $SYSTEM.SQL.Schema.ImportDDL() validation
  • Deployment Strategies: Use $SYSTEM.OBJ.LoadDir() with flags for controlled imports
  • Rollback Protection: Validate imports in test environments before production deployment

Detailed Notes

Overview

When importing updated classes and schema definitions into InterSystems IRIS, developers must implement strategies to mitigate risks associated with compilation dependencies, schema changes, and deployment failures.

Automatic Dependency Management

The class compiler automatically manages basic dependencies by:

  • Generating a list of classes that must be compiled first
  • Resolving inheritance hierarchies
  • Determining storage structures for persistent classes

Complex scenarios require explicit management through Import directives and compilation flags.

Import Directive

  • Syntax: `Import (Package1, Package2)` before the Class definition
  • Function: Allows the compiler to resolve short class names by searching specified packages
  • Default Packages: Current package, %Library, and User packages
  • Benefit: Prevents compilation errors when classes reference other classes without fully qualified names

Compilation Flags

  • /compile: Automatically compile modified dependencies
  • "ck": Compile with check compile
  • "d": Display output
  • "k": Keep source code

Use $SYSTEM.OBJ methods like Compile(), Load(), and CompileList() with these flags.

Schema-Related Challenges

  • Persistent class changes affect underlying SQL tables and indices
  • Conflicting changes (datatype modifications, adding required properties with existing data) can cause import failures

Mitigation Strategies

  • Pre-validate schema changes using $SYSTEM.SQL.Schema.ImportDDL()
  • Use Storage Default mechanism to customize class-to-storage mapping
  • Implement data migration routines in %OnBeforeSave() or separate utility classes
  • Test imports in non-production environments before production deployment

Deployment Best Practices

  • Use $SYSTEM.OBJ.LoadDir() with flags "/compile/displaylog/displayerror"
  • Maintain source control tags/branches corresponding to deployed versions
  • Use GetModifiedDocNames REST API for hash-based change detection
  • Export classes using $SYSTEM.OBJ.Export() for backup before major imports
  • Maintain separate dev/test/prod environments with controlled promotion processes
  • Implement automated testing that runs after imports

Documentation References

Exam Preparation Summary

Critical Concepts to Master:

  1. Source Control Models: Understand differences between client-side (REST API/Git) and server-side (%Studio.SourceControl hooks)
  2. REST API Methods: Know key methods (GetDoc, PutDoc, GetDocNames, GetModifiedDocNames, Compile)
  3. VS Code Integration: Understand how modern IDEs connect to IRIS using the Source Code File REST API
  4. Server-Side Hooks: Recognize when server-side source control hooks execute (save, compile, delete operations)
  5. Compilation Dependencies: Understand how the class compiler resolves dependencies and import directives
  6. Import Strategies: Know how to use $SYSTEM.OBJ methods with appropriate flags for controlled imports
  7. Schema Changes: Understand risks when importing updated persistent classes with schema modifications
  8. Rollback Protection: Know techniques for validating imports and maintaining backup/recovery options

Common Exam Scenarios:

  • Selecting appropriate source control integration approach for a development team
  • Troubleshooting compilation errors related to package imports and dependencies
  • Implementing deployment procedures that handle schema evolution safely
  • Configuring VS Code connectivity to IRIS using the REST API
  • Using GetModifiedDocNames to detect changed files and avoid conflicts
  • Applying compilation flags to manage dependency updates during imports
  • Designing rollback strategies for failed class/schema imports
  • Distinguishing when to use client-side vs. server-side source control integration

Hands-On Practice Recommendations:

  • Configure VS Code ObjectScript extension and connect to an IRIS instance
  • Experiment with the Source Code File REST API using tools like Postman or curl
  • Import classes using $SYSTEM.OBJ.Load() and CompileList() with various flags
  • Create test scenarios that modify persistent class schemas and handle migration
  • Use GetModifiedDocNames to track changes and implement change detection logic
  • Practice export/import cycles with XML files as backup/recovery mechanism
  • Implement simple %Studio.SourceControl subclass to understand server-side hooks
  • Test deployment workflows across development, test, and production environments
  • Use Import directives to resolve package dependencies in class definitions
  • Validate schema changes using $SYSTEM.SQL.Schema methods before production import

Key Terms and Definitions:

  • Client-Side Integration: Source control managed in developer workspace using Git and modern IDEs
  • Server-Side Integration: Source control hooks executing within IRIS server during operations
  • Source Code File REST API: HTTP REST API providing access to IRIS source code files for IDEs
  • GetDoc/PutDoc: REST API methods to retrieve and update source code files remotely
  • GetModifiedDocNames: REST API method returning file names with hash for change detection
  • %Studio.SourceControl: Base class for implementing server-side source control hooks
  • Import Directive: Class declaration directive specifying packages for short class name resolution
  • Compilation Flags: Parameters like "ck", "d", "k" controlling compile behavior
  • Schema Evolution: Process of modifying persistent class storage structures with existing data
  • $SYSTEM.OBJ: System class providing methods for loading, compiling, and managing code
  • Storage Compiler: Component determining storage structures for persistent/serial classes
  • Dependency Resolution: Compiler process identifying and compiling dependent classes first
  • Incremental Compilation: Compiling only modified classes and their changed dependencies
  • LoadDir(): Method importing all source files from a directory with compilation options
  • Export/Import XML: Backup/restore mechanism using XML file format for classes and routines

Important Configuration Points:

  • REST API endpoint: `https://server:port/api/atelier/`
  • API version paths: `/v1/` and `/v2/` for different API generations
  • Authentication: Requires Authorization header with username/password credentials
  • Content-Type: Must specify `application/json` for POST/PUT operations
  • If-None-Match header: Enables conditional GET to retrieve only modified files
  • Web application: REST API exposed through web app with %Api.Atelier dispatch class
  • Compile flags: "/compile", "/displaylog", "/displayerror" for LoadDir operations
  • Namespace context: All REST API calls specify target namespace in URL path

Risk Mitigation Checklist:

  1. Always export classes to XML backup before major imports
  2. Test schema changes in non-production environments first
  3. Use GetModifiedDocNames hash values to detect concurrent modifications
  4. Implement automated tests that run after imports to validate functionality
  5. Maintain separate dev/test/prod environments with controlled promotion
  6. Document dependencies and import order for complex class hierarchies
  7. Use version control tags/branches corresponding to deployed versions
  8. Validate DDL changes with $SYSTEM.SQL.Schema methods before import
  9. Plan data migration strategies for persistent classes with existing data
  10. Establish rollback procedures and practice recovery scenarios

Report an Issue