Add interfaces

Contract types definition file

The XML file that defines one or more interfaces has a structure like described below.

<?xml version="1.0" encoding="UTF-8"?> 
<interfaces formatversion="1"> 
	<interface uselegacysessionid="false" session="none" > 
		<name>MyContractType</name> 
		<version>1</version> 
		<type>core</type> 
		<corescript>MyOwnScript</corescript> 
		<parameters> 
				<input> 
					<param optional="false"> 
							<name>textIn</name> 
							<type>message</type> 
					</param> 
				</input> 
				<output> 
						<param optional="false"> 
								<name>textOut</name> 
								<type>message</type> 
						</param> 
				</output> 
			</parameters> 
		</interface> 
</interfaces>

For this XML file, consider the following:

• Always use “1” for the formatversion attribute.
• The file can contain one or more <interface> elements.
• Always use “false” for the uselegacysessionid attribute.
• The session attribute of the <interface> can have the following values:
  • create: This interface creates a session in the Contract Manager.
  • require: This interface requires a session in the Contract Manager to be present.
  • none: This interface does not interact with or does not require any session in the Contract Manager.

  The session attribute value indicates whether the implementing KCM Core script needs to create a session in the Contract Manager (session="create") or requires a session to be present (session="require") in the Contract Manager. You can use this functionality to link various interfaces together. For example, if you have one interface that creates a document but does not return the document, the script creates a session, and the document is stored in that session. The other interface that required a session distributes the document stored in this session to a location.

• If you have your type set to composeruihtml5 or composeruij2ee, the create session will be implicit. Your session should be set to none as this attribute is ignored. For interfaces of the type core, the session attribute can be set to none, create, or require.
• To link various interfaces, you add one interface that creates a session in the Contract Manager. The call to this first interface creates a session. Then create other interfaces that require a session. When calling these interfaces, enter the session retrieved from the first call.
• If you set the session to "create," your interface automatically returns a session ID. You can use this session ID with other requests that require a session ID.
• A KCM Core script added to an interface that creates a session in the Contract Manager should always create a session and pass it on when the script is executed.

The following are examples of what the KCM Core script should contain. Both examples perform the same functionality.

CreateSession;Const Text dummy = exchange_data("sessionID", _sessionid, 0);

or

ITPOLSSessionStart

To use an interface with the session set to "require," perform a request that first creates a session and then receives a session ID from it. Interfaces with the session set to "require" are automatically extended with a parameter to enter the session ID. This allows you to have access to a particular session in KCM Core. You can access data stored in the KCM Core session using sessiondir.

• The <name> and <version> elements of the <interface> identify the interface. The name must contain only alphanumeric characters and periods. The version must be an integer number.
• The <type> of an <interface> must either be core, designer, administration, or composeruiforhtml5:
  • core: indicates if the task should be handled by KCM Core only.
  • designer: interface to interact with KCM Designer.
  • administration: indicates that this interface is to perform administrative actions.
  • composeruiforhtml5: executing the interface involves ComposerUI for HTML5. It is necessary to run KCM Core scripts that involve interactivity, to compose documents that contain forms or Content Wizards with selections to be made.
• The <corescript> element defines the name of the KCM Core service script that implements the interface. This script must support the input and output parameters as described by the interface. For more information on adding KCM Core service scripts, see the Kofax Communications Manager Core Scripting Language Developer's Guide and Kofax Communications Manager Core Developer’s Guide.

Parameters

Parameter names must contain only alphanumeric characters and periods. The parameter names are case-insensitive.

The parameter types are case-sensitive and must be all lowercase.

• Input parameters must be provided on the SOAP call for the interface. Your KCM Core script must contain the same parameters as the interface (apart from document type parameters). In the example XML, the parameter textIn must appear in your KCM Core script as Parameter Text textIn. With the exception of Document parameters, the order of the input parameters in the interface definition must correspond to the order of the KCM Core script parameters in the implementation.
• In the core script interface implementation, Document parameters are not script parameters but implemented as calls to the ReceiveFile function. Therefore, these parameters are skipped when passing the interface parameters on to KCM Core.
• Output parameters are those returned by the KCM Core script, either by means of exchange_data or SendFile. The Contract Manager passes the output along in the SOAP response.
• Optional parameters may be omitted from the SOAP request. If an input parameter is optional, the KCM Core script must contain a default value for the corresponding parameter. Output parameters cannot be optional.

Parameters can be of various types. The types differ according to restrictions on the values that can be entered or returned. The following table provides a description of the parameter types: