Creating Mappings

Learn how to create mappings within KeyNamics.

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 - In 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:

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.

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'

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

• //field[@name='contact']/@id

will return the id of the field named contact.

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:

• 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

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