Start

See Running an interactive ITP model for a description of the functionality of the method Start.

• Signature

  ResultCode Start (string model,
                    string resultDocument,
                    string keys,
                    string extras,
                    string preCMD,
                    string postCMD,
                    string onSuccessCMD,
                    string onFailureCMD);
  

• Parameters

  1. Master Template: Specifies the KCM Master Template to be run.

  2. resultDocument: Specifies the path of the result document. See the documentation on the property ResultDocument.

  3. keys: Tthe parameter keys is used to pass information to KCM Master Template. For example, you can use the parameter keys to identify the customer for whom you want to create a policy or an invoice. The KCM Master Template can then use the identifying information to retrieve the full customer name and address.

     Keys are passed as a string of values separated by semicolons (;). The sequence must be the same as the order in which they are expected in the Master Template.

     The property DataFile is used to specify an XML data file to be passed to the KCM Master Template. And the special value "*DataURI" is passed to indicate that this data file should be used.

     It is possible to specify an empty key by following a semicolon with another one (;;). This will ensure that the empty parameter will count in the sequence.

  4. Extras: Extra parameters are used to pass information to KCM Master Template. For example, you can use the extra parameters to pass extra information on the user who runs the KCM Master Template, at run time. Extras are typically used to pass information to the model that is not available from the database and that cannot be derived from the database data.

     The parameter Extras is specified as a string of values separated by semicolons (;). The sequence must be the same as the order in which they are expected in the model.

     It is possible to specify an empty parameter by following a semicolon with another one (;;). This ensures that the empty parameter counts in the sequence.

  5. PreCMD: AS/400 only. The Pre command is executed after the library list is set.

     We recommend that the API user is aware that this Pre command is executed when the Master Template needs to get data from the database. If the Master Template is set up in such a way that interact statements follow on this data access, the Pre command is executed the first time the data is accessed and every time the call Continue is called.

  6. OnSuccessCMD: AS/400 only. The OnSuccess command is executed if the Master Template is completed successfully.
  7. OnFailureCMD: AS/400 only. The OnFailure command is executed if the Master Template fails.

  8. PostCMD: AS/400 only. The Post command is executed at the end of the run (after OnSuccess or OnFailure).

     We recommend that the API user is aware that this Post command is executed for the call to Start and also for each subsequent call to Continue. This means that the Post command is executed for the call Start and all its Continue calls.

• Return values

  The following result values are defined for the methods Start and Continue:

  1. Model.ResultCode.Done

     The Master Template run is completed. The final document has been stored to the location set in the property ResultDocument. If the property History is enabled, a file with all form answers in XML format has been saved to the location set in the property InfoFile.

  2. Model.ResultCode.Interact

     A file containing an XML form (XForms 1.0) is saved to the location set in the property InfoFile. In addition, if the property PreviewDocument has been set, a preview document has been written to the location set in the property PreviewDocument.

     The keyselection.xml and interact.xml examples of XML data files, which are returned by the method Start in case of key selection or a form, can be found in the folder: APIs\Online\Example XML Files of the KCM Core installation.

     The application that uses the KCM ComposerUI .NET API responds to this result by gathering answers to the Form questions in the XML form file, and by subsequently calling Continue, passing the answers to the Form questions in the parameter response. The format of the parameter response must also be XForms 1.0 XML.

     An example (response.xml) of an XML data file that should be passed to the method Continue in case of an interaction, can be found in the folder APIs\Online\Example XML Files of the KCM Core installation.

  3. Model.ResultCode.Error

     An error has occurred. An XML document describing the error is stored at the location set in the property InfoFile. After an error has occurred, the session information on the KCM Core is not destroyed. A user is still able to go back to a previous form, and resubmit other form data.

     An example (error.xml) of an XML data file returned by the method Start in case of an error can be found in the folder APIs\OnLine\Example XML Files of the KCM Core installation.