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

<figure><img src="/files/sHwOOcDSivDiOtLDUhns" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/CiL3Xduz2eanGsBTaSkQ" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/SbFPDNF9k9htzlRQP6O5" alt=""><figcaption></figcaption></figure>

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

{% hint style="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.&#x20;
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keyfax.biz/integrations/host-systems/civica/civica-cx/mappings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.