Introduction

This document outlines the installation and use of the workflow trigger service and corresponding executable.

The workflow trigger functional is designed to enable an XML file supplied by a third party in the appropriate format to be used to trigger a workflow inside KnowledgeWorker based upon the criteria defined in a configuration file.

Overview

The diagram below shows the functional components involved in the workflow trigger.

The Workflow Trigger Web Service receives the XML from the third part application, and this includes the category, attribute data and an indication of the data source, such as cataloguerequest. 

The Workflow Trigger Web Service identifies the source of the XML from its content and looks into the configuration file to determine the directory into which to copy the XML content.  The Workflow Trigger Web Service is only responsible for placing the content for processing and not the actual processing of the XML.  Restricting the Workflow Trigger Web Service in this way reduces the risk of an external application overloading the KnowledgeWorker service and denying service to KnowledgeWorker users.

The Workflow Trigger Execution engine is started using a batch file to trigger an instance of the engine for each permitted source.  The Workflow Trigger Execution engine is a task that every 5 seconds looks to identify if there are XML files to process from the defined source.  Where an XML file is present this is processed based on the execution rules in the configuration file.  Upon completion the Workflow Trigger Execution checks for further files and then processes each in turn.

It is the Workflow Trigger Execution that will trigger the workflow in KnowledgeWorker and that is responsible for identifying/ reporting errors.

Installation & Use

Installation of the Workflow Trigger functionality involves a number of steps:

• The definition of a workflow category
• The creation and addition to KnowledgeWorker of a workflow based on the category
• The editing of the WebServiceConstants.asp in WEBSERVICES\WF_XML_TRIGGER to identify the location of the Workflow Trigger configuration file KWXML.XML that must co-exists with the WF_XML_Trigger.exe found in the directory Addins\WF_XML_TRIGGER
• The editing of the KWXML.XML in order to set-up the necessary information for source, user, KnowledgeWorker instance, folder locations and trigger clause
• The editing of the sample batch file WF_XML_TRIGGER.bat to trigger executable of only the relevant batch files

The definition of the workflow category will include the attribute names that will be tags in the XML data from the third-party application, as in the sample XML supplied here:

<KW_WF_TRIGGER>

     <CATEGORIES>

         <CATEGORY NAME="CategoryLookup_Cat">

              <CatLookUp_Attr>1</CatLookUp_Attr>

              <CatEntry_Attr>This is the text</CatEntry_Attr>

         </CATEGORY>

     </CATEGORIES>

             <SOURCE>ONE</SOURCE>

</KW_WF_TRIGGER>

The source in this case is declared as “ONE” and the Category is identified by name rather than identifier number to permit portability between KnowledgeWorker instances with the same category definition.  Note: This can be achieved using export and import category to ensure that the same category and attribute details are present in more than one instance of KnowledgeWorker.

Only attributes that have been defined as editable in the initial step of the workflow will be updated.  Any attributes that are omitted from the XML will be assumed to be null.

The workflow to be triggered by the workflow trigger execution engine must added to KnowledgeWorker and launch in order to ensure that the contents of the file has been inserted into the database.

The KWXML.XML file needs to include the relevant details for the web service and the workflow execution engine. An example of the configuration file is:

<XML version='1.0' encoding='iso-8859-1'>

     <KW_WF_TRIGGER_INI>

         <SOURCES>

         <SOURCE NAME = "ONE">

              <USERNAME>system</USERNAME>

              <PASSWORD>system</PASSWORD>

              <SERVER>reddot040315</SERVER>

              <HOLDINGAREA>C:\temp\KW_SERVER\ErrorFiles</HOLDINGAREA>

              <XMLCONTENTPATH>C:\temp\KW_SERVER\XMLFiles</XMLCONTENTPATH>

              <ERROR_LOGPATH>C:\temp\KW_SERVER\ErrorFiles\ErrorLog.log</ERROR_LOGPATH>

         <SUCCESS_LOGPATH>C:\temp\KW_SERVER\ErrorFiles\SuccessLog.log</SUCCESS_LOGPATH>

              <WFID>5056</WFID>

              <WFCATEGORY>CategoryLookup_Cat</WFCATEGORY>

              <TRIGGER_CLAUSE>

                        <ATTR_NAME>CatLookUp_Attr</ATTR_NAME>

                        <ATTR_VALUE>1</ATTR_VALUE>

              </TRIGGER_CLAUSE>

              <SET_EMAIL_FLAG>ON</SET_EMAIL_FLAG>

              <FROMEMAIL>Admin@adimn.com</FROMEMAIL>

              <TOEMAIL>Datum@datum.com</TOEMAIL>

         </SOURCE>

         </SOURCES>

     </KW_WF_TRIGGER_INI>

</XML>

Each source is defined and for the source the workflow node identifier is used to identify the workflow that is to be used.  The trigger clause is used to define the workflow that is to be trigger based upon the value of an attribute.  When that attribute does not match the trigger clause no workflow will be triggered.

The Source name must match in case and spelling the name in the XML provided by the third-party application.

Testing the Workflow Trigger

To test the workflow trigger, a harness has been provided in the form of the TestXML.asp. 

Edit TestXML.asp so that the page knows the location of the workflow trigger web service.  Update the line:

Const WEB_SERVICE_URL = "http://localhost/WebServices/ProcessWFTrigger.asp"

The ProcessWFTrigger.asp is the page that will receive the XML from the third-party application and process it into the relevant content path / directory for the source application.

Create a sample of XML for the external application based on the sample file SampleKWXMLFormat.xml (see below).

<KW_WF_TRIGGER>

     <CATEGORIES>

         <CATEGORY NAME="CategoryLookup_Cat">

              <CatLookUp_Attr>1</CatLookUp_Attr>

         </CATEGORY>

     </CATEGORIES>

             <SOURCE>ONE</SOURCE>

</KW_WF_TRIGGER>

The sample must include the source name and the relevant category and attributes to be complete in the initial step of the workflow.  Note workflow attributes will not be updated unless they have been defined as editable.

Launch the page TestXML.asp in a browser and paste the sample XML into the input dialogue and observe the output dialogue.  Examine the workflow actions and instances from Admin to see that the workflow has been triggered successfully.