Skip to main content

Creating and Using an Installation Manifest

This chapter describes how to use the %Installer utility to create an installation manifest describing a specific Caché configuration and use it to generate code to configure a Caché instance. The chapter discusses the following topics:

Overview of an Installation Manifest

The %Installer utility lets you define an installation manifest that describes a specific Caché configuration, rather than a step-by-step installation process. To do so, you create a class that contains an XData block describing the configuration you want, using variables that contain information usually provided during installation (superserver port, operating system, and so on). You also include in the class a method that uses the XData block to generate code to configure the instance. (You can copy and paste this method from this book.)

Once you have defined the manifest, you can call it during installation, from a Terminal session, or from code. The manifest must be run in the %SYS namespace.

Creating a Class That Defines a Manifest

To create a class that defines an installation manifest, create a class as follows:

  • It must include the %occInclude include file.

  • It must contain an XData block specifying the details of the installation.

    You can specify any legal name for the XData block; you use this name later as an argument.

    If you use [XMLNamespace = INSTALLER] after the name of the XData block, Studio provides assistance as you type the XData block.

    The root element in the XData block must be <Manifest>. For details, see “<Manifest> Tags”.

  • It must define the setup() method, as shown in the following example.

  • The setup() method must refer to the XData block by name as shown in the following example.

The following is an example:

Include %occInclude
Class MyPackage.MyInstaller
XData MyInstall [ XMLNamespace = INSTALLER ]
         <!--Code for each iteration of named Index key while looping through values-->
               <!--Code for each iteration of named Index key while looping through values-->
            <!--Code for each iteration of named Index key while looping through values-->

ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 3, 
   pInstaller As %Installer.Installer, 
   pLogger As %Installer.AbstractLogger) 
   As %Status [ CodeMode = objectgenerator, Internal ]
   #; Let XGL document generate code for this method. 
   Quit ##class(%Installer.Manifest).%Generate(%compiledclass,
      %code, "MyInstall")

Key Options

The outermost XML tag, <Manifest>, contains all the information for code generation. There can be as many <Namespace> tags as needed within the <Manifest> tag to define namespaces in the manifest.

A <Configuration> tag, which is located inside a <Namespace> tag, is required only if databases and/or mappings are being defined. There must be as many <Database> tags within the <Configuration> tag as are needed to define the namespace. In addition, following each <Database> tag, you can add <GlobalMapping>, <RoutineMapping>, and <ClassMapping> tags as required. The </Configuration> tag activates the defined mappings.

Within the context of a <Namespace> tag — after the databases and their mappings have been defined — globals can be loaded, and routines and classes can be loaded and compiled using <Import> tag. Class methods can be invoked using the <Invoke> tag. Invoked class methods can execute routines and access globals that have been imported.

Optionally, you can define variable pairs with the <Var> tag; each variable must specify a name and value. When the value for the <Var> is needed, the name is referenced by the ${NameAssigned} syntax.

For an example, see “Example” later in this chapter.

Adding Users and Passwords

There are several ways to add users (including their roles and passwords) to the installed instance, as follows:

  • Using the Management Portal after installation is complete, as described in the Caché Security Administration Guide.

  • Using the <User> tag in the manifest, as described in in <Manifest> Tags.

    The PasswordVar parameter of the <User> tag specifies the variable containing the password for the user; for example, by defining PasswordVar="Pwd", you are specifying that the value of the variable Pwd is the password for a user. There are a variety of ways to populate this variable, but it is ultimately up to you to do this. You might consider using a remote method invocation to another instance of Caché or a web service; the problem with these approaches is that the server that is installing Caché may need internet access. Other possibilities include importing the method you are using to the instance you are installing, or adding a client-side form to the install that prompts for users and passwords, which can be passed to your manifest.

  • Using the Security.UsersOpens in a new tab class on a staging instance of Caché or Ensemble, as follows:

    1. Export the user information by using the Security.Users.Export()Opens in a new tab method.

    2. Import the user information by adding the following at the beginning of your manifest class (in the %SYS namespace):

      <Invoke Class="Security.Users" Method="Import" CheckStatus="true">
      <Arg Value="PathToExportedUserInformation"/>

      where PathToExportedUserInformation is the location of the output file specified in the Security.Users.Export()Opens in a new tab method.

Adding Messages

You can define messages to be added to the log by incorporating <Log> tags in your class, in the following format:

<Log Level="<level>" Text="<text>"/>

The log level must be in the range of 0 to 3, where 0 is “none” and 3 is “verbose”; if the log level specified in the setup() method is equal to or greater than the Level property in the <Log> tag, the message is logged. The text is limited to 32,000 characters.

You set the log level via the second argument of the setup() method (for more information, see “Using the Manifest” later in this chapter). Since this cannot be passed to the manifest from the install, you must set it in the class as follows:

ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 3, 
   pInstaller As %Installer.Installer, 
   pLogger As %Installer.AbstractLogger) 
   As %Status [ CodeMode = objectgenerator, Internal ]

You can direct where messages are displayed via the fourth argument (%Installer.AbstractLogger) of the setup() method; for example, if you instantiate a %Installer.FileLogger object referencing an operating system file, all %Installer and log messages are directed to that file. (Without this argument, all messages are written to the primary device if setup() is called directly, and are ignored if it is executed by the installer.)

<Manifest> Tags

Following are descriptions of the tags (in alphabetical order) you can use within the XData block of your manifest class.

Some tags can contain expressions (strings) that are expanded when the manifest is executed. There are three types of expressions that can be expanded, as follows:

  • ${<var_name>}

    Expands to the value of the specified user variable (defined with the <Var> tag, as described in this section) or predefined variable (listed in the section Variables Available within <Manifest>). Examples of this type of expression can be found within this section.

  • ${#<param_name>}

    Expands to the value of the specified parameter for the class containing the XDATA.

  • #{<COS_expression>}

    Expands to the specified Caché Object Script expression (which must be properly quoted).

Parameter expressions are expanded at compile time, which means they can be nested within variable and COS expressions. Addtionally, variable expressions are expanded before COS expressions and thus can be nested within the latter.


Null arguments cannot be passed in tags in a manifest class. The <Arg/> tag passes an empty string, equivalent to <Arg=""/>, not null.


The value shown in square brackets ([]) is the default used for a property if it is not specified explicitly.


Parent tags: <Invoke>, <Error>

Passes an argument into a method called via <Invoke> or <Error>.

  • Value—Value of an argument.

<Error Status="$$$NamespaceDoesNotExist">
        <Arg Value="${NAMESPACE}"/>

Parent tag: <Configuration>

Creates a class mapping from a database to the namespace which contains this <Configuration> item.

  • Package—Package to be mapped.

  • From—Source database used for mapping.

<ClassMapping Package="MYAPP"

Parent tag: <Namespace>

Compiles the specified class name by calling %SYSTEM.OBJ.Compile(Class, Flags)Opens in a new tab.

  • Class—Name of class to be compiled.

  • Flags—Compilation flags [ck].

  • IgnoreErrors—Continue on error? [0]


Parent tag: <Namespace>

Child tags: <ClassMapping>, <Database>, <GlobalMapping>, <RoutineMapping>

Required as parent tag of configuration tags within <Namespace>. The closing tag (</Configuration>) activates the mappings for the databases in the namespace and updates the .cpf file.

No properties.

    <Database> . . . />
    <ClassMapping> . . . />

Parent tag: <Namespace>

Copies or moves the source class definition to the target.

  • Src—Source class.

  • Target—Target class.

  • Replace—Overwrite target class? [0]


Parent tag: <Manifest>

Copies the source directory to a target.

  • Src—Source directory.

  • Target—Target directory.

  • IgnoreErrors—Continue on error? [0]


Parent tag: <Manifest>

Copies the source file to a target.

  • Src—Source file.

  • Target—Target file.

  • IgnoreErrors—Continue on error? [0]


Parent tag: <Production>

Creates or overrides the access credentials

  • Name—Name of the access credentials.

  • Username—User name.

  • Password—User password.

  • Overwrite—Overwrite if the account already exists.


Parent tag: <Namespace>

Defines one or more CSP applications, as defined within the Security.ApplicationsOpens in a new tab class. (Also see Editing a CSP Application: The General Tab in the Caché Security Administration Guide for more details on each of these fields.)

  • AuthenticationMethods—Enabled authentication methods. (For supported authentication methods and the corresponding values to provide, see the AutheEnabled property in Security.Applications. For example, commonly used values are 4=Kerberos, 32=password, and 64=unauthenticated.

  • AutoCompile—Automatic compilation (in CSP settings)? [1]

  • CSPZENEnabled—CSP/ZEN enabled? [1]

  • ChangePasswordPage—Path to change password page.

  • CookiePath—Session cookie path.

  • CustomErrorPage—Path to custom error page.

  • DefaultSuperclass—Default superclass.

  • DefaultTimeout—Session timeout.

  • Description—Description.

  • Directory—Path to CSP files.

  • EventClass—Event class name.

  • Grant—List of roles assigned upon logging into the system.

  • GroupById—Group by ID?

  • InboundWebServicesEnabled—Inbound web services enabled? [1]

  • IsNamespaceDefault—Default application for the namespace? [0]

  • LockCSPName—Lock CSP name? [1]

  • LoginClass—Path to login page.

  • PackageName—Package name.

  • PermittedClasses—Permitted classes.

  • Recurse—Recurse (serve subdirectories)? [0]

  • Resource—Resource required to access web app.

  • ServeFiles—Service files? [1]

    • 0—No

    • 1—Always

    • 2—Always and cached

    • 3—Use CSP security

  • ServeFilesTimeout—Time, in seconds, of how long to cache static files.

  • TwoFactorEnabled—Two-step authentication enabled? [0]

  • Url—Name of the web application.

  • UseSessionCookie—Use cookies for the session?


Parent tag: <Configuration>

Defines a database within a namespace.

See Configuring Databases in the “Configuring Caché” chapter of the Caché System Administration Guide for information about the database settings controlled by the following properties.

  • BlockSize—Block size for database (4096, 8192, 16384, 32768, 65536).

  • ClusterMountMode—Mount database as a part of a cluster at startup?

  • Collation—Default collation for globals created in the database.

  • Create—Create a new database (yes/no/overwrite)? [yes]

  • Dir—Database directory.

  • Encrypted—Encrypt database?

  • EncryptionKeyID—ID of encryption key.

  • InitialSize—Initial size of the database, in MB.

  • ExpansionSize—Size in MB to expand the database by when required.

  • MaximumSize—Maximum size the database can expand to.

  • MountAtStartup—Mount when launching the installed instance?

  • MountRequired—Require mounting of database at every instance startup?

  • Name—Database name.

  • PublicPermissions—The Permission value to be assigned to the Resource if it must be created. It is ignored if the Resource already exists. Read-only or read-write.

  • Resource—Resource controlling access to the database.

  • StreamLocation—Directory in which streams associated with the database are stored.

<Database Name="${DBNAME}" 
<Database Name="MYAPP" 

Parent tag: <Manifest>

Sets the variable value if it is not already set.

  • Name—Variable name.

  • Value—Variable value.

  • Dir—Variable value, if a path to a folder or file

<Default Name="blksiz"
    Value="8192" />

Parent tags: <If>

Executed when the conditional defined by the preceding <If> statement is false.

No properties.

<If Condition='#
<CopyFile Src="C:\\InterSystems\key_files\cache300.key" Target="${MGRDIR}\cache.key" IgnoreErrors="0"/>

Parent tag: <Manifest>

Child tag: <arg>

Generates an error.

  • Status: Error code.

  • Source: Source of the error.

<Error Status="$$$NamespaceDoesNotExist" Source=>
    <Arg Value="${NAMESPACE}"/>

Parent tag: <Manifest>

Defines values for iterations of the specified index key.

  • Index—Variable name.

  • Values—List of variable values.

    <!--Code for each iteration of TargetNameSpace-->

Parent tag: <Configuration>

Maps a global to the current namespace.

  • Global: Global name.

  • From: Source namespace of the global.

  • Collation: Global collation [Caché Standard]

<GlobalMapping Global="MyAppData.*"
    From="MYAPP" Collation="30"/> 
<GlobalMapping Global="cspRule" 

Parent tags: <Manifest>, <Namespace>

Child tag: <Else>

Specifies a conditional action.

  • Condition: Conditional statement.

<If Condition='$L("${NAMESPACE}")=0'>
    <Error Status="$$$NamespaceDoesNotExist" Source=>
        <Arg Value="${NAMESPACE}"/>

Parent tags: <Manifest>, <Namespace>

Specifies a conditional action if a variable has been set.

  • Var: Variable name.

<IfDef Var="DBCreateName">
   <Database Name="${DBNAME}" 

Parent tags: <Manifest>, <Namespace>

Specifies a conditional action if a variable has not been set.

  • Var: Variable name.


Parent tag: <Namespace>

Imports files by calling %SYSTEM.OBJ.ImportDirOpens in a new tab(File,Flags,Recurse) or %SYSTEM.OBJ.Load(File,Flags)Opens in a new tab.

  • File—File or folder for import.

  • Flags—Compilation flags [ck].

  • IgnoreErrors—Continue on error? [0].

  • Recurse—Import recursively? [0].


Parent tag: <Namespace>

Child tag: <arg>

Calls a class method and returns the execution result as the value of a variable.

  • Class—Class name.

  • Method—Method name.

  • CheckStatus—Check the returned status?

  • Return—Name of variable to write result to.

<Invoke Class="SECURITY.SSLConfigs" Method="GetCertificate" CheckStatus="1" Return="CertContents"> 
    <Arg Value="Cache.cer"/>

Parent tag: <Namespace>

Loads a CSP page by calling %SYSTEM.CSP.LoadPageOpens in a new tab(PageURL,Flags) or %SYSTEM.CSP.LoadPageDir(DirURL,Flags)Opens in a new tab.

  • Name—URL of CSP page.

  • Dir—URL of directory containing CSP pages.

  • Flags—Compilation flags [ck].

  • IgnoreErrors—Continue on error? [0].


Parent tag: <Manifest>

Writes a message to the log specified by the setup() method if the log level specified by the setup() method is greater or equal to the level property provided.

  • Level—Log level, from 0 (none) to 3 (verbose).

  • Text—Log message (string up to 32,000 characters in length).

See Adding Messages for more information.


Parent tag: n/a (Root tag, containing all other tags.)

Child tags: <CopyDir>, <CopyFile>, <Default>, <Else>, <Error>, <ForEach>, <If>, <IfDef>, <IfNotDef>, <Log>, <Namespace>, <Resource>, <Role>, <SystemSetting>, <User>, <Var>

No properties.

    <Namespace ... >
            <Database .../>
            <Database .../>

Parent tag: <Manifest>

Child tags: <Compile>, <Configuration>, <CopyClass>, <CSPApplication>, <Else>, <If>, <IfDef>, <IfNotDef>, <Import>, <Invoke>, <LoadPage>, <Production>

Defines a namespace.

  • Name—Name of the namespace.

  • Create—Create a new namespace (yes/no/overwrite)? [yes]

  • Code—Database for code.

  • Data—Database for data.

  • Ensemble—Ensemble-enabled namespace? [0]

(Other properties are applicable to Ensemble web applications.)

<Namespace Name="${NAMESPACE}" 
               <Database Name="${NAMESPACE}" . . . />

Parent tag: <Namespace>

Child tags: <Credential>, <Setting>

Defines an Ensemble production.

  • Name—Production name.

  • AutoStart—Automatically launch production? [0]

<Production Name="${NAMESPACE}" 
     AutoStart="1" />

Parent tag: <Manifest>

Defines a resource.

  • Name—Resource name.

  • Description—Resource description.

  • Permission—Public permissions.


Parent tag: <Manifest>

Defines a role.

  • Name—Role name.

  • Description—Role description (cannot contain commas).

  • Resources—Privileges (resource-privilege pairs) held by the role.

  • RolesGranted—Roles granted by the named role.

    Description="Database user"
    RolesGranted= />

Parent tag: <Configuration>

Defines a routing mapping.

  • Routines: Routine name.

  • Type: Routine type (MAC, INT, INC, OBJ, ALL).

  • From: Source database of the routine.

<RoutineMapping Routines="MyRoutine"
    Type="ALL" From="${NAMESPACE}" /> 

Parent tag: <Production>

Configures an item in the Ensemble production by calling the Ens.Production.ApplySettings() method.

  • Item—Item name.

  • Target—Setting type (Item, Host, Adapter).

  • Setting—Setting name.

  • Value—Value to configure for setting.

<Production Name="Demo.ComplexMap.SemesterProduction">
    <Setting Item="Semester_Data_FileService"
    <Setting Item="Semester_Data_FileService"
    <Setting Item="Semester_Data_FileService"

Parent tag: <Manifest>

Sets the value for a property of any Config class that implements the Modify method.

  • of the Config class.

  • Value—Value to assign to property.


Parent tag: <Manifest>

Defines a user; if PasswordVar is included, the user’s password must be provided in the specified variable name.

  • Username—Username.

  • PasswordVar—Name of variable containing user password.

  • Roles—List of roles to which user is assigned.

  • Fullname—User’s full name.

  • Namespace—User’s startup namespace.

  • Routine—User’s startup routine.

  • ExpirationDate—Date after which user login will be disabled.

  • ChangePassword—Require user to change password on next login?

  • Enabled—Is user enabled?

  • Comment—Optional comment.

    Fullname="Data Entry Clerk"

Parent tag: <Manifest>

Defines and sets variables that can be used in the manifest/

  • Name—Variable name.

  • Value—Value to assign to variable.

<Var Name="Namespace" Value="MUSIC"/> 
<Var Name="GlobalDatabase" Value="${Namespace}G"/> 
<Var Name="RoutineDatabase" Value="${Namespace}R"/> 
<Var Name="AppDir" Value="C:\MyApp\${CFGNAME}"/> 
<Var Name="GlobalDatabaseDir" Value="${AppDir}\${GlobalDatabase}"/> 
<Var Name="RoutineDatabaseDir" Value="${AppDir}\${RoutineDatabase}"/> 
<Var Name="Resource" Value="%DB_${Namespace}"/> 
<Var Name="Role" Value="${Namespace}"/> 
<Var Name="CSPResource" Value="CSP_${Namespace}"/> 

For a comprehensive example of a user-defined installer class, see Sample.InstallerOpens in a new tab in the SAMPLES namespace.

For an up-to-date list of tags and attributes, see the %Installer class reference documentation.

Variables Available within <Manifest>

The following table lists the predefined variables that you can use in the manifest:

Variable Name Description
SourceDir (Available only when the installer is run) Directory from which the installation (setup_cache.exe or cinstall) is running.
ISCUpgrade (Available only when the installer is run) Indicates whether this is a new installation or an upgrade. This variable is either 0 (new installation) or 1 (upgrade).
CFGNAME Instance name.
CPUCOUNT Number of operating system CPUs.
CSPDIR CSP directory.
HOSTNAME Name of the host server.
HTTPPORT Web server port.
INSTALLDIR Directory into which Caché is installed.
MGRDIR Manager (mgr) directory.
PLATFORM Operating system.
PORT Caché superserver port.
PROCESSOR Processor chip.
VERSION Caché version number.

Using the Manifest

You can use the manifest as follows:

  • In the %SYS namespace, enter the following command in the Terminal:

    %SYS>Do ##class(MyPackage.MyInstaller).setup()

    You can pass an array by reference to the setup() method where the subscript is used as a variable in the <Manifest> and the node value is the variable <value>. For example:

    %SYS>Set vars("SourceDir")="c:\myinstaller"
    %SYS>Set vars("Updated")="Yes"
    %SYS>Do ##class(MyPackage.MyInstaller).setup(.vars,3)

    In this example, the second argument (3) is the log level.

  • Export the manifest class as DefaultInstallerClass.xml to the same directory where the Caché install (either .msi, setup_cache.exe, or cinstall) is run. It is imported into %SYS and compiled, and the setup() method is executed.

    Note that if you use the export technique, you cannot pass arguments directly to the setup() method. However, you can do the following:

    • On Microsoft Windows systems (see the chapter “Installing Caché on Microsoft Windows”), you can modify the .msi install package to pass variable name/value pairs to the setup() method. You can also use command-line arguments with the installer to pass the location of the exported manifest class, variable pairs, log file name, and log level, as shown in the following example:

      setup.exe INSTALLERMANIFEST="c:\MyStuff\MyInstaller.xml"

      Variable names passed using the INSTALLERMANIFESTPARAMS argument may contain only alphabetic and numeric characters (A-Za-z0-9) and underscores (_), and may not start with an underscore.

    • On UNIX®, Linux, macOS systems (see the chapter “Installing Caché on UNIX®, Linux, and macOS”), you can set environment variables to define the location of the exported manifest class, variable name/value pairs, log file name, and log level prior to running either cinstall or cinstall_silent, as shown in the following example:



The following class creates a namespace (MyNamespace) and three databases; two of the databases are defined as the default databases for globals (MyDataDB) and routines (MyRoutinesDB), while the third database (MyMappingDB) is a globals database that overrides the default database mapping for t* globals in the MyNamespace namespace.


For a more comprehensive example, see the Sample.InstallerOpens in a new tab class in the SAMPLES namespace.

Include %occInclude

/// Simple example of installation instructions (Manifest)
Class MyInstallerPackage.SimpleManifest

XData SimpleManifest [ XMLNamespace = INSTALLER ]
    <Namespace Name="MyNamespace" Create="yes" 
        Code="MyRoutinesDB" Data="MyDataDB">
        <Database Name="MyRoutinesDB" Create="yes" 
        <Database Name="MyDataDB" Create="yes" 
        <Database Name="MyMappingDB" Create="yes" 
        <GlobalMapping Global="t*" From="MyMappingDB"/>

/// This is a method generator whose code is generated by XGL.
ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 3, 
   pInstaller As %Installer.Installer, 
   pLogger As %Installer.AbstractLogger) 
   As %Status [ CodeMode = objectgenerator, Internal ]
    #; Let our XGL document generate code for this method. 
    Quit ##class(%Installer.Manifest).%Generate(%compiledclass, 
    %code, "SimpleManifest")


After the class is compiled, you can invoke it in the Terminal as shown below (assuming you created the class in the USER namespace):

%SYS>znspace "USER"
USER>do ##class(MyInstallerPackage.SimpleManifest).setup()
FeedbackOpens in a new tab