Integration - XML Schemas - Export (Frontline)

Document data
Document Date: 16 August 2006revision 1
Keyfax version : 3.2.0.0 (or greater)
Software required: Internet Explorer 6.0+, XML editor
User skill requirements: MSXML editing.
Author: Technical Serviceskeyfax@touch-base.com

XML Export Schema

This section details the export information generated by a Keyfax Frontline request (session), and is intended as a definitive guide to how to parse Keyfax data in a Host Management System or other calling application (Host). This schemas should be used whilst testing Integration scenarios, and as a general reference.

If integration with a Host is a Microsoft Windows based application, Omfax have developed a COM based ActiveX control (Keyfax.ocx). This can be used to simplify the integration with Keyfax, by reading a series of properties when a Keyfax session is complete. For full details of using the Keyfax.ocx see the ActiveX OCX section.

Any XML element which does not have a dedicated Keyfax OCXproperty, can be accessed by the GetNodeByXPath OCX property. Some of these are described below:

XML Element Description
<? xml version="1.0" ?>
<!-- Data generated 16/08/2006 10:46:58 by KFDXML.dll [version: 3.2.0.3] -->
 
<KeyfaxData> XML Root (Document Element)
  <Enquiry name="Enquiry1"> Section (can be multiple sections if supported by Host) Main Enquiry details, name attribute is incremental "Enquiry1", Enquiry2" etc.
    <IsDeleted>False</IsDeleted>
    <IsDirty>False</IsDirty>
    <IsNew>True</IsNew>

Section status information:
  IsDeleted = If True: Linked Database record DELETE required.
  IsDirty = If True: Linked Database record UPDATE required.
  IsNew = If True: Linked Database record INSERT required.
Note: These elements are replicated in every document sub section and are intended for generating automatic database queries using the Export XML to build statements via custom XSLT.

    <EnquiryDialog>82</EnquiryDialog> The ID of the Keyfax Script which was used to generated XML output.
    <EnquiryText>
      <![CDATA[ Anti-social behaviour: Abandoned car ]]>
    </EnquiryText>
A textual description of the enquiry, built from the script category name, enquiry name and any selected option or input text.
    <LogDate>16/08/2006 10:46:58</LogDate> The date and time which the call (script) was processed (completed).
    <EnquiryCatRef>4</EnquiryCatRef> The ID of the Keyfax Script Category which was used to generated XML output.
    <EnquiryCategory/> Not used in FL scripts
    <ClientID>PF</ClientID> Any Client ID passed from the Host to Keyfax at start-up (usually if they manage calls for multiple clients).
Note: This value is used by CCLite installations.

Keyfax OCX property to fetch value (no dedicated property):
strValue = Keyfax.GetNodeByXPath("Enquiry[1]/ClientID")

    <TenantID>45431</TenantID> Any Tenant ID (or Property Ref) passed to Keyfax at start-up.
    <TenantText>
      <![CDATA[ Mr P Graddon, Omfax Systems Ltd, 21 The Causeway, Bicester,
Oxon, OX26 6AN
]]>
    </TenantText>
The name and address of the caller or property passed from the Host to Keyfax at start-up.
Note: This will be used in email or mailmerge tasks. This is usually a CSV formatted full postal address.
    <UserCode>UserID01</UserCode> The UserID passed from the Host to Keyfax at start-up.
    <ScriptPath>
      <Question>Q1 = Where is it? : A1 = take details</Question>
      <Question>Q2 = [O]Operator message: is it on landlord's land?: A2 = Yes</Question>
      <Question>Q3 = Do you know who owns it or who put it there?: A3 = take details</Question>
      <Question>Q4 = What type of car is it?: A4 = take details, make, colour, registration</Question>
      <Question>Q5 = Is the HO available to take the call?: A5 = No</Question>
    </ScriptPath>

Each question and selected option or entered text (not [EDT] or [XAD] text inputs) is recorded and formatted in one of three different styles of ScriptPath.
This output can be used to record the scripted conversation to a database record for future audit purposes.

The ScriptPath type is set in the XML configuration file: //configuration/Scripting/FL/Exchange/ScriptPath[@type]
The ScriptPath on the left is type=1. See the following alternative ScriptPaths:

ScriptPath type=0:

<ScriptPath>
  <![CDATA[ [Q=Where is it?;A=take details],
[Q=[O]Operator message: is it on landlord's land?;A=Yes],
[Q=Do you know who owns it or who put it there?;A=take details],
[Q=What type of car is it?;A=take details, make, colour, registration],
[Q=Is the HO available to take the call?;A=No]
]]>
</ScriptPath>

ScriptPath type=2:

<ScriptPath>
  <Question no ="1">
    <Request>Where is it?</Request>
    <Response>take details</Response>
  </Question>
  <Question no ="2">
    <Request>[O]Operator message: is it on landlord's land?</Request>
    <Response>Yes</Response>
  </Question>
  <Question no ="3">
    <Request>Do you know who owns it or who put it there?</Request>
    <Response>take details</Response>
  </Question>
  <Question no ="4">
    <Request>What type of car is it</Request>
    <Response>take details, make, colour, registration</Response>
  </Question>
  <Question no ="5">
    <Request>Is the HO available to take the call?</Request>
    <Response>No</Response>
  </Question>
</ScriptPath>

    <ActionCount>1</ActionCount>
    <SubActionCount>4</SubActionCount>
    <AdviceCount>1</AdviceCount>
    <CustomCount>0</CustomCount>

Details the number of sections for Actions, SubActions, Advice and Custom items.
These counters can be used to create a loop to access each of the sections by it's name attribute.

For Custonm sections see the descriptions in the Repairs Diagnostic Export XML Schema

    <Action name="Action1" type="KF_FL_TASK">

Section (can be multiple Actions): Used to hold Keyfax Action code and details.
An Action can be a Host action or an internal Keyfax action, such as an Email or Mailmerge Task.
If internal Tasks are Merged and Processed by the Keyfax Client, a TaskTemplate section will also be included within the Action section.
Note: An Action may have one or more associated SubActions, which are used to capture information from a variety of sources during the script interview.

      <ActionCode>ASB007</ActionCode> An Action code is returned by scripts to a Host as an instruction to do something, i.e. send an email, create a mailmerge letter etc.
Keyfax uses this code to include Task Template XML fragments into the TaskTemplate section.
      <ActionCodeEx>ASB007</ActionCodeEx> ActionCodes can be manipulated by Keyfax Frontline Rules before Tasks are merged (at loading of results screen).
The ActionCodeEx records the original code generated by a script before any Rules are run.
      <ActionCodeDesc>
        <![CDATA[ Abandoned car, email HO ]]>
      </ActionCodeDesc>
The Keyfax ActionCode description.
      <HasSubActions>True</HasSubActions> This will be "True" if the Action has associated SubActions.
      <Priority>1</Priority> The Priority of the Action (normally 1, 2 or 3).
      <IsDeleted>False</IsDeleted>
      <IsDirty>False</IsDirty>
      <IsNew>True</IsNew>
Section status information (see Enquiry section).
      <TaskTemplate ID="ASB007">
        <Name>Abandoned car, email HO</Name>
        <Notifications/>
        <Reassignments/>
        <Task Type="Letter" Item="1">
          <SentDate/>
          <UserID/>
          <Description>
            <![CDATA[ Untitled Document ]]>
          </Description>
          <Letter Printed="False" Attachments="False">
            <Letterhead>
              <![CDATA[ Preprinted Letterhead ]]>
            </Letterhead>
            <Body Merge="False" Merged="False" >
              <![CDATA[ <p/> ]]>
            </Body>
            <Merge/>
            <Attachments/>
          </Letter>
        </Task>
      </TaskTemplate>

If Keyfax Tasks are enabled and configured to Merge, the TaskTemplate which matches the Keyfax generated ActionCode will be included in the Action section.
Keyfax TaskTemplates can contain Email and Letter templates, and any one TaskTemplate can contain multiple Email or Letter tasks in any quantity or combination.

The example Tasktemplate shown here is a skeleton of an Letter Task, without any letter body or merge fields defined.

Note: As TaskTemplates are used internally by the Keyfax Client application and Keyfax Contact Centre, the exact schema for some of the elements have not been detailed. Detailed specification of the Task Templates will be added to this documentation in due course.

    </Action> End of Action section
    <SubAction name="SubAction1" owner="ASB007" type="TEXT_CAPTURE"> Section (can be multiple SubAction sections): Used to hold data which is associated to Actions.
The owner attribute indicates to which Action the SubAction relates.
Note: The type attribute defines information reuired for MIS-AMS SQLActiveH integration using a Gateway object and the MISexchange.xml interface method. This is not required for other 3rd party host integrations.
      <ParentActionCode>ASB007</ParentActionCode> The same as the SubAction owner attribute, indicates to which Action the SubAction relates.
      <SubActionCode>[EDT]001</SubActionCode> A SubAction code is used by scripts to capture snippets of information from a variety of sources, which will be used in tasks generated by Action codes to merge into template bookmarks based on the associated SubActionKeys.
These codes can be one of the following types:
  [EDT] = Edit box - Returns multiline text input by user during script.
  [XAD] = Address - Returns CSV formatted addresses input by user during script.
  [SCR] = Screen captured data - Selected option text or single line text entered by user during script.
  [AID] = Add in Database data - Data fetched from Dataview (or other 3rd party associated database) via custom SELECT queries ran during script.
      <SubActionCodeEx>[EDT]001</SubActionCodeEx> SubActionCodes can be manipulated by Keyfax Frontline Rules before Tasks are merged (at loading of results screen).
The SubActionCodeEx records the original code generated by a script before any Rules are run.
      <SubActionKey>Details01</SubActionKey> The SubActionKey is the name of the bookmark within an ActionCode template, which will be replaced with the SubActionValue during template merging (submit) if merging is enabled.
      <SubActionValue>
        <![CDATA[ Outside Community Centre ]]>
      </SubActionValue>
The SubActionValue is the data to replace the bookmark (SubActionKey) during template merging (submit) if merging is enabled.
      <IsDeleted>False</IsDeleted>
      <IsDirty>False</IsDirty>
      <IsNew>True</IsNew>
Section status information (see Enquiry section).
    </SubAction> End of SubAction section
    <SubAction name="SubAction2" owner="ASB007" type="XADD_CAPTURE">
      <ParentActionCode>ASB007</ParentActionCode>
      <SubActionCode>[XAD]003</SubActionCode>
      <SubActionCodeEx>[XAD]003</SubActionCodeEx>
      <SubActionKey>Addressee01</SubActionKey>
      <SubActionValue>
        <![CDATA[ Mr R Smith, 1 Paddock Way, Anytown ]]>
      </SubActionValue>
      <IsDeleted>False</IsDeleted>
      <IsDirty>False</IsDirty>
      <IsNew>True</IsNew>
    </SubAction>
Second SubAction section, with an address captured from an [XAD] Address dialogue.
    <SubAction name="SubAction3" owner="ASB007" type="AIDB_EXECUTE">
      <ParentActionCode>ASB007</ParentActionCode>
      <SubActionCode>[AID]101</SubActionCode>
      <SubActionCodeEx>[AID]101</SubActionCodeEx>
      <SubActionKey>Email01</SubActionKey>
      <SubActionValue>test5@omfax.co.uk</SubActionValue>
      <IsDeleted>False</IsDeleted>
      <IsDirty>False</IsDirty>
      <IsNew>True</IsNew>
    </SubAction>
Third SubAction section, with an email address returned from a [AID] query (a SELECT SQL statement againt an associated Dataview database), based on the supplied TenantID
    <SubAction name="SubAction4" owner="ASB007" type="TEXT_CAPTURE">
      <ParentActionCode>ASB007</ParentActionCode>
      <SubActionCode>[EDT]002</SubActionCode>
      <SubActionCodeEx>[EDT]002</SubActionCodeEx>
      <SubActionKey>Details02</SubActionKey>
      <SubActionValue>
        <![CDATA[ 1992, Red Ford Escort ]]>
      </SubActionValue>
      <IsDeleted>False</IsDeleted>
      <IsDirty>False</IsDirty>
      <IsNew>True</IsNew>
    </SubAction>
Fourth SubAction section, with text returned fron a multi line text input box.
    <Advice name="Advice1"> Section (can be multiple Advice sections): Used to hold details of messages displayed during scripts. These are passed back for storage by host for future audit purposes.
      <AdviceCode>[ADV]00001</AdviceCode> The internal Keyfax FL code which was used to generate the Advice Section.
      <AdviceCodeEx>[ADV]00001</AdviceCodeEx> AdviceCodes can be manipulated by Keyfax Repair Diagnostic Rules (at loading of results screen).
The AdviceCodeEx records the original code generated by a script before any Rules are run.
      <AdviceCodeDesc>
        <![CDATA[ Refer to HO ]]>
      </AdviceCodeDesc>
The description of the AdviceCode.
      <AdvicePlainText>
        <![CDATA[ MSG: Refer to Housing Officer Advise the caller
that you will refer their call to the Housing Officer. If the
Officer is not available to take the call, you will pass on
the details of the enquiry to the Housing Officer who will
contact the caller shortly.
]]>
      </AdvicePlainText>

The body of the advice code. This can be returned in plain text or HTML format:

The AdvicePlainText type is set in the XML configuration file: //configuration/Scripting/FL/Exchange/AdvicePlainText[@html] and //configuration/Scripting/FL/Exchange/AdvicePlainText[@prefix]
The AdvicePlainText on the left is html=0, prefix="MSG: ". See the following alternative AdvicePlainText:

AdvicePlainText html=1, prefix="":

<AdvicePlainText>
  <![CDATA[ <div style='background-color:#FFFFFF;color:#000000;width:573px;'>
<DIV ALIGN=CENTER><BR><FONT STYLE="font-family:'Arial';font-size:12pt;">
<B>Refer to Housing Officer</B>
<P>Advise the caller that you will refer their call to the Housing Officer. If the Officer is not available to take the call, you will pass on the details of the enquiry to the Housing Officer who will contact the caller shortly.</P></FONT></DIV></div> 
]]>
</AdvicePlainText>

      <IsDeleted>False</IsDeleted>
      <IsDirty>False</IsDirty>
      <IsNew>True</IsNew>
Section status information (see Enquiry section).
    </Advice> End of Advice section
    <ContTelNo>01869 242 967</ContTelNo>
    <HomeTelNo>01234 555 666 </HomeTelNo>
    <WorkTelNo>01869 242 967</WorkTelNo>
    <MobileTelNo>07770 123456 </MobileTelNo>
    <CallerEmail>support@omfax.co.uk</CallerEmail>
    <Notes>If not available at main Contact number, please try on Mobile phone.</Notes>
Elements containing the current caller passed to Keyfax in start-up request. These can be used in merge operations.

Keyfax OCX property to fetch value(s) (no dedicated property):
strValue = Keyfax.GetNodeByXPath("Enquiry[1]/ContTelNo")

  </Enquiry> End of Enquiry section
  <GUID>E87D6835-1DC5-3F5E-D805BF84ED35DC4D</GUID> The GUID used in sendin a start-up enquiry request.
  <Status>1</Status> The Keyfax Export status 1=Complete, 2=Cancelled, Other=error
</KeyfaxData> End of XML Root (Document Element)