› KCM 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 Kofax 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 Kofax Communications Manager Core Developer's Guide.
  • Result: Required, string. Path, name, and extension of the result document. The format of the result document is the same as the format of the template script used to create the template. If the template script is a Microsoft Word document (.docx), the result document is a Microsoft Word (.docx) document. The format of the result document can be overridden by the OutputMode parameter.
  • 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 parameter Keys. 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 parameter Keys 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 parameter Keys, 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 parameter Keys 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, KCM does not perform a post-include after the template has been run. Post-includes in KCM 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 Kofax 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 KCM 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 KCM Interactive templates.

If batch mode is enabled, KCM 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. Overrides the output format for the result document.

This parameter determines the type of the result document produced. Currently supported formats are:

  • native produces a document in the same format as the template.
  • 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. If the template is a Document Template, it is treated as a Document Pack Template. The produced Document Pack will have a single slot containing the result of that template.

The default is native.

A template can query the OutputMode parameter by calling the function runmodel_setting("OutputMode").

SuppressInteractiveCheck: Optional, boolean. If set to True, KCM 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), KCM 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 KTA 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 KCM Core. These errors are identified with the USR1000 and USR1001 labels.

Availability

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

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

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