search

Mappings

You can map specific Keyfax export elements to certain properties of the Civic CX repair request, works order, task line or inspection using the CxMappings.xml mappings file.

An example Civica CX mapping file can be seen below...

<?xml version="1.0" encoding="utf-8"?>
<!-- The Civica CX Mappings File
    IMPORTANT: The default attribute is used if the xPath attribute is omitted or the xPath expression does not resolve to any node.     
    If the xPath attribute resolves to a valid node this nodes inner text will be used over the default value unless the nodes inner text is also empty or zero.
    If the nodes inner text is empty or zero the default attribute will be used providing the default attribute is not also empty or zero 
    **************************
    Supported mapping ids include...
    **************************
        - AssetId - Corresponds to the WorksOrderDetail.AssetId
        - ContactId - Maps to RepairRequest.MainContactId
        - Description - Maps to RepairRequest.Problem        
        - PriorityId - Maps to RepairRequest.PriorityId
        - PriorityText - Maps to RepairRequest.PriorityId (requires lookUpTypeId)
        - WorksOrderAccessNotes - Maps to WorksOrderDetail.AccessNotes
        - WorksOrderRepairTypeId - Maps to WorksOrderDetail.RepairTypeId
        - WorksOrderRepairTypeText - Maps to WorksOrderDetail.RepairTypeId (requires lookUpTypeId)
        - WorksOrderOutcomeId - Maps to WorksOrderDetail.OutcomeId
        - WorksOrderOutcomeText - Maps to WorksOrderDetail.OutcomeId (requires lookUpTypeId)        
        - WorksOrderPriorityId - Maps to WorksOrderDetail.PriorityId
        - WorksOrderPriorityText - Maps to WorksOrderDetail.PriorityId (requires lookUpTypeId)
        - WorksOrderStatusId - Maps to WorksOrderDetail.OrderStatusId
        - WorksOrderStatusText - Maps to WorksOrderDetail.OrderStatusId    
        - WorksOrderDescription - Maps to WorksOrderDetail.Description
        - WorksOrderAdditionalAnalysisId Maps to WorksOrderDetail.AdditionalAnalysisId
        - WorksOrderAdditionalAnalysisText- Maps to WorksOrderDetail.AdditionalAnalysisId
        - WorksOrderRework - Maps to WorksOrderDetail.Rework  
        - WorksOrderRightToRepair - Maps to WorksOrderDetail.RightToRepair
        - Repairs - Maps to repairTasks
        - LocationId - Maps to RepairTaskDetail.LocationId
        - LocationText - Maps to RepairTaskDetail.LocationId (requires lookUpTypeId)
        - InspectionTypeText - Maps to InspectionDetail.InspectionTypeId
        - InspectionAccessDetails - Maps to InspectionDetail.AccessDetails
        - InspectionDescription - Maps to InspectionDetail.Description
        - InspectionOutcomeTypeId - Maps to InspectionDetail.OutcomeId
        - InspectionOutcomeTypeText - Maps to InspectionDetail.OutcomeId
        - InspectionStatusId - Maps to InspectionDetail.InspectionStatusId
        - InspectionStatusText - Maps to InspectionDetail.InspectionStatusId
    **************************
    For further details see https://github.com/Omfax-Systems/Keyfax/issues/1210
-->
<CxMappings>
  <Config>
    <Api>
      <!-- i.e. https://cxtest.domain.co.uk/ or https://cxnewtest.domain.org.uk/ -->
      <Url>https://cx.domain.org.uk/</Url>
      <Username>CxUser</Username>
      <Password>*********************</Password>      
    </Api>
    <Web>
      <Redirect>
        <!-- Optional URL to display a link to the created repair request within Civica CX after Keyfax complete (on Completed/Default.aspx) -->
        <!-- If either settings are ommited no link is displayed. {RepairRequestId} and {WorksOrderId} will be replaced with the real IDs at runtime -->
        <!-- {RepairContactId} will get repalced with the MainContactId associated against the created repair request -->
        <RepairRequestText>Open Civica CX Repair Request</RepairRequestText>
        <RepairRequestUrl>https://cx.domain.org.uk/cx/LaunchScreen?token=&amp;EntityType=RepairRequest&amp;EntityId={RepairRequestId}</RepairRequestUrl>
      </Redirect>
    </Web>
    <Admin active="1">
      <List id="inspectionTypes">
        <Item value="0">Service</Item>
        <Item value="1">Pre Inspection</Item>
        <Item value="2">Post Inspection</Item>
      </List>
    </Admin>
  </Config>
  <Mappings>
  <RD>
    <!-- ************ Repair Request ************ -->
    <Mapping id="ContactId" default="213101" xPath="Fault[@name='Fault1']/ClientID/text()"/>
    <Mapping id="AssetId" xPath="Fault[@name='Fault1']/AssetID/text()"/>
    <!--<Mapping id="Description" default="N/A" xPath="Fault[@name='Fault1']/FaultText/text()" />-->
    <Mapping id="Description" default="N/A" xPath="Fault[@name='Fault1']/FaultText/text(),Fault[@name='Fault2']/FaultText/text(),Fault[@name='Fault3']/FaultText/text()" maxLen="1000" />
    <Mapping id="PriorityId" default="4" requireXPath="false" lookUpTypeId="0" xPath="Fault[@name='Fault1']/Repair[@name='Repair1']/Priority/text()"  />
    <!-- ************ Works Order ************ -->    
    <Mapping id="WorksOrderStatusText" default="Entered Request" xPath="Fault/StatusText" />
    <Mapping id="WorksOrderPriorityId" default="4" lookUpTypeId="0" requireXPath="false" xPath="Fault[@name='Fault1']/Repair[@name='Repair1']/Priority/text()"  />
    <Mapping id="WorksOrderRepairTypeId" default="3" lookUpTypeId="1" xPath="Fault[@name='Fault1']/Nominal_Code/text()"  />        
    <Mapping id="WorksOrderOutcomeText" default="Contractor Cancelled" lookUpTypeId="145" />
    <Mapping id="WorksOrderDescription" default="N/A" xPath="Fault[@name='Fault1']/FaultText/text(),Fault[@name='Fault2']/FaultText/text(),Fault[@name='Fault3']/FaultText/text()" maxLen="1000" />        
    <Mapping id="WorksOrderAdditionalAnalysisText" default="NA" lookUpTypeId="19" />
    <Mapping id="WorksOrderRework" default="0" xPath="Fault[@name='Fault1']/Rework/text()" />
    <Mapping id="WorksOrderRightToRepair" default="0" xPath="Fault[@name='Fault1']/RTR/text()" />
    <Mapping id="WorksOrderAccessNotes" default="N/A" xPath="Fault[@name='Fault1']/Additional_Info/text()" />    
    <Mapping id="WorksOrderAdditionalAnalysisId" default="12" lookUpTypeId="19" xPath="Fault[@name='Fault1']/WorksOrderAdditionalAnalysisId/text()" />    
    <!-- ************ Repair Tasks ************ -->
    <Mapping id="Repairs" requireXPath="false" xPath="Fault/Repair"/>
    <Mapping id="LocationText" default="Bathroom" lookUpTypeId="43" />
    <!-- ************ Inspections ************ -->
    <!-- IMPORTANT: Inspections elements must always have a default attribute as the xPath may not appear within all Keyfax reuslts -->
    <Mapping id="InspectionTypeId" default="1" xPath="Fault[@name='Fault1']/Action[@name='Action1' and @type='MIS_INSPECTION']/ActionCodeEx/text()" lookUpTypeId="50057" />
    <Mapping id="InspectionOutcomeTypeId" default="1" xPath="Fault[@name='Fault1']/InspectionOutcomeTypeId/text()" lookUpTypeId="18" />
    <Mapping id="InspectionPriorityId" default="2" xPath="Fault[@name='Fault1']/Action[@name='Action1' and @type='MIS_INSPECTION']/Priority/text()" lookUpTypeId="0" />
    <Mapping id="InspectionStatusId" default="1" xPath="Fault[@name='Fault1']/InspectionStatusId/text()" lookUpTypeId="62" />
    <Mapping id="InspectionAccessDetails" default="N/A" xPath="Fault[@name='Fault1']/Additional_Info/text(),Fault[@name='Fault2']/Additional_Info/text(),Fault[@name='Fault3']/Additional_Info/text()" maxLen="1000" />
    <Mapping id="InspectionDescription" default="N/A" xPath="Fault[@name='Fault1']/FaultText/text(),Fault[@name='Fault2']/FaultText/text(),Fault[@name='Fault3']/FaultText/text()" maxLen="1000" />
    <Mapping id="InspectorId" default="0" xPath="Fault[@name='Fault1']/InspectorID/text()" />    
  </RD>
  <FL>
    <Mapping id="ContactId" default="24786" xPath="Enquiry[@name='Enquiry1']/ClientID/text()"/>
    <Mapping id="AssetId" xPath="Enquiry[@name='Enquiry1']/AssetID/text()"/>
    <Mapping id="Description" default="Test description - should be overriden by xPath" xPath="Fault[@name='Fault1']/FaultText/text()" />
    <Mapping id="StatusText" default="Entered - Request" xPath="Enquiry/StatusText" />
    <Mapping id="RepairTypeText" default="Response - General Reactive" lookUpTypeId="1" />
    <Mapping id="OutcomeText" default="Right First Time" lookUpTypeId="145" />
    <Mapping id="WorksOrderDescription" default="Test works order description" xPath="Fault[@name='Fault1']/FaultText/text()"  />
    <Mapping id="LocationText" default="General" lookUpTypeId="43" />
  </FL>
  <ROL>
    <Mapping id="ContactId" default="24786" xPath="Call[@name='Call1']/ClientID/text()"/>
    <Mapping id="AssetId" xPath="Call[@name='Call1']/AssetID/text()"/>
    <Mapping id="Description" default="Test description - should be overriden by xPath" xPath="Fault[@name='Fault1']/FaultText/text()" />
    <Mapping id="StatusText" default="Entered - Request" xPath="Call/StatusText" />
    <Mapping id="RepairTypeText" default="Response - General Reactive" lookUpTypeId="1" />
    <Mapping id="OutcomeText" default="Right First Time" lookUpTypeId="145" />
    <Mapping id="WorksOrderDescription" default="Test works order description" xPath="Fault[@name='Fault1']/FaultText/text()"  />
    <Mapping id="Repairs" xPath="Call/Repair"/>
    <Mapping id="LocationText" default="General" lookUpTypeId="43" />
  </ROL>
  <EOL>
    <Mapping id="ContactId" default="24786" xPath="Call[@name='Call1']/ClientID/text()"/>
    <Mapping id="AssetId" xPath="Call[@name='Call1']/AssetID/text()"/>
    <Mapping id="Description" default="Test description - should be overriden by xPath" xPath="Fault[@name='Fault1']/FaultText/text()" />
    <Mapping id="StatusText" default="Entered - Request" xPath="Call/StatusText" />
    <Mapping id="RepairTypeText" default="Response - General Reactive" lookUpTypeId="1" />
    <Mapping id="OutcomeText" default="Right First Time" lookUpTypeId="145" />
    <Mapping id="WorksOrderDescription" default="Test works order description" xPath="Fault[@name='Fault1']/FaultText/text()"  />
    <Mapping id="Repairs" xPath="Call/Repair"/>
    <Mapping id="LocationText" default="General" lookUpTypeId="43" />
  </EOL>
</Mappings>
</CxMappings>

hashtag
General Mappings

The mappings file supports the following identifiers. These can be used for the id attribute. These identifgiers are used to tell the mappings code which properties to use the mapping for within Civica CX.

  • AssetId - Corresponds to the WorksOrderDetail.AssetId

  • ContactId - Maps to RepairRequest.MainContactId

  • Description - Maps to RepairRequest.Problem

  • RepairTypeId - Maps to WorksOrderDetail.RepairTypeId

  • RepairTypeText - Maps to WorksOrderDetail.RepairTypeId

  • OutcomeId - Maps to WorksOrderDetail.OutcomeId

  • OutcomeText - Maps to WorksOrderDetail.OutcomeId

  • StatusId - Maps to WorksOrderDetail.OrderStatusId

  • StatusText - Maps to WorksOrderDetail.OrderStatusId

  • LocationId - Maps to RepairTaskDetail.LocationId

  • LocationText - Maps to RepairTaskDetail.LocationId

  • Repairs - Maps to repairTasks

  • PriorityId - Maps to WorksOrderDetail.PriorityId

  • PriorityText - Maps to WorksOrderDetail.PriorityId

  • WorksOrderDescription - Maps to WorksOrderDetail.Description

Each mapping is described in further detail below...

hashtag
- AssetId

The AssetId mapping is required when creating a repair request. If a AssetId is not provided or is invalid you may see the following error....

A AssetId value is always required. If Keyfax returns a zero or empty AssetId then the value specified within the default attribute of the <Mapping/> element will be used if the default attribute value is not also zero or empty.

hashtag
- ContactId

The ContactId is required when creating a repair request. If a contact Id is not provided or an invalid id is provided you may see the following error....

A ContactId value is always required. If Keyfax returns a zero or empty ContactId then the value specified within the default attribute of the <Mapping/> element will be used if the default attribute value is not also zero or empty.

hashtag
- Description

The Description mapping is required when creating a repair request. If a Description is not provided you may see the following error....

hashtag
- RepairTypeId & RepairTypeText

A RepairTypeId or RepairTypeText mapping is required. The RepairTypeId attribute allows you to explicitly set the ID to use whilst the RepairTypeText mapping allows you to search for a particular repair type within CX by description.

If you provide a 'RepairText' mapping and the repair text cannot be found you'll see an error like so...

If the RepairTypeId is omitted you will see the following error....

hashtag
- StatusId & StatusText

The StatusId and StatusText mappings are optional and can be omitted. If omitted the repair request will still be created. The StatusId attribute allows you to explicitly set the ID to use whilst the StatusText mapping allows you to search for a particular status within CX by description.

If you provide a StatusText mapping that cannot be found within CX you'll see the following error...

hashtag
- PriorityId & PriorityText

The PriorityId and PriorityText mappings are optional and can be omitted. If omitted the repair request will still be created. The PriorityId attribute allows you to explicitly set the ID to use whilst the PriorityText mapping allows you to search for a particular priority within CX by description.

If you provide a PriorityText mapping that cannot be found within CX you'll see the following error...

hashtag
- OutcomeId & OutcomeText

A OutcomeId or OutcomeText mapping is required. The OutcomeId attribute allows you to explicitly set the ID to use whilst the OutcomeText mapping allows you to search for a particular outcome within CX by description.

If you provide a OutcomeText mapping that cannot be found within CX you'll see the following error...

If an invalid OutcomeId is provided Citivca CX will return the following error...

hashtag
- Repairs

Repair tasks are optional and if committed the repair request will still be created.

hashtag
- WorksOrderDescription

The WorksOrderDescription is required. If the WorksOrderDescription is committed or empty the following error may be thrown...

hashtag
How are the correct CX mappings used for the export XML script type?

The mappings file should contain a root Mappings element with a child element representing the script type for the mappings. The mappings matching the type attribute on the supplied Keyfax Export XML will be used. For example if the following export XML is provided...

Then the Mappings/RD mappings will be used. If the following export XML is provided...

Then the Mappings/EOL mappings will be used.

hashtag
Look Up Values

If a non-numeric default attribute value and lookUpTypeId attribute value are provided within the CX mappings the mapping code will load all look up values matching the supplied lookUpTypeId and will search for the lookUpId who's description matches the text supplied within either the default attribute or the evaluated xPath expression. If the text is not found then 0 would be returned. This search is not case sensitive. For example notice the Location drop down list below is automatically set...

This was populated via the following CX mapping...

In the above example we are using the default attribute to search all look up value descriptions that belong to the look up type with ID 43. If we find a look up value with the description "Example Location" then the lookUpId is returned. This can also be overridden via the xPath attribute to dynamically return the text to search for.

For example to populate the works order outcome ID within CX with the correct lookUpId we could also provide a mapping like so...

This will then take the inner text found within "Fault/CX/OutcomeText element within the Keyfax export XML and if this is not a numeric value will search for this value within all look up value descriptions who's type matches ID 145 within Civica CX. If a match is found (not case-sensitive) then the correct lookUpId will be returned and associated with the works order outcome.

You can also set the lookUpId explicitly using the default attribute (not via a text search) via the corresponding ID version of each look up value mapping. For example...

Or again this could be obtained via a valid xPath expression from the Keyfax export XML...

hashtag
Repair Location

The Repairs Locations look up field type within CX (LookUpTypeId: 43) was empty at the time of development and so I populated this look up type with a single value for testing purposes as shown below...

You can see this value can be set for tasks...

This was populated via the following CX mapping...

hashtag
Inspection Mappings

The following mappings can be used to control how inspections are created from the export XML produced by Keyfax...

circle-info

IMPORTANT Inspection mappings must always have a default attribute as the xPath may not appear within all Keyfax reuslts. The default is used if no data is returned from Keyfax.

PreviousIntroductionNextStart Up Data

Last updated