Mapping Examples
Example mappings to help demonstrate KeyNamics mappings.
Last updated
Example mappings to help demonstrate KeyNamics mappings.
Last updated
This example demonstrates how to create a Mapping in order to send data to Keyfax and the accompanying Import XML Databox that is necessary to access that data within your scripts. Assuming there is a Defects Period date field on the current form which you wish to access within your scripts. You will need to create an entity level (in this case 'MainCase', or Global Mapping (for all entities) similar to that below. THe name of the form field is cust_defectsperiod:
This Mapping will store the Defects Period in the startup data that is sent to Keyfax. In Keyfax Admin Tools, you will need to create an Import Databox (and any related Expressions) to reference this data:
The Customer DataType is a Lookup field that you can use to specify a customer, which can be an Account or Contact. In previous releases of Dynamics 365 Customer Engagement (on-premises), several out-of-the-box entities such as the Case, Lead, and Opportunity entities, included a special kind of lookup field that represented a customer. Using this lookup field you could choose between two entities: Account or Contact.
With this new capability, you can add the Customer field to any system or custom entity. You can use the Customer field in more entities to track the customer's information in the same way you've used the Customer field in the Case, Lead, and Opportunity entities.
Let's look at an example as to how you might use a Customer data type within KeyNamics...
The requirement is that you need to set up KeyNamics Mappings to send either the Account or Contact name and address details (from the selection in the current Form's Customer Datatype field) to Keyfax in a single CSV string. You will need to set up the following Mappings and FetchXml queries, six items in all: To retrieve the name and address when the selection in the Customer field is the Account:
'Bookmark' Mapping to access the accountid on the current Form; this is used by the FetchXml query below
FetchXml query to retrieve Account details and concatenate the results into a CSV string
Mapping entry that invokes the FetchXml above and sends the data to Keyfax.
In much the same way, to retrieve the name and address when the selection in the Customer field is the Contact:
'Bookmark' Mapping to access the contactid on the current Form; this is used by the FetchXml query below
FetchXml query to retrieve Contact details and concatenate the results into a CSV string
Mapping entry that invokes the FetchXml above and sends the data to Keyfax.
Clearly, only one 'set' of mappings will work depending on what is currently selected in the Customer field. As such, it's important that no Default value is supplied in either of the above mapping entries (points 3 and 6). You may ask why? The reason is that if an Account record is currently selected on the Form and the Contact has a Default setting, this will override the Account details when sending data to Keyfax as no data wil be found. Similarly, if a Contact record is currently selected and the Account mapping has a Default setting the COntact details will be overridden by the Default. The whole premise of handling Customer fields is that one of the attempts to locate details will fail.
If no selection has been made, nothing will be sent to Keyfax.
Looking further into the Account example, the first thing to do is create a Mapping entry that accesses the Id of the Account. To retrieve this from the current form, see the Source field below. Also note that the Target is set to null and this prevents the mapping entry from being sent to Keyfax. It's a good idea to make clear this Mapping entry is merely used as a BookMark by naming it appropriately:
Next, create the FetchXml Statement to access fields as required. The example below retrieves name and address details. Notice that Bookmark #1 points at the Account Id derived from the Mapping above:
Finally, create the Mapping that invokes the FetchXml above and actualy sends the data to Keyfax. The account (or contact) name and address ends up in the Target, i.e. the 'Tenant' node, to be sent to Keyfax:
You will need to repeat the above to handle the selection of a Contact from the Customer field.
In the below example we demonstrate how to use a "Receive from Keyfax" mapping to access a specific value within the Keyfax results XML and populate an entity form field named keyfax_receive_category with this value.
Let's say we wanted to access the Fault_Category returned by Keyfax as shown below...
To access the Fault_Category value create a new mapping within KeyNamics using the following XPath query to select the Fault_Category value as highlighted above...
You can see an example of the full KeyNamics mapping below...
To identify the name of entity form fields on your entity form as used within the target value above please see the "Discovering Field Names" section within Mapping Entity Form Fields.
