01. Getting started

Getting Started

Installing IPM

1. Go to the latest release and download the XML file.

2. Import it into IRIS and compile via any desired way (Management Portal, Studio or Terminal)

If you are working with InterSystems IRIS Community Edition in Docker, you can use Docker Images, which already include IPM instead of step 1 and 2.

3. Check that calling zpm in the command line results in the following

    USER>zpm

    =============================================================================
    || Welcome to the Package Manager Shell (ZPM).                             ||
    || Enter q/quit to exit the shell. Enter ?/help to view available commands ||
    =============================================================================
    zpm:USER>

Prior to IPM 0.9.0, this would automatically be available in all namespaces. To make IPM available in all namespaces as of 0.9.0, run:

zpm "enable -map -globally"

(3.1). After version 0.9.2, you can also call

zpm "enable -community"

This will reset the zpm installation to the community repository and map IPM to all namespaces. If using this method, you can update zpm to newer version by running

zpm "reinstall zpm"

4. To get the list of all available modules use search command

    zpm: USER>search
    registry https://pm.community.intersystems.com:
    analyzethis 1.1.4
    dsw 2.1.41
    objectscript-package-template 1.0.3

The Registry pm.community.intersystems.com is used by default.

5. Install a module using install command:

    zpm: USER>install objectscript-package-template

or

    zpm: USER>install objectscript-package-template -v

Key -v (-verbose) produces verbose output from the command.

Using IPM

IPM can used:

• through the interactive or application-style shell entry point for direct command execution
• through a script-friendly pipeline entry point for automation and CI/CD use cases

Using IPM through the CLI

IPM can be used from the command line in two complementary ways:

• interactively, by entering the zpm shell from the terminal
• non-interactively, by passing an IPM command string directly to zpm

For example, you can start the interactive shell with:

USER>zpm
zpm:USER>

From there, you can run commands such as:

zpm:USER>repo -list
zpm:USER>install objectscript-package-template -v
zpm:USER>quit
USER>

You can also invoke the same functionality in a one-shot form:

USER>zpm "repo -list"
USER>zpm "install objectscript-package-template -v"

Using IPM in a CI/CD Pipeline

Using Shell()

Shell() runs a single IPM command string and returns a %Status value. For example:

set sc = ##class(%IPM.Main).Shell("repo -list")
if $$$ISERR(sc) {
    write "The command failed.",!
}

Using ShellScript()

ShellScript() is the shell-oriented wrapper for running an IPM command.

It is useful when the command is being driven from a script or OS-style workflow where you want:

• output written to a log file
• process termination on failure when that is preferred

Arguments

ClassMethod ShellScript(
    pCommand As %String,
    pOutputLogFile As %String = "",
    pAppendToLog As %Boolean = 0,
    pTerminateOnError As %Boolean = 1) As %Status

• pCommand

  • The IPM command string to execute, such as repo -list or load /path/to/module.

• pOutputLogFile

  • Optional path to a file that receives the shell-style command output.
  • If omitted, the command runs without redirecting output to a file.

• pAppendToLog

  • Controls whether the output log file is appended to or replaced.
  • Use 1 to append to an existing file.
  • Use 0 to start a fresh log file.

• pTerminateOnError

  • Availability: IPM v0.10.9-beta.4+
  • Controls whether the process should terminate when the command fails.
  • Use 1 for script-style failure behavior.
  • Use 0 if you want the method to return the error status instead of stopping the process.

Example use of ShellScript()

set sc = ##class(%IPM.Main).ShellScript(
    "load /path/to/module",
    "/tmp/zpm-shell.log",
    0,
    1)

Updating IPM

To update IPM to a newer version, you can just grab a newer release from latest release, and follow the same procedure as a new install

If you have enabled ipm globally using -zpm "enable -map -globally"-, then this newer version will automatically be used in the rest of the namespaces on your instance as well.

If you are using the community version of ipm, then all you have to do is run

zpm "reinstall zpm" 

to get the newest version!

Setting up an ORAS repository

Note: this requires a Python version >= 3.10.0 and <3.13.0

As of version 0.10.0, IPM supports OCI repositories through ORAS, which allows use of industry-standard registries like Docker Hub, AWS ECS, Artifactory, and Azure Artifacts. To configure an OCI registry in IPM, run zpm repo, select the ORAS option, and then provide a name and URL for the registry. Alternatively, a one liner can be used: zpm repo -o -name <registry-name> -url <registry-url>

Authorization credentials can be provided in the same way as an HTTPS repository: with -username, -password, and -token.

Updating an installed module?

See Updating an IPM Module (IPM v0.10.4+) for zpm "update" usage and how to add update steps to your module.