Skip to main content
Previous sectionNext section

Creating and Using an Installation Manifest

This topic describes how to use the %Installer utility to create an installation manifest that describes a specific InterSystems IRIS® data platform configuration and use it to generate code to configure an InterSystems IRIS instance.

Overview of an Installation Manifest

The %Installer utility lets you define an installation manifest that describes and configures a specific InterSystems IRIS 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 the 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. This appendix provides installation manifest examples that you can copy and paste to get started.

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 an Installation Manifest

This section contains the information needed to create an installation manifest, broken into the following subjects:

Manifest Class Definition

To create a class that defines an installation manifest, create a class that meets the following criteria (or start from the blank template in the Installation Manifest Examples section below):

  • The class must include the %occInclude include file.

  • The class must contain an XData block specifying the details of the installation. The name of the XData block will be used later as an argument. The root element in the XData block must be <Manifest>. For details, see “List of <Manifest> Tags”.

    In Studio, if you include [XMLNamespace = INSTALLER] after the name of the XData block, Studio provides assistance as you type the XData block.

  • The class must define a setup() method that refers to the XData block by name, as seen in the Installation Manifest Examples section.

Common Manifest Options

This section describes some of the common tasks an installation manifest is used to perform. The following options are described:

Define Namespaces

To define namespaces, add any number of <Namespace> tags within the <Manifest> tag.

If you want to define databases or mappings for a namespace, put a <Configuration> tag inside the <Namespace> tag. For each database the namespace contains, add a <Database> tag within the <Configuration> tag. To define mappings, add <GlobalMapping>, <RoutineMapping>, and <ClassMapping> tags beneath the appropriate <Database> tag. The </Configuration> tag activates the defined mappings.

Also within a <Namespace> tag, you can load globals, routines, and classes using the <Import> tag. You can also invoke class methods, which in turn can execute routines and access globals that have been imported, with the <Invoke> tag.

You can define variables with the <Var> tag. To reference a variable within the manifest, use the ${var_name} syntax. For more information, see Variables Within <Manifest> Tags below.

Add Users and Passwords

There are multiple ways to add users (including their roles and passwords) to the installed instance:

  • Include a <User> tag in an installation manifest, as described in the List of <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 InterSystems IRIS or a web service; the problem with these approaches is that the server that is installing InterSystems IRIS 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.

  • Edit users in the Management Portal after installation is complete, as described in the “Users” chapter in Security Administration Guide.

  • Using the Security.Users class on a staging instance of InterSystems IRIS, as follows:

    1. Export the user information by using the Security.Users.Export() 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"/>
      </Invoke>
      Copy code to clipboard

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

Write to the Manifest Log

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

<Log Level="<level>" Text="<text>"/>
Copy code to clipboard

The log level must be in the range of -1 to 3, where -1 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 appendix). 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 ]
Copy code to clipboard

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.)

Perform Post-Upgrade Tasks

When upgrading an instance of InterSystems IRIS, you can use an installation manifest to automatically perform any necessary post-upgrade tasks, such as recompiling code. You do this by using the <Invoke> tag to call the class methods described in the How to Compile Namespaces section of the “Upgrading InterSystems IRIS” chapter of this book.

See the Installation Manifest Examples section of this appendix for an example of a manifest that can be used during an upgrade.

Variables Within <Manifest> Tags

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>} — Variables

Expands to the value of the variable. In addition to the predefined variables described in this section, you can specify additional variables with the <Var> tag.

${#<param_name>} — Class Parameters

Expands to the value of the specified parameter for the manifest class.

#{<ObjectScript_expression>} — ObjectScript Expressions

Expands to the specified InterSystems IRIS Object Script expression (which must be properly quoted).

Note:

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

The following table lists the predefined variables that are available to use in the manifest:

Variable Name Description
SourceDir (Available only when the installer is run) Directory from which the installation (setup_irisdb.exe or irisinstall) 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).
CFGDIR See INSTALLDIR.
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 InterSystems IRIS is installed.
MGRDIR Manager (mgr) directory.
PLATFORM Operating system.
PORT InterSystems IRIS superserver port.
PROCESSOR Processor chip.
VERSION InterSystems IRIS version number.

List of <Manifest> Tags

All the information for code generation is contained in the outermost XML tag, <Manifest>. The tags within <Manifest> describe a specific configuration of InterSystems IRIS. This section contains a list of these tags and their function. Not all tags and attributes are listed here; for a complete list, see the %Installer class reference documentation. The default value for an attribute, if any, is listed in square brackets next to each attribute.

Important:

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

<Arg>

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}"/>
/>
Copy code to clipboard
<ClassMapping>

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"
     From="MYDB"/>
Copy code to clipboard
<Compile>

Parent tag: <Namespace>

Compiles the specified class name by calling %SYSTEM.OBJ.Compile(Class, Flags).

  • Class—Name of class to be compiled.

  • Flags—Compilation flags [ck].

  • IgnoreErrors—Continue on error? [0]

<Compile  
    Class="MyPackage.MyClass"
    Flags="ck"
    IgnoreErrors=0/>
Copy code to clipboard
<Configuration>

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.

<Configuration>
    <Database> . . . />
    <ClassMapping> . . . />
/>
Copy code to clipboard
<CopyClass>

Parent tag: <Namespace>

Copies or moves the source class definition to the target.

  • Src—Source class.

  • Target—Target class.

  • Replace—Overwrite target class? [0]

<CopyClass  
    Src="MyPackage.MyClass"
    Target="NewPackage.NewClass"
    Replace="0"/>
Copy code to clipboard
<CopyDir>

Parent tag: <Manifest>

Copies the source directory to a target.

  • Src—Source directory.

  • Target—Target directory.

  • IgnoreErrors—Continue on error? [0]

<CopyDir  
    Src="${MGRDIR}"
    Target="F:\MyTargetDir"
    IgnoreErrors="0"/>
Copy code to clipboard
<CopyFile>

Parent tag: <Manifest>

Copies the source file to a target.

  • Src—Source file.

  • Target—Target file.

  • IgnoreErrors—Continue on error? [0]

<CopyFile  
    Src="${MGRDIR}\messages.log"
    Target="F:\${INSTANCE}_log"
    IgnoreErrors="0"/>
Copy code to clipboard
<Credential>

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.

<Credential  
    Name="Admin"
    Username="administrator"
    Password="123jUgT540!f3B$#"
    Overwrite="0"/>
Copy code to clipboard
<CSPApplication>

Parent tag: <Namespace>

Defines one or more web applications, as defined within the Security.Applications class.

  • 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]

  • CSPEnabled—CSP 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?

  • 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?

<CSPApplication 
    Url="/csp/foo/bar"
    Description=""
    Directory="C\InterSystems\IRIS\CSP\Democode1"
    Resource=""
    Grant="%DB_%DEFAULT"
    Recurse="1"
    LoginClass=""
    CookiePath="/csp/demo1"
    AuthenticationMethods="64"/>
Copy code to clipboard
<Database>

Parent tag: <Configuration>

Defines a database within a namespace.

See Configuring Databases in the “Configuring InterSystems IRIS” chapter of the 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}" 
    Dir="${MGRDIR}/${DBNAME}"  
    Create="yes"
    Resource="${DBRESOURCE}"
    Blocksize="8192"
    ClusterMountMode="0"
    Collation="5"
    Encrypted="0"
    EncryptionKeyID=
    ExpansionSize="0"
    InitialSize="1"
    MaximumSize="0"
    MountAtStartup="0"
    MountRequired="0"
    StreamLocation=
    PublicPermissions=""/>
<Database Name="MYAPP" 
    Dir="${MYAPPDIR}/db"  
    Create="no"
    Resource="${MYAPPRESOURCE}"
    Blocksize="8192"
    ClusterMountMode="0"
    Collation="5"
    Encrypted="0"
    EncryptionKeyID=
    ExpansionSize="0"
    InitialSize="1"
    MaximumSize="0"
    MountAtStartup="0"
    MountRequired="0"
    StreamLocation=
    PublicPermissions=""/>
Copy code to clipboard
<Default>

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" />
Copy code to clipboard
<Else>

Parent tags: <If>

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

No properties.

<If Condition='#
{##class(%File).Exists(INSTALL_"mgr\iris.key")}
'>
<Else/>
<CopyFile Src="C:\\InterSystems\key_files\iris300.key" Target="${MGRDIR}\iris.key" IgnoreErrors="0"/>
</If>
Copy code to clipboard
<Error>

Parent tag: <Manifest>

Child tag: <arg>

Generates an error.

  • Status: Error code.

  • Source: Source of the error.

<Error Status="$$$NamespaceDoesNotExist" Source=>
    <Arg Value="${NAMESPACE}"/>
</Error>
Copy code to clipboard
<ForEach>

Parent tag: <Manifest>

Defines values for iterations of the specified index key.

  • Index—Variable name.

  • Values—List of variable values.

<ForEach 
    Index="TargetNameSpace"
    Values="%SYS,User">
    <!--Code for each iteration of TargetNameSpace-->
</ForEach>
Copy code to clipboard
<GlobalMapping>

Parent tag: <Configuration>

Maps a global to the current namespace.

  • Global: Global name.

  • From: Source namespace of the global.

  • Collation: Global collation [IRIS Standard]

<GlobalMapping Global="MyAppData.*"
    From="MYAPP" Collation="30"/> 
<GlobalMapping Global="cspRule" 
    From="MYAPP"/>
Copy code to clipboard
<If>

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}"/>
    </Error>
</If>
Copy code to clipboard
<IfDef>

Parent tags: <Manifest>, <Namespace>

Specifies a conditional action if a variable has been set.

  • Var: Variable name.

<IfDef Var="DBCreateName">
   <Database Name="${DBNAME}" 
       Dir="${MGRDIR}/${DBNAME}"  
       Create="yes"
       ...
</IfDef>
Copy code to clipboard
<IfNotDef>

Parent tags: <Manifest>, <Namespace>

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

  • Var: Variable name.

<Import>

Parent tag: <Namespace>

Imports files by calling %SYSTEM.OBJ.ImportDir(File,Flags,Recurse) or %SYSTEM.OBJ.Load(File,Flags).

  • File—File or folder for import.

  • Flags—Compilation flags [ck].

  • IgnoreErrors—Continue on error? [0].

  • Recurse—Import recursively? [0].

<Invoke>

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="iris.cer"/>
</Invoke>
Copy code to clipboard
<LoadPage>

Parent tag: <Namespace>

Loads a CSP page by calling %SYSTEM.CSP.LoadPage(PageURL,Flags) or %SYSTEM.CSP.LoadPageDir(DirURL,Flags).

  • Name—URL of CSP page.

  • Dir—URL of directory containing CSP pages.

  • Flags—Compilation flags [ck].

  • IgnoreErrors—Continue on error? [0].

<Log>

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 -1 (none) to 3 (verbose).

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

See Write to the Manifest Log for more information.

<Manifest>

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.

<Manifest>
    <Namespace ... >
        <Configuration>
            <Database .../>
            <Database .../>
        </Configuration>
    </Namespace>
</Manifest>
Copy code to clipboard
<Namespace>

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—interoperability-enabled namespace? [0]

(Other properties are applicable to Interoperability web applications.)

<Namespace Name="${NAMESPACE}" 
     Create="yes" 
     Code="${NAMESPACE}"
     Data="${NAMESPACE}"> 
          <Configuration> 
               <Database Name="${NAMESPACE}" . . . />
          </Configuration>
</Namespace>
Copy code to clipboard
<Production>

Parent tag: <Namespace>

Child tags: <Credential>, <Setting>

Defines a production.

  • Name—Production name.

  • AutoStart—Automatically launch production? [0]

<Production Name="${NAMESPACE}" 
     AutoStart="1" />
Copy code to clipboard
<Resource>

Parent tag: <Manifest>

Defines a resource.

  • Name—Resource name.

  • Description—Resource description.

  • Permission—Public permissions.

<Resource
    Name="%accounting_user" 
    Description="Accounting"
    Permission="RW"/>
Copy code to clipboard
<Role>

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.

<Role 
    Name="%DB_USER"
    Description="Database user"
    Resources="MyResource:RW,MyResource1:RWU"
    RolesGranted= />
Copy code to clipboard
<RoutineMapping>

Parent tag: <Configuration>

Defines a routine mapping.

  • Name: Routine name.

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

  • From: Source database of the routine.

<RoutineMapping Name="MyRoutine"
    Type="ALL" From="${NAMESPACE}" /> 
Copy code to clipboard
<Setting>

Parent tag: <Production>

Configures an item in the 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"
        Target="Item"
        Setting="PoolSize"
        Value="1"/>
    <Setting Item="Semester_Data_FileService"
        Target="Host"
        Setting="ComplexMap"
        Value="Demo.ComplexMap.Semester.SemesterData"/>
    <Setting Item="Semester_Data_FileService"
        Target="Adapter"
        Setting="FilePath"
        Value="C:\Practice\in\"/>
</Production>
Copy code to clipboard
<SystemSetting>

Parent tag: <Manifest>

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

<User>

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 (see <Var> below).

  • 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 is disabled.

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

  • Enabled—Is user enabled?

  • Comment—Optional comment.

<User 
    Username="Clerk1"
    PasswordVar="clerk1pw"
    Roles="Dataentry"
    Fullname="Data Entry Clerk"
    Namespace=
    Routine=
    ExpirationDate=
    ChangePassword=
    Enabled=
    Comment=""/>
Copy code to clipboard
<Var>

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}"/> 
Copy code to clipboard

Using the Manifest

You can run a manifest manually, or as part of an installation.

Manually

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

%SYS>do ##class(MyPackage.MyInstaller).setup()
Copy code to clipboard

You can pass an array of variables to the setup() method by reference. Each subscript is used as a variable name, and the node as the value. For example:

%SYS>set vars("SourceDir")="c:\myinstaller"
%SYS>set vars("Updated")="Yes"
%SYS>do ##class(MyPackage.MyInstaller).setup(.vars,3)
Copy code to clipboard

The second argument in this example (3) is the log level.

During Installation

Export the manifest class as DefaultInstallerClass.xml to the same directory where the InterSystems IRIS install (either .msi, setup_irisdb.exe, or irisinstall) is run. It is imported into %SYS and compiled, and the setup() method is executed.

Note:

Make sure that the user running the installation has write permission to the manifest log file directory. The installation does not proceed if the log file cannot be written.

Note that if you use the export technique, you cannot pass arguments directly to the setup() method. The following sections describe how to pass arguments on Windows or on UNIX®, Linux, and macOS:

On 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, variables, log file name, and log level, as shown in the following example:

setup.exe INSTALLERMANIFEST="c:\MyStuff\MyInstaller.xml"
INSTALLERMANIFESTPARAMS="SourceDir=c:\mysourcedir,Updated=Yes"
INSTALLERMANIFESTLOGFILE="installer_log" INSTALLERMANIFESTLOGLEVEL="2"
Copy code to clipboard
Note:

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.

For more information, see the Command Line Reference section in the “Installing InterSystems IRIS on Microsoft Windows” chapter of this book.

On UNIX®, Linux, and macOS

On UNIX®, Linux, and macOS systems, you can set environment variables to define the location of the exported manifest class, variables, log file name, and log level prior to running either irisinstall or irisinstall_silent, as shown in the following example:

ISC_INSTALLER_MANIFEST="/MyStuff/MyInstaller.xml"
ISC_INSTALLER_PARAMETERS="SourceDir=/mysourcedir,Updated=Yes"
ISC_INSTALLER_LOGFILE="installer_log"
ISC_INSTALLER_LOGLEVEL="2"
./irisinstall
Copy code to clipboard

For more information, see the Unattended Installation Parameters section in the “Installing InterSystems IRIS on UNIX®, Linux, and macOS” chapter of this book.

Installation Manifest Examples

This section contains examples of installation manifests that do the following:

Blank Template

The following is a basic manifest template:

Include %occInclude

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

XData SimpleManifest [ XMLNamespace = INSTALLER ]
{
<Manifest>
   <Log Level="3" Text="Start manifest" />
   <Namespace Name="">
      <Import File="" />
      <Invoke Class="" Method="" CheckStatus="" Return=""> 
         <Arg Value=""/>
      </Invoke> 
   </Namespace>
   <CopyFile Src="" Target="" IgnoreErrors=""/>
   <CopyDir Src="" Target="" IgnoreErrors=""/>   
   <Log Level="3" Text="End manifest" />
</Manifest>
}

/// 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")
}

}
Copy code to clipboard

Create a Namespace

The manifest in this example creates a namespace (MyNamespace) and three databases. The MyDataDB and MyRoutinesDB databases are the default databases for globals and routines, respectively, while the MyMappingDB database is another globals database. The <GlobalMapping> tag creates a mapping to MyMappingDB for t* globals in the MyNamespace namespace, which overrides the default mapping.

Include %occInclude

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

XData SimpleManifest [ XMLNamespace = INSTALLER ]
{
<Manifest>
    <Namespace Name="MyNamespace" Create="yes" 
        Code="MyRoutinesDB" Data="MyDataDB">
      <Configuration>
        <Database Name="MyRoutinesDB" Create="yes" 
            Dir="C:\MyInstallerDir\MyRoutinesDB"/>
        <Database Name="MyDataDB" Create="yes" 
            Dir="C:\MyInstallerDir\MyDataDB"/>
        <Database Name="MyMappingDB" Create="yes" 
            Dir="C:\MyInstallerDir\MyMappingDB"/>
        <GlobalMapping Global="t*" From="MyMappingDB"/>
      </Configuration>
    </Namespace>
</Manifest>
}

/// 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")
}

}
Copy code to clipboard

Compile After an Upgrade

The manifest in this example recompiles code in a namespace called APPTEST, and is intended to be run after an upgrade. It performs the following tasks:

  1. Writes a message to the manifest log indicating the start of the manifest installation process.

  2. Sets the current namespace to APPTEST, which contains the code that needs to be recompiled after the upgrade.

  3. Invokes the method %SYSTEM.OBJ.CompileAll() to compile the classes in the namespace.

  4. Invokes the method %Routine.CompileAll() to compile the custom routines in the namespace.

  5. Writes a message to the manifest log indicating the end of the manifest installation process.

Include %occInclude

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

XData SimpleManifest [ XMLNamespace = INSTALLER ]
{
<Manifest>
    <Log Level="3" Text="The Installer Manifest is running."/>
    <Namespace Name="APPTEST">
        <Invoke Class="%SYSTEM.OBJ" Method="CompileAll" CheckStatus="1"> 
            <Arg Value="u"/>
        </Invoke>
        <Invoke Class="%Routine" Method="CompileAll" CheckStatus="1"/>
        </Namespace>
    <Log Level="3" Text="The Installer Manifest has completed."/>
</Manifest>
}

/// 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")
}

}
Copy code to clipboard