Integration - XML Schemas - Export (Repairs Diagnostic)

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

XML Export Schema

This section details the export information generated by a Keyfax Repairs Diagnostic 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 25/08/2006 09:20:32 by KFDXML.dll [version: 3.2.0.3] -->
  
<KeyfaxData> XML Root (Document Element)
  <Fault name="Fault1"> Section (can be multiple sections if supported by Host) Main Fault details, name attribute is incremental "Fault1", Fault2" 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.

    <Fault_Dialog>151</Fault_Dialog> The ID of the Keyfax Script which was used to generated XML output.
    <Fault_Category>1</Fault_Category> The ID of the Keyfax Script category which was used to generated XML output.
Note: This value should be used to store with the repair request by host HMS and passed to Keyfax RD requests with repair history. This will allow fade in history alerts to be displayed when the same category of fault is selected within Keyfax in future RD sessions.
    <FaultText>
      <![CDATA[ Basins: Basin - loose; bathroom; pedestal; Fair wear and tear ]]>
    </FaultText>		 A textual description of the fault, built from the script category name, fault name and any selected option or input text.
    <LogDate>25/08/2006 09:20:32</LogDate> The date and time which the call (script) was processed (completed).
    <Communal_Type>4</Communal_Type> A communal code (if set by script) indicating the unit to which the repair relates: i.e. P = property, B = block, C = communal area.
Note: This value is configurable via scripts to match HMS requirements.
    <Reason_Code>ET</Reason_Code> A code representing a reason for which a fault occured (if set by script).
Note: This value is configurable via scripts to match HMS requirements. A user select fault reason can have an affect on the recharge status of the repair.
    <Reason_Text>
      <![CDATA[ Elderly Tenant ]]>
    </Reason_Text>		 The textual description for the above reason code.
    <Recharge>0</Recharge> If the repair is to be rechargeable to the Tenant: 1 = Yes, 0 = No.
    <Recharge_Code>RREP</Recharge_Code> A recharge code representing the recharge type (if set by script).
Note: This value is configurable via scripts to match HMS requirements.
    <Recharge_Cost>28.74</Recharge_Cost> The value of any rechargeable repair, including VAT and any additional charges.
Note: This value is calculated based on each SOR item value, times their quantity plus VAT if rechargeable.
    <Repair_No>R930063</Repair_No> If a repair number is passed by a host HMS, this is returned in this element.
Note: This value is NOT generated by Keyfax RD.
    <Repair_Status>2</Repair_Status> Fixed: Always will be 2 = ordered.
    <Schedule_ID>omfax\23</Schedule_ID> Keyfax RD generated unique ID, made up of current UserCode with a suffixed sequential number.
Note: this ID is also used in jf_orders, jf_sub_orders and jf_audit records.
    <Site_Visit>
      <![CDATA[ Works every day except Wednesdays ]]>
    </Site_Visit>		 Any user entered text related to contractor site restrictions or access.
    <Additional_Info>
      <![CDATA[ The tiles are broken over the basin ]]>
    </Additional_Info>		 Any addition information entered by the user at the end of the diagnosic script. This information is indended to be forwarded to the contractor or inspector visiting to inspect or repair the fault on site.
    <Special_Instructions>
      <![CDATA[ Please ring before visiting ]]>
    </Special_Instructions>		 Special instructions for site contractors.
    <Tenancy_Type>ASS</Tenancy_Type> The Tenancy code passed at startup, which is used by Keyfax RD to determine the set of scripts made available to the user.
    <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("Fault[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 the basin? : A1 = bathroom</Question>
      <Question>Q2 = What type is it?: A2 = pedestal</Question>
      <Question>Q3 = Is it safe?: A3 = Yes</Question>
      <Question>Q4 = How did it happen?: A4 = Tenant action</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/RD/Exchange/ScriptPath[@type]
The ScriptPath on the left is type=1. See the following alternative ScriptPaths:

ScriptPath type=0:

<ScriptPath>
  <![CDATA[ [Q=Where is the basin?;A=bathroom],
[Q=What type is it?;A=pedestal],
[Q=Is it safe?;A=Yes],
[Q=How did it happen?;A=Tenant action] ]]>
</ScriptPath>

ScriptPath type=2:

<ScriptPath>
  <Question no ="1">
    <Request>Where is the basin?</Request>
    <Response>bathroom</Response>
  </Question>
  <Question no ="2">
    <Request>What type is it?</Request>
    <Response>Pedestal</Response>
  </Question>
  <Question no ="3">
    <Request>Is it safe?</Request>
    <Response>Yes</Response>
  </Question>
  <Question no ="4">
    <Request>How did it happen? </Request>
    <Response>Tenant action</Response>
  </Question>
</ScriptPath>
    <Contractor_Code/> Only contains data if Script generated [KEY] code is used specifying specific contractor data is to be placed in Contractor_Code element.

Keyfax OCX property to fetch value (no dedicated property):
strValue = Keyfax.GetNodeByXPath("Fault[1]/Contractor_Code")
    <Expenditure_Code/> Only contains data if Script generated [KEY] code is used specifying expenditure data is to be placed in Expenditure_Code element.

Keyfax OCX property to fetch value (no dedicated property):
strValue = Keyfax.GetNodeByXPath("Fault[1]/Expenditure_Code")
    <Nominal_Code/> Only contains data if Script generated [KEY] code is used specifying nominal data is to be placed in Nominal_Code element.

Keyfax OCX property to fetch value (no dedicated property):
strValue = Keyfax.GetNodeByXPath("Fault[1]/Nominal_Code")
    <Job_Code/> Only contains data if Script generated [KEY] code is used specifying job data is to be placed in Job_Code element.

Keyfax OCX property to fetch value (no dedicated property):
strValue = Keyfax.GetNodeByXPath("Fault[1]/Job_Code")
    <Location/> Only contains data if Script generated [KEY] code is used specifying location data is to be placed in Location element.

Keyfax OCX property to fetch value (no dedicated property):
strValue = Keyfax.GetNodeByXPath("Fault[1]/Location")
    <RepairCount>1</RepairCount>
    <AdviceCount>1</AdviceCount>
    <CustomCount>1</CustomCount>
    <ActionCount>0</ActionCount>
    <SubActionCount>0</SubActionCount>
    <UpdateCount>0</UpdateCount>

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

For Actions and SubActions see the descriptions in the Frontline Export XML Schema
    <Repair name="Repair1">

Section (can be multiple Repair sections): Used to hold Keyfax Repair code (SOR code) and details.
      <CompleteBy>30/08/2006 09:20:00</CompleteBy> The date which the repair is required to be completed.
Note: This is calculated based on the priority the SOR repair code is assigned via the diagnostic script.
      <Priority>U</Priority> The Priority of the Repair (configured to match HMS priorities within Keyfax RD).
      <RepairCode>630713</RepairCode> A RepairCode or SOR (Schedule of Rates) code returned by the diagnostic script.
      <RepairCodeEx>630713</RepairCodeEx> RepairCodes can be manipulated by Keyfax Repair Diagnostic Rules (at loading of results screen).
The RepairCodeEx records the original code generated by a script before any Rules are run.
      <RepairCodeDesc>
        <![CDATA[ BASIN:REFIX WASH HAND BASIN ]]>
      </RepairCodeDesc>		 The RepairCode (SOR) description.
      <UnitOfMeasure>NO</UnitOfMeasure> The unit of measure for the RepairCode, i.e. No, M2, M, length etc.
      <UnitOfMeasureQuantity>1</UnitOfMeasureQuantity> The quantity of RepairCode (SOR) items required.
      <Contractor>PLU</Contractor> Any specific contractor or trade code associated to the RepairCode (SOR).
      <IsDeleted>False</IsDeleted>
      <IsDirty>False</IsDirty>
      <IsNew>True</IsNew>		 Section status information (see Fault section).
    </Repair> End of Repair Section
    <Custom name="Custom1">

Section (can be multiple Custom sections): Used to hod any additional data items which do not have specific export elements.

      <ParentSection>Export</ParentSection> Defines wheter the data is related to the fault (Export) or a specific Repair code (RepairCode / SOR code).
      <CustomCode>[KEY]001</CustomCode> The internal Keyfax RD code which was used to generate the Custom Section.
      <CustomCodeEx>[KEY]001</CustomCodeEx> CustomCodes can be manipulated by Keyfax Repair Diagnostic Rules (at loading of results screen).
The CustomCodeEx records the original code generated by a script before any Rules are run.
      <CustomKey>myKey</CustomKey> The name (or key) of the data to be returned. This should be unique to each export generated by a RD script.
      <CustomKeyValue>
        <![CDATA[ information to be returned ]]>
      </CustomKeyValue>		 The custom data being returned from the script.

Keyfax OCX property to fetch custom value (no dedicated property):
strCustom = Keyfax.GetNodeByXPath("Fault/Custom[CustomKey='myKey']/CustomKeyValue")
to get the CustomKeyValue from the first Custom section with a CustomKey named 'myKey' OR: to get a specific CustomKeyValue for a Custom section:
strCustom = Keyfax.GetNodeByXPath("Fault[@name='Fault1']/Custom[@name='Custom1' and CustomKey='myKey']/CustomKeyValue")
      <IsDeleted>False</IsDeleted>
      <IsDirty>False</IsDirty>
      <IsNew>True</IsNew>

Section status information (see Fault section).
    </Custom> End of Custom section
    <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>[ATR]003</AdviceCode> The internal Keyfax RD code which was used to generate the Advice Section.
      <AdviceCodeEx>[ATR]003</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[ Tenant responsible]]>
      </AdviceCodeDesc>		 The description of the AdviceCode.
      <AdvicePlainText>
        <![CDATA[ MSG: Tenant responsible for any damage caused by
members of the household or visitors Advise the tenant that they
may be charged for the cost of the work Do you wish to continue
logging thisr epair? You will be required to give a justification
to proceed ]]>
      </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/RD/Exchange/AdvicePlainText[@html] and //configuration/Scripting/RD/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>Tenant responsible for any damage caused by members of the household or visitors
<P> Advise the tenant that they may be charged for the cost of the work<P></B>
<P>Do you wish to continue logging this repair?<BR>
<I>You will be required to give a justification to proceed</I></FONT></DIV></div> ]]>
</AdvicePlainText>
      <IsDeleted>False</IsDeleted>
      <IsDirty>False</IsDirty>
      <IsNew>True</IsNew>		 Section status information (see Fault 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("Fault[1]/ContTelNo")
  </Fault> End of Fault section
  <GUID>E87D6835-1DC5-3F5E-D805BF84ED35DC4D</GUID> The GUID used in sendin a start-up repairs request.
  <Status>1</Status> The Keyfax Export status 1=Complete, 2=Cancelled, Other=error
</KeyfaxData> End of XML Root (Document Element)