› Communications Manager Core Scripting Language Developer's Guide › Commands › ITPRun

ITPRun

You can use the ITPRun command to run a template. This command replaces the ITP command, which is deprecated.

Usage 

ITPRun 
      Model (<text>)
      Result (<text>)

The first two arguments are the name of the template and the location of the result. They are both mandatory. The remaining arguments are all optional.

A template can expect Keys and Extras in a certain order. They must be provided as a list of values, separated by semicolons. 

      Keys(<text>) 
      Extras(<text>)
      DisablePostIncludes (True or False)
      Environment (<text>)

The MetaData parameter specifies the name of an XML file to store template run metadata after the template completed. 

      MetaData (<text>)

The following parameters specify a user name and password for retrieving data in the template run. 

      DBUserID (<text>)
      DBPassword (<text>)

The following section is AS/400 only and optional. See also AS/400 Connection parameters later in this section. 

      PreCMD (<text>)
      OnSuccessCMD (<text>)
      OnFailureCMD (<text>)
      PostCMD (<text>)

You can specify the data XML file with which the Data Backbone is filled. 

      DBB_XMLInput (<text>)
      DBB_XMLOutput (<text>)
 					BatchMode (True or False)

With OutputMode the formatting of the result document can be specified. 

						OutputMode (<text>)

Pre-flight checks can be disabled with the following setting. 

						SuppressInteractiveCheck (True or False)

Integration used with Tungsten TotalAgility and other applications. 

						ClosedLoopIdentifier (<text>);

Parameters

  • Model: Required, string. The rep:/ URI or Letter Book URL to be executed. For more details on the rep:/ URI, see the chapter Document composition in the Tungsten Communications Manager Core Developer's Guide.
  • Result: Required, string. Specifies the path, name, and extension of the result document or pack.

    If ITPRun is called with an active document pack, it produces all document pack content in the open document pack and overwrites any previous content. Depending on the value of the result parameter, it will subsequently do either of the following:

    • If the result parameter contains the path to the open pack, ITPRun returns without saving the content of the open pack to a file.

    • Otherwise, ITPRun saves the newly filled document pack to the indicated file location.

    In both cases, the document pack remains open to allow for further processing.

  • Keys: Optional, string. Keys are used to specify parameters for the data retrieval of a template. A template can use data retrieval statements to retrieve data from external sources. Data retrieval statements are parameterized with keys used to identify which data should be retrieved, such as the number of the intended recipient. Keys are passed as a string of values separated by semicolons. Each value specifies a single parameter required by a data retrieval statement in the template.

    Data retrieval parameters explicitly specified with the PAR keyword in the Template scripting language are not taken from the Keys parameter. Values from the parameter Keys are only used when a data retrieval statement in the template does not explicitly specify a parameter itself.

    The sequence of keys passed in the Keys parameter must be in the order in which they are expected in the template. You can specify an empty parameter by following a semicolon with another semicolon. This ensures that the empty parameter counts in the sequence.

    Example 

    ITPRun
      ...
      Keys ("value1;;value3;value4");

    The meaning of a Keys entry can differ depending on the data connection being used. For database connections, a Keys entry typically provides a database primary key value, such as an invoice number used to retrieve records with a database query. For the XML File connection, a Keys entry specifies the full path to an XML file.

    For the XML File connection, you can only specify XML files through the Keys parameter, not as parameters to the data retrieval statements in the template. For each data retrieval statement that uses a main entry from an XML File DID Module, the next entry in the Keys parameter determines the XML file to be used.

    The script ITPRun does not support the use of parameter files.

  • Extras: Optional, string. Extra parameters are used to pass additional information to variables with the EXTRA keyword in the template. These parameters are usually calculated by the script or derived from the request parameters. Extra parameters are specified as a string of values separated by semicolons with the maximum length of 1024 characters. The sequence must be in the same order as the variables in the template. This parameter is not meant to pass big amounts of data to a template, for this purpose, use the Data Backbone.

    You can specify an empty parameter by following a semicolon with another semicolon. This ensures that the empty parameter counts in the sequence.

    Example 

    ITPRun
      ...
      Extras ("value1;value2;;");

  • DisablePostIncludes: Optional, boolean. If set to True, Communications Manager does not perform a post-include after the template has been run. Post-includes in Communications Manager Core are performed lazily by default (ITPLAZYPOSTINC=Y). If set to False (or left empty), ITPRun uses the ITPPOSTINC setting in the itp.cfg to determine if post-includes have to be processed.

    The default is False.

  • Environment: Optional, string. Templates are always run in an environment that can be indicated with this parameter. If no environment parameter is given, the default environment is used. If an environment is passed that does not exist, an error is given.

    This parameter is ignored when running Document Pack Templates.

  • MetaData: Optional, string. The name of an XML file in which metadata on the template run is written. An existing metadata file may also be supplied to be extended by the template. If this parameter is not given, no such file is generated.

    This parameter is ignored when running Document Pack Templates and with OutputMode set to "pack". For more information, see the section XML metadata from template runs in the Tungsten Communications Manager Core Developer's Guide.

  • DBUserID: Optional, string. User account name for retrieving data from a database. This parameter allows a database user account to be specified per template run.

  • DBPassword: Optional, string. Password belonging to the account name specified in DBUserID.

  • DBB_XMLInput: Optional, string. The name of a data XML file used to fill the Data Backbone of the template. The data XML must match the XSD of the Data Backbone. In batch mode, this XSD is extended with wrappers to enable more than one Data Backbone data sets to be specified.

  • DBB_XMLOutput: Optional, string. The name of a file where the XML with data of the Data Backbone of the template should be stored after the template run has completed.

    The file name passed to DBB_XMLInput and DBB_XMLOutput should be a valid path/file specification on the computer running Communications Manager Core. It can be preceded by "session:", in which case the file is located in the session directory. The DBB parameters allow you to create templates that do not need a DID, as data is loaded directly into the Data Backbone from the XML.

  • BatchMode: Optional, boolean.

    Enable batch mode for Communications Manager Interactive templates.

    If batch mode is enabled, Communications Manager Core expects one or more Data Backbone data sets in the input XML file. The model automatically fills the Data Backbone with one set at a time and runs the template for that set. The result document is a concatenated set of all output documents.

    The default is False. Enabling this option requires that an XML file is passed using the DBB_XMLInput parameter.

  • OutputMode: Optional, string.

    This parameter is only relevant for Document templates. When specified, it overrides the output format of the result. It can have the following values:

    • native produces a document in the same format as the template. This is the default value.
    • utf8 produces text in UTF-8 encoding.
    • utf16 produces text in UTF-16 encoding.
    • aiadocxml produces an XML file representing the structure of the result document. This structure is based on the Content Wizard(s) used in the document.

    • pack produces a document pack with a single slot that contains the result of the document template.

  • SuppressInteractiveCheck: Optional, boolean.

    If set to True, Communications Manager performs a pre-flight check to verify that a (potentially) interactive Master Template can be run in a non-interactive mode. The developer is responsible for detecting this and suppressing any interactivity. If the Master Template tries to become interactive, an error is reported. If set to False (or left empty), Communications Manager prohibits Master Templates that contain interactive statements from running in a non-interactive mode.

  • ClosedLoopIdentifier: Optional, string.

    Use the Closed Loop Identifier to pass an identifier to the template. The identifier will be included in the Metadata and used in the resulting Document Pack to identify each result document. Templates can override the identifier by changing the _Document.ClosedLoopIdentifier field.

    This option is used in Tungsten TotalAgility integration. Use is also supported for other applications.

AS/400 exit points

The following commands allow the script to execute AS/400 shell commands to modify the context of the AS/400 HDM job.

PreCMD: Optional, string. The command PreCMD is executed after the library list is set.

OnSuccessCMD: Optional, string. The command OnSuccessCMD is executed if the template is completed successfully.

OnFailureCMD: Optional, string. The command OnFailureCMD is executed if the template failed.

PostCMD: Optional, string. The PostCMD command is executed at the end of the run (after OnSuccessCMD or OnFailureCMD).

Error handling

A template can use the keywords ERROR and WARNING to report errors to Communications Manager Core. These errors are identified with the USR1000 and USR1001 labels.

Availability

As of Communications Manager Core 4.2.0, references to templates on the file system are no longer supported.

The BatchMode and OutputMode parameters are introduced in Communications Manager Core version 4.2.3.

The CCMOnDemandMode, CCMInterfaceType, and Alternative parameters are introduced in Communications Manager Core version 4.4.