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>

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...

- `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....

An asset ID is always required to construct a valid repair request! Ensure a valid Civica CX AssetId mapping is configured. Parameter name: assetId

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.

- `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....

Main contact with Id=XX does not exist in the system.

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.

- `Description`

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

The CX Web Service at "POST https://cxtest.hebrideanhousing.co.uk/cx/WebService/WSRepairService" returned the following faults: Code: "s:Client", Message: "CreateRepairRequestAndOrWorksOrder has validation faults: Please enter Problem"

- `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...

GetLookUpByDescription - Unable to automatically obtain lookUpId. Could not find a look up value who's description equals "Response - General Reactive XYZ" and who's lookUpTypeId equals "1".

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

The CX Web Service at "POST https://cxtest.hebrideanhousing.co.uk/cx/WebService/WSRepairService" returned the following faults: Code: "s:Client", Message: "CreateRepairRequestAndOrWorksOrder has validation faults: Invalid Repair Type"

- `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...

GetWorksOrderStatus - Unable to automatically obtain status code. Could not find a status code who's description equals "Entered - Request XYZ".

- `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...

 GetLookUpByDescription - Unable to automatically obtain lookUpId. Could not find a look up value who's description equals "Entered - Request" and who's lookUpTypeId equals "50074".

- `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...

 GetLookUpByDescription - Unable to automatically obtain lookUpId. Could not find a look up value who's description equals "Right First Time XYZ" and who's lookUpTypeId equals "145".

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

The CX Web Service at "POST https://cxtest.hebrideanhousing.co.uk/cx/WebService/WSRepairService" returned the following faults: Code: "s:Client", Message: "CreateRepairRequestAndOrWorksOrder has validation faults: Invalid Outcome"

- `Repairs`

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

- `WorksOrderDescription`

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

 The CX Web Service at "POST https://cxtest.hebrideanhousing.co.uk/cx/WebService/WSRepairService" returned the following faults: Code: "s:Client", Message: "CreateRepairRequestAndOrWorksOrder has validation faults: Description is required"

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...

<Fault name=""Fault1"" type=""RD"">

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

<Call name=""Call1"" type=""EOL"">

Then the Mappings/EOL mappings will be used.

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...

<Mapping id="LocationText" default="Example Location" lookUpTypeId="43" />

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...

<Mapping id="OutcomeText" lookUpTypeId=""145"" xPath="Fault/CX/OutcomeText/text()" />

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...

<Mapping id="OutcomeId" default="123" />
<Mapping id="LocationId" default="456" />
<Mapping id="RepairTypeId" default="789" />
<Mapping id="PriorityId" default="50074" />

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

<Mapping id="OurcomeId" xPath="Fault/CX/OutcomeId/text()" />
<Mapping id="LocationId" xPath="Fault/CX/LocationId/text()" />
<Mapping id="RepairTypeId" xPath="Fault/CX/RepairTypeId/text()" />

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...

<Mapping id="LocationText" default="Example Location" lookUpTypeId="43" />

Inspection Mappings

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

<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()" />

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.

PreviousIntroduction NextStart Up Data

Last updated 5 months ago

General Mappings

- AssetId

- ContactId

- Description

- RepairTypeId & RepairTypeText

- StatusId & StatusText

- PriorityId & PriorityText

- OutcomeId & OutcomeText

- Repairs

- WorksOrderDescription