# Creating Mappings

Creating a mapping entry is quite straight-forward. In it's most basic form, a mapping defines the data to be...

* **Sent to Keyfax** - To enrich the capabilities of the Keyfax scripts
* **Received from Keyfax - I**n order to populate fields in the current form once the script has completed

Below **KeyNamics Configuration\Mappings** click **New**. This will present the following screen:

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

### Fields

Below are descriptions of each of the fields required to create a Mapping entry.

#### Name

Any name which describes the data being mapped. Please enter only upper/lower case alphanumeric, space, dash and underscore characters.

{% hint style="info" %}
**TIP** if this mapping is merely to be used as a Bookmark for a FetchXml query, it is useful to name it accordingly so that it is clearly identified in a list of mappings, e.g. '**Bookmark: Contact Name and Address**'
{% endhint %}

#### **Entity Name/Global**

This is the name of the entity to which this mapping applies, e.g. **account, contact, cust\_repairs**. Essentially, this is the name of the form where the Keyfax launch button is located.\
\
If '**Global**' is specified, this mapping will be used across all Forms/Cases. \
\
&#x20;If a Global mapping exists, it can be **overridden** by an **entity-level** mapping with the same Target.

#### **Data Direction**

This determines whether this mapping will **send** data to, or **receive** data from Keyfax.

#### **Source Type**

If you are **sending** data to Keyfax you can select any of:

* The Dynamics Organisation Name
* The currently logged in Dynamics  Username
* FetchXml query - only available if you are sending data to Keyfax

If you don't select any of the above, the Source or Default fields specified in the form fields below will be used.\
\
If you are **receiving** data from Keyfax the Source Type field is hidden; in this case, it's only possible to specify an xPath into Keyfax's export data (XML).

#### **Source**

f you are sending data to Keyfax, this can be a **parent/field** specifier e.g. \
\
`contact/address1_composite`\
\
In this case, you will need to be certain that the Form that launches Keyfax actually has a current parent (e.g. Account, Contact etc).\
\
Alternatively, this can be an **xPath** that accesses any field on the Current form (importantly, - it must contain data) where Keyfax is being launched.  Fields on the current Form can be accessed as XML, e.g.&#x20;

* `//field[@name='contact']/@id`&#x20;

will return the **id** of the field named **contact**.&#x20;

**XPath** is a powerful construct. For example, if you wished to map data from different fields, any one of which *may* contain data:

* `//field[@name='contact' or @name='property'` **or** `@name='block' or @name='estate']/@value`

#### **Default**

If the data you are trying to send or receive does not exist, or no Source has been specified, or if you simply need to use a fixed value, this default value will be used. \
\
KeyNamics can run across different clients; these are currently defined as:

* **Web** - Unified Interface
* **Outlook** - Dynamics 365 for Outlook client
* **Mobile** - Mobile app

As it may be necessary to supply different default values for each client, this can be achieved by providing a comma-separated list of values, e.g.

* `web=RD,mobile=ROL,outlook=ROL`

#### **Target**

If this mapping is **sending** data to Keyfax, this will be the name of the node in the Startup data XML packet. For example:&#x20;

* `Caller/Name`
* `Caller/Title`

If **receiving** data from Keyfax, this is the form **field name** which will receive the data provided by the Keyfax diagnostic.\
\
Also, when receiving data from Keyfax scripts into **Lookup** fields in Dynamics, the scripts must export *the exact same text* as it appears in the Lookup, e.g. ‘Doors and Windows’., ‘Heating and Electrics’ etc.\
\
If the target specified is '**null**' this indicates that the mapping is purely used to derive data intended to satisfy **bookmarks** within **FetchXml** queries and will not be sent to Keyfax. \
\
If **multiple (comma separated) target names** are specified and the mapping is using a FetchXml query that returns multiple items, they will be split out to suit. For example, consider this FetchXml query which returns four items&#x20;

```
<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false" count="1">
   <entity name="systemuser" >
       <attribute name="domainname" />
       <attribute name="lastname" />
       <attribute name="isdisabled" />
       <attribute name="islicensed" />
       <filter type="and" >
           <condition attribute="fullname" operator="eq" value="[BOOKMARK#1]" />
       </filter>
   </entity>
</fetch>
```

By setting the target to:

* `domainName, lastName, isDisabled, isLicensed`

these four nodes will be created and sent to Keyfax in the startup/launch data.


---

# 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/product-suite/keynamics/configuration/mappings/creating-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.