Mapping JSON Results

Learn how to return Keyfax results as JSON within KeyNamics.

NOTE The JSON results detailed below are generated on the Keyfax web server using Newtonsoft.JSON. This JSON is more reliable than the client side generated JSON used via the JSON dump field as detailed within Mapping Dump Fields. It's recommended you use the approach detailed below to return JSON if you wish to use JSON to reliably process Keyfax results.

The JSON stored within the keyfax_json column within the keyfax_result entity within KeyNamics is populated via the <ResultJson/> element returned from the GetResults SOAP based web service ran on the Keyfax web server.

To update a field on an entity form using "Receive from Keyfax" mappings with the JSON stored within the keyfax_result.keyfax_json column please follow the steps below.

Prerequisites

1. Ensure your Keyfax installation is using the "KeyNamics" export templates. This will ensure all JSON properties that should be represented as arrays are actually returned as arrays even if there is only 1 item returned.

2. Ensure Keyfax is set-up to return JSON results from the GetResult SOAP API end-point on the Keyfax web server. Ensure the SOAP/GetResult/@resultJson attribute within Keyfax configuration on the web server is set to 1.

Instructions

1. Ensure the KeyNamics environment has been updated to KeyNamics 3.1.0+ or is running the latest Keyfax.CRM.Solution.dll assembly - see "Updating existing environments" below.

2. Add a new multi-line text field to the desired entity form, this field will be populated with the value from keyfax_result.keyfax_json. This field should have a maximum length of 1,048,576 as shown below...

Make a note of the logical field name. We''ll need this later for the target within our final mapping. For now ensure the field is added to the entity form and the entity form is published after being updated. You can see an example below of the field we added during testing...

1. Create a new "Receive from Keyfax" mapping with a name & source of "GUID" as shown below...

Ensure the target is null as we'll only use this GUID mapping to obtain the Keyfax GUID to later perform a FetchXML query. This won't be used to update any entity form fields.

1. Create a new FetchXML statement using the previously created GUID mapping as a bookmark as shown below...

The FetchXML statement is included below...

• Name: Fetch keyfax_result.keyfax_json using Keyfax GUID

• Fetch XML:

<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="true">
  <entity name="keyfax_session">
    <link-entity name="keyfax_result" to="keyfax_sessionid" from="keyfax_session_id" link-type="inner">
      <attribute name="keyfax_json" />
    </link-entity>
    <filter type="and">
      <condition attribute="keyfax_guid" operator="eq" value="[BOOKMARK#1]" />
    </filter>
  </entity>
</fetch>

• Bookmark 1: GUID

This FetchXML simply selects the keyfax_json column from the keyfax_result entity using the Keyfax GUID and the relationship that exists between sessions and results within KeyNamics.

1. Finally create a new mapping to populate the multi-line text field we added to the entity form in step 2 with the result produced via the FetchXML statement created in step 4. above

The "Target" field should be the logical field name of the field we wish to update on the entity form.

1. Verify Results

Complete a Keyfax script and you should see the entity form field created in step 2 above is updated with the value from the keyfax_result.keyfax_json column....

Updating existing environments

At the time of writing KeyNamics 3.1.0 has not been released. If this update needs to be applied within a D365 environment before 3.1.0 is released we would need to update the Keyfax.CRM.Solution.dll assembly within the target environment with a version from source control. The plug-in registration tool should be used to update this assembly as shown below...

NOTE The above step will not be necessary once 3.1.0 has officially released and we compile a tested 3.1.0 solution.

Why is a 3.1.0 update necessary?

To allow mappings to query the keyfax_result entity using FetchXML the order in which the results are created has been changed. Results are now added to the keyfax_result entity before "Receive from Keyfax" mappings are constructed.

That's It

If we can assist further please don't hesitate to Contact Us.