Power Pages Portals

Learn how to install KeyNamics within your Power Pages Portal.

After KeyNamics has been fully configured & installed navigate to your Power Pages portals URL.

The URL for your portal will typically be in the form https://{yourportalname}.powerappsportals.com where {yourportalname} represents the name choose for your portal during portal set-up. If your portal administrator has configured a custom domain name for your portal you may need to contact your portal administrator to confirm the URL you should to access your portal.

If you are the portal administrator you can visit https://make.powerapps.com/ and click "Apps" on the left. You should see your portal application listed and you can browse to the portal as shown below...

image

Once you've navigated to your Power Apps portal KeyNamics will be available on one or more pages within your portal.

KeyNamics is generally installed and configured by Omfax Systems within your Dynamics environment and portal administrators would generally not need to worry about configuring portal pages. For completeness details on how KeyNamics can be added to portal pages is provided below.

Installing KeyNamics for Power Pages Portals

To support different scenarios KeyNamics for Power Apps portals can be embedded on a Power App Portal page in a few different ways. We refer to these scenarios as...

• Minimal Keyfax is launched via a simple hyperlink from the portal page. Results are handled via a Power Automate Flow.

• Entity Form Keyfax is launched via a Basic or Advanced entity form embedded on the portal page. Results are handled either via field mappings to update the entity form or via a Power Automate Flow.

Both scenarios are demonstrated further below. With either scenario portal page layout and styling can be customized to perfectly reflect your organizations branding. All styles used by KeyNamics within portal pages use the standard Bootstrap styles provided by Power Apps portals.

Minimal

At a minimum you can embed KeyNamics on a Power App Portal page using a regular anchor tag (hyperlink). You can see in the screen grab below we have a single button that launches Keyfax...

image

For reference the HTML & liquid code for this portal page are provided below...

<!-- keyfax.css & keyfax.js are web files within the portal -->
<link href="/keyfax.css" rel="stylesheet" type="text/css">
<script src="/keyfax.js"></script>
<!-- Hidden fields required by KeyNamics -->
<input id="txtKeyfaxGuid" type="hidden">
<!-- Liquid code to populate a hidden field with the authenticated portal users contactid -->

<div data-gb-custom-block data-tag="if">

<input type="hidden" id="contact_id" value="{{user.contactid}}" />            

</div>

<div class="row sectionBlockLayout">
    <div class="container">
        <div class="col-md-12 columnBlockLayout">
            <h2>Report a Repair</h2> 
            <!-- Status label -->
            <p id="lblKeyfaxStatus">Loading...</p>
            <!-- Button to launch Keyfax -->
            <button id="btnLaunchKeyfax" type="button" onclick="window.keynamics.launchUrl(false);">Launch Keyfax Scripts</button>
        </div>
    </div>
</div>

<script>
    // The JavaScript necessary to configure and initialize KeyNamics
    // This should be included in the portal page after the keyfax.js file has been included
    $(document).ready(function () {
        // Initialize KeyNamics
        window.keynamics.init({            
            /* The current Dynamics entity name (for example keyfax_test, new_tenants, account, contact, case, job etc) */
            /* Defaults to Global if not specified */
            currentEntityName: "keyfax_test"
        });
    });
</script>

When the "Launch Keyfax Scripts" button is clicked the launchUrl() method is called within the keyfax.js JavaScript file to create the users KeyNamics session and open Keyfax within a pop-up window. This is shown below...

image

The tenant would typically walk through the script until completion. Once complete the opening portal page is made aware Keyfax has completed, this is shown below...

image

Developers can leverage several client side events exposed by the KeyNamics for Power Apps portals JavaScript API to implement custom functionality once Keyfax completes or is cancelled. For further information see the "Customizing the KeyNamics for Power App Portal JavaScript" section within this guide.

If the minimal scenarios is used it's recommended portal administrators leverage Power Automate Flows to perform any additional post-processing of Keyfax results. For further information on this please refer to the "Using Power Automate Flows to process Keyfax results" section of this guide.

Entity Form

To leverage the field mapping functionality offered by KeyNamics portal administrators can also embed KeyNamics within any portal entity form. Field mappings can be used to then send field values to Keyfax to provide context aware scripting or update fields on this form with information from Keyfax once Keyfax completes.

You can see an example of KeyNamics embedded within a basic portal entity form below...

image

As with the minimal scenario when the "Launch Keyfax Scripts" button is click Keyfax is presented within a pop-up window as shown below...

image

Once the portal page detects Keyfax has completed fields on the form are updated based on configured "Receive from Keyfax" field mappings within KeyNamics. You can see below we've updated two fields with results from Keyfax...

image

In addition to using field mappings to update entities within Dataverse with results from Keyfax portal administrators can also leverage Power Automate Flows to perform additional post-processing of Keyfax results. For further information on this please refer to the "Using Power Automate Flows to process Keyfax results" section of this guide.

For reference the HTML & liquid code for this portal entity form are provided below...

<div class="row sectionBlockLayout">
    <div class="container">

        <div class="col-md-12" style="margin: 60px 0 24px 0;">
            <h3>Portal Test Form</h3>
            <p>An example entity form added via liquid<br></p>
        </div>

        <!-- Populate a hidden field with key details for the authenticated portal user from the contacts entity -->
        <!-- Send to Keyfax mappings can be used to read these fields and provide the values to Keyfax for use within scripts -->
        

<div data-gb-custom-block data-tag="if">

        <input type="hidden" id="contact_id" value="{{user.contactid}}" />        
        

</div>

        <!-- Keyfax (keyfax.css & keyfax.js are added as web files to the portal -->
        <!-- Both files can be found within the /PortalWebFiles folder of the KeyNamics solution -->
        <link href="/keyfax.css" rel="stylesheet" type="text/css">
        <script src="/keyfax.js"></script>

        <!-- The liquid tag to embed the entity form into the portal page -->
        <!-- Only one "entityform" liquid tag is supported per portal page -->
        <div class="col-md-12">
            

<div data-gb-custom-block data-tag="entityform" data-0='Portal Test Form'></div>

        </div>

    </div>    

    <!-- Configure & initialize KeyNamics -->
    <script>
        // The JavaScript necessary to configure and initialize KeyNamics
        // This should be included in the portal page after the keyfax.js file has been included
        $(document).ready(function () {
            // Initialize KeyNamics
            window.keynamics.init({
                /* If provided Keyfax DOM elements will be programmatically appended to the specified selector */
                /* This can be used to inject the Keyfax launch button and status label into a specific area on an entity form */
                /* The WebResource_Keyfax selector is the name of the web resource added to the portal test form */
                /* If found on the page this element will be replaced with the real Keyfax launch button and status label */
                appendTo: "#WebResource_Keyfax",
                /* The current Dynamics entity name (for example keyfax_test, new_tenants, account, contact etc) */
                /* Defaults to Global if not specified */
                currentEntityName: "keyfax_test",   
                /* Optional client accessing KeyNamics, typically used to load different Keyfax configurations based on the supplied client name */
                /* Defaults to "repairs-online" if not specified */
                client: "repairs-online"           
            });
        });
    </script>
</div>

You will notice within the above code example the entity form is embedded within the portal page using the `

` liquid tag. The name supplied here matches the name of our Basic Form within the portal as shown below...

image

The "Portal Test Form" has a web resource field with the name WebResource_Keyfax. At run-time this web resource is replaced with the KeyNamics launch button and status label. You can see an example of this below...

image

When embedding KeyNamics within a entity form it's important to ensure the currentEntityName property is updated within the KeyNamics for Power Apps portals JavaScript to align with the entity being used by the entity form. For example if we are displaying an entity form to allow users to create jobs and the jobs form is associated with a new_jobs entity within Dataverse we should update the KeyNamics for Power Apps portals JavaScript code embedded on the portal page as shown below...

<script>
    $(document).ready(function () {
        window.keynamics.init({            
            currentEntityName: "new_jobs"
        });
    });
</script>

This allows you to configure entity specific field mappings within KeyNamics that will only be applied for the new_jobs entity or when the jobs form is presented. This is helpful if you wish to present KeyNamics within several different entity forms and apply different field mappings for each form.

Understanding Sessions and Results within KeyNamics

Sessions (keyfax_session)

When KeyNamics is launched an entry is always added to the keyfax_session entity within Dynamics to represent the users KeyNamics session. This provides the user launching KeyNamics with a global unique identifier to represent the session which is then used for subsequent requests to obtain session specific data. You can review all created KeyNamics sessions via the "Sessions" link available within the KeyNamics model driven app as shown below...

image

Results (keyfax_result)

When KeyNamics completes results for the Keyfax script are always added to the keyfax_result entity within Dynamics. You can review all created KeyNamics results via the "Results" link available within the KeyNamics model driven app as shown below...

image

For convenience the results produced by Keyfax are available within the keyfax_result entity as both XML and JSON. You can review each result entry within the Results area of the KeyNamics app to view this XML or JSON.

Sessions & Results are automatically purged

By default any entries older than 31 days within the keyfax_session and keyfax_result entities will be automatically deleted by two System Jobs defined within Dynamics. The purge duration for these entities can be adjusted via the BulkDeleteSessionPurgeDays & BulkDeleteResultPurgeDays KeyNamics settings.

For further information see the "New System Jobs" section within #864

Understanding the KeyNamics lifecycle

When KeyNamics is launched either manually via a hyperlink or automatically via an event the following steps are followed.

Launching Keyfax

1. Create KeyNamics Session - The clients browser makes a POST request to /_api/keyfax_sessions. This adds an entry into the keyfax_session entity within Dataverse to represent the users KeyNamics session. This POST request returns a global unique identifier or GUID to represent the clients session. This GUID is later used within subsequent requests to identify the users KeyNamics session. From here on in we will refer to this GUID as the KeyNamics Session ID.

2. Invoke LaunchKeyfaxUrl action - Upon receipt of a KeyNamics Session ID the clients browser then makes an additional POST request to /_api/keyfax_sessions/Microsoft.Dynamics.CRM.keyfax_LaunchKeyfaxUrl supplying the KeyNamics Session ID. This invokes the LaunchKeyfaxUrl action. The LaunchKeyfaxUrl action is C# server side code hosted within Dynamics and is responsible for taking the "Send to Keyfax" mappings defined within KeyNamics and constructing the start-up data required by Keyfax to return a launch URL. The LaunchKeyfaxUrl action posts this start-up data to Keyfax to obtain a unique launch URL and then updates the keyfax_session entry within Dynamics matching the users KeyNamics Session ID.

3. Get KeyNamics Session - Once this LaunchKeyfaxUrl action completes and launch information has been successfully added to the keyfax_session entity within Dynamics the clients browser then makes an additional GET request to /_api/keyfax_sessions to obtain the Keyfax launch URL for the users KeyNamics session.

KeyNamics will now launch Keyfax within a pop-up window. The tenant would walk through the Keyfax script until completion.

This is further illustrated below...

KeyNamics for Power Apps portals - Launch Flow 2 drawio

Obtaining Keyfax Results

Upon completion of a script KeyNamics adds the Keyfax script results to the keyfax_result entity within Dataverse. The results are available in both XML and JSON form via the keyfax_xml and keyfax.json columns within the keyfax_result entity. The keyfax_result entity is populated as follows...

1. Create KeyNamics Results - Upon completion of a script the clients browser makes POST request to /_api/keyfax_results to create an entry within the keyfax_result entity within Dataverse representing the results for the users KeyNamics session. This call returns back a global unique identifier the client can use to identify the results. We will refer to this global unique identifier as the KeyNamics Result ID.

2. Invoke GetResult action - Upon receipt of the KeyNamics Result ID the clients browser makes an additional POST request to /_api/keyfax_sessions/Microsoft.Dynamics.CRM.keyfax_GetResult supplying the KeyNamics Result ID. This invokes the GetResult action. The GetResult action is C# server side code hosted within Dynamics and is responsible for obtaining results from Keyfax and exposing these results via "Receive from Keyfax" mappings to update entity forms or via the keyfax_result entity.

3. Get KeyNamics Result - Once the GetResult action completes and results have been successfully added to the keyfax_result entity within Dynamics the clients browser then makes an additional GET request to /_api/keyfax_results to obtain the "Receive from Keyfax" mappings necessary to update fields if KeyNamics is embedded within a Basic or Advanced portal entity form. If KeyNamics is not embedded within an entity form within your portal you will likely need to use a Power Automate Flow to perform custom processing against the results added to the keyfax_result entity within Dataverse.

This is illustrated below...

KeyNamics for Power Apps portals - Results Flow drawio

To monitor health and performance whenever KeyNamics is launched or results are obtained we measure & log the following timing metrics...

• Request Time The number of milliseconds it took the clients browser to perform a POST request into Dataverse

• Keyfax Execution Time The number of milliseconds it took the server side Dynamics action to communicate with and parse the response from the Keyfax Web API

• Action Execution Time The number of milliseconds it took in total for the server side Dynamics action to execute. This includes the Keyfax Execution Time.

To track the client request time an additional HTTP request is necessary. We feel this is a worthwhile tradeoff as the additional request should be negligible under normal circumstances and capturing this client request time can helps isolate KeyNamics performance problems.

The above metrics are available for review via the Sessions or Results links within the KeyNamics model driven app or via the complimentary Power BI dashboard provided with KeyNamics.

Using Power Automate Flows to process Keyfax results

With Power Automate Flows you can use a low-code, drag-and-drop approach to develop optional, automated flows to perform additional post-processing of data produced by KeyNamics.

To give you a sense for what's possible Power Automate Flows can be used to...

• Manipulate any entity within Dataverse when Keyfax is launched

• Manipulate any entity within Dataverse when Keyfax completes or is cancelled

• Integrate with hundreds of 3rd party connectors to automate common tasks

• Trigger additional notifications (post to Slack / Trello or send SMS / push notifications)

• Make smarter decisions leveraging artificial intelligence with AI Builder

Creating a Power Automate Flow

Power Automate Flows typically represent business workflows and as such are often unique for each organization. For this reason we cannot provide a one size fits all flow however here we'll aim to offer some general examples and tips & tricks to help you quickly develop a unique Power Automate Flow to interact with KeyNamics.

To help you get started we'll create a simple Power Automate Flow to send a few example emails & update an example entity within Dataverse whenever results are added as a result of a user completing a script within KeyNamics.

1. Visit https://flow.microsoft.com/

2. Click Create within the menu on the left

3. Selected Automated Cloud Flow as shown below...

image

1. Provide a name for your flow. For the trigger choose "When a row is added, modified or deleted" for Microsoft Dataverse. This is shown below...

image

1. Once you've created the flow you'll see the following screen...

image

1. Update the trigger as shown below, this will ensure the flow will execute only when new Keyfax results are added to the keyfax_result entity within Dataverse. In this example whenever the keyfax_xml column within the keyfax_result entity is modified the flow will execute. The keyfax_xml column holds the final results for Keyfax scripts within XML format within Dataverse. The important trigger properties to update are...

• Change type: Added or modified

• Table name: Results

• Scope: Organization

• Select columns: keyfax_xml

TIP The keyfax_json column provides Keyfax results in JSON form. If you prefer to work with JSON you may wish to monitor for changes on the keyfax_json column and not the keyfax_xml column.

The above trigger is shown below...

image

1. To make it easier to work with the result XML, we'll first add this to an XML variable within our flow. You'll need to add a variable action and define as shown below...

image

The expression for this variable is xml(triggerOutputs()['body/keyfax_xml']). Within the flow we can now refer to this variable and execute XPath expressions against this XML to iterate with the XML or pull out specific elements.

1. To further demonstrate this let's create another variable called Actions. This variable will use an XPath expression to return a collection of all action XML elements within our Keyfax results. You can see this below...

image

The expression for this variable is xpath(Variables('Xml'), '/KeyfaxData/Call/Action')

1. Next we'll create an "Apply to each" action within the flow to iterate each <Action/> XML element within the previously defined action variable. We'll check the type of action and if the action is of type "Email" we'll send an email from the flow. The basic action is shown below...

image

During each iteration we can execute XPath expressions against each found <Action/> XML element as shown below...

image

The full expression for the condition action is xpath(xml(item()), 'string(/Action/TaskTemplate/Task/@Type)'). We check the value of the type attribute and if this equals "Email"" we trigger an email action as shown below...

image

You can see we pull out the recipient, subject and body for the email from the KeyNamics results using the following expressions...

• xpath(xml(item()), 'string(/Action/TaskTemplate/Task/Email/Addresses/To)')

• xpath(xml(item()), 'string(/Action/TaskTemplate/Task/Email/Subject)')

• xpath(xml(item()), 'string(/Action/TaskTemplate/Task/Email/Body)')

It's important to remember that Keyfax will send configured emails and task emails don't need to be sent via a Power Automate Flow. We've used this example to demonstrate more advanced ways developers can interact with the XML provided by KeyNamics.

1. Finally you can see below whenever our flow is triggered we can update any other entity within Dataverse with information from the KeyNamics result. In the example below we are adding a new row to a Test entity within Dataverse and setting the Name column of this new row to the global unique identifier issued by Keyfax to uniquely identify the Keyfax session. This is shown below...

image

The full XPath expression to populate the name column with the Keyfax global unique identifier from the result XML is xpath(Variables('Xml'), 'string(/KeyfaxData/GUID)').

Further Flow Considerations

• Keep it simple (At least at the beginning)

• How is your flow handled when the user cancels the Keyfax script

• How is your flow handled when the keyfax_session or keyfax_result entities are automatically purged

• How is your flow handled for different script types (if your installation supports multiple Keyfax script types)

Example Results Produced by KeyNamics

The results shown below are for example purposes only and do not represent real world results. These results are just provided as a convenience to show the most common elements exposed by Keyfax Please review the final Export XML produced for your KeyNamics installation by visiting the Results page within the KeyNamics app and inspecting the XML column.

Repairs Online (minimal example JSON)

{
  "root": {
    "Call": {
      "name": "Call1",
      "type": "ROL",
      "OriginatingSystem": "org870a925a",
      "Config": {},
      "CategoryId": "24685",
      "CategoryText": "Communal",
      "TopicId": "42384",
      "TopicText": "Automatic barriers",
      "CallText": "Automatic barriers; automatic barrier; won't close; Car park",
      "LogDate": "20/01/2022 16:40:52",
      "UserCode": "operator",
      "ScriptPath": {},
      "ExpenditureCode": {},
      "ContractCode": {},
      "PreAuthoriseRequired": {},
      "ReasonCode": {},
      "ReasonText": {},
      "Recharge": "0",
      "RechargeCode": "RREP",
      "RechargeCost": "127.50",
      "ScheduleId": "operator\\148",
      "SiteVisit": "Example additional appointment information.",
      "AdditionalInfo": "Example additional information",
      "SpecialInstructions": {},
      "RepairCount": "1",
      "AdviceCount": "0",
      "ActionCount": "2",
      "SubActionCount": "1",
      "Repair": {
        "name": "Repair1",
        "CompleteBy": "25/01/2022 16:40:52",
        "ResponseDays": "5",
        "Priority": "U",
        "PriorityId": "26059",
        "RepairCode": "ELE003",
        "RepairCodeDesc": "AUTOMATIC ARM BARRIER: FIND FAULT AND RECTIFY",
        "UnitOfMeasure": "IT",
        "UnitOfMeasureQuantity": "1",
        "Contractor": {}
      },
      "Action": [
        {
          "name": "Action1",
          "type": "KF_ROL_TASK",
          "ActionCode": "OFFICE",
          "ActionCodeDesc": "Email office with repair details",
          "HasSubActions": "True",
          "Priority": "R",
          "PriorityID": "26060",
          "TaskTemplate": {
            "ID": "OFFICE",
            "AutoClose": "False",
            "Name": "Email office with repair details",
            "Notifications": {},
            "Reassignments": {},
            "Task": {
              "Type": "Email",
              "Item": "1",
              "SentDate": {},
              "UserID": {},
              "Description": {},
              "Email": {
                "Sent": "True",
                "Attachments": [
                  "True",
                  {
                    "Attachment": {
                      "Item": "1",
                      "Type": "File",
                      "Body": {},
                      "ItemName": {}
                    }
                  }
                ],
                "Addresses": {
                  "To": "[e-mail]",
                  "From": "[e-mail]",
                  "CC": {},
                  "BCC": {}
                },
                "Subject": "operator\\148 Automatic barriers; automatic barrier; won't close; Car park 20 Jan 2022",
                "Body": {
                  "Merge": "True",
                  "Merged": "True"
                }
              }
            }
          }
        },
        {
          "name": "Action2",
          "type": "KF_ROL_TASK",
          "ActionCode": "REQUEST",
          "ActionCodeDesc": "Your repair request",
          "HasSubActions": "False",
          "Priority": "R",
          "PriorityID": "26060",
          "TaskTemplate": {
            "ID": "REQUEST",
            "AutoClose": "False",
            "Name": "Your repair request",
            "Notifications": {},
            "Reassignments": {},
            "Task": {
              "Type": "Email",
              "Item": "1",
              "SentDate": {},
              "UserID": {},
              "Description": {},
              "Email": {
                "Sent": "True",
                "Attachments": [
                  "False",
                  {}
                ],
                "Addresses": {
                  "To": "[e-mail]",
                  "From": "[e-mail]",
                  "CC": {},
                  "BCC": {}
                },
                "Subject": "Your Repair Request",
                "Body": {
                  "Merge": "True",
                  "Merged": "True"
                }
              }
            }
          }
        }
      ],
      "SubAction": {
        "name": "SubAction1",
        "owner": "OFFICE",
        "type": "SCRIPT_CAPTURE",
        "ParentActionCode": "OFFICE",
        "SubActionKey": "PhotoPath",
        "SubActionValue": {}
      }
    },
    "ROLDetail": {
      "ROLDetail": {
        "Appointments": "Mon 08:00- 12:00,  12:00- 14:00,  14:00- 16:00. "
      },
      "CompanyInfo": {
        "Email": {},
        "EmergencyTel": {},
        "Name": {},
        "Website": {}
      }
    },
    "Status": "1",
    "GUID": "ccf56fc0-8d1e-4671-93f7-902810659537"
  }
}

Repairs Online (minimal example XML)

<root>
    <Call name="Call1" type="ROL">
        <OriginatingSystem>org870a925a</OriginatingSystem>
        <Config></Config>
        <CategoryId>24685</CategoryId>
        <CategoryText>Communal</CategoryText>
        <TopicId>42384</TopicId>
        <TopicText>Automatic barriers</TopicText>
        <CallText>Automatic barriers; automatic barrier; won't close; Car park</CallText>
        <LogDate>20/01/2022 16:40:52</LogDate>
        <UserCode>operator</UserCode>
        <!-- ScriptPath format designed for task formatting! -->
        <ScriptPath>
            <![CDATA[html|Which component is not working? <b>automatic barrier</b><br />|html|What's the problem? <b>won't close</b><br />|html|Where is it? <b>Car park</b><br />|]]>
        </ScriptPath>
        <ExpenditureCode />
        <ContractCode />
        <PreAuthoriseRequired />
        <ReasonCode></ReasonCode>
        <ReasonText></ReasonText>
        <Recharge>0</Recharge>
        <RechargeCode>RREP</RechargeCode>
        <RechargeCost>127.50</RechargeCost>
        <ScheduleId>operator\148</ScheduleId>
        <SiteVisit>Example additional appointment information.</SiteVisit>
        <AdditionalInfo>Example additional information</AdditionalInfo>
        <SpecialInstructions></SpecialInstructions>
        <RepairCount>1</RepairCount>
        <AdviceCount>0</AdviceCount>
        <ActionCount>2</ActionCount>
        <SubActionCount>1</SubActionCount>
        <Repair name="Repair1">
            <CompleteBy>25/01/2022 16:40:52</CompleteBy>
            <ResponseDays>5</ResponseDays>
            <Priority>U</Priority>
            <PriorityId>26059</PriorityId>
            <RepairCode>ELE003</RepairCode>
            <RepairCodeDesc>AUTOMATIC ARM BARRIER: FIND FAULT AND RECTIFY</RepairCodeDesc>
            <UnitOfMeasure>IT</UnitOfMeasure>
            <UnitOfMeasureQuantity>1</UnitOfMeasureQuantity>
            <Contractor></Contractor>
        </Repair>
        <Action name="Action1" type="KF_ROL_TASK">
            <ActionCode>OFFICE</ActionCode>
            <ActionCodeDesc>Email office with repair details</ActionCodeDesc>
            <HasSubActions>True</HasSubActions>
            <Priority>R</Priority>
            <PriorityID>26060</PriorityID>
            <TaskTemplate ID="OFFICE" AutoClose="False">
                <Name>Email office with repair details</Name>
                <Notifications />
                <Reassignments />
                <Task Type="Email" Item="1">
                    <SentDate />
                    <UserID />
                    <Description>
                        <![CDATA[Repair request recieved]]>
                    </Description>
                    <Email Sent="True" Attachments="True">
                        <Addresses>
                            <To>[e-mail]</To>
                            <From>[e-mail]</From>
                            <CC></CC>
                            <BCC></BCC>
                        </Addresses>
                        <Subject>operator\148 Automatic barriers; automatic barrier; won't close; Car park 20 Jan 2022</Subject>
                        <Body Merge="True" Merged="True">
                            <![CDATA[<p>A repair has been raised by&nbsp;<b></b>&nbsp;on&nbsp;<b>Thu 20 Jan 2022 - 16:40</b> . This repair has been given reference <b>operator\148</b></p><p>This repair relates to : <b>Automatic barriers; automatic barrier; won't close; Car park</b></p><p>The Repair Code details are: <b><table id="xformServicesMain" border="1" cellspacing="1" cellpadding="1" width="735"><tr style="FONT-WEIGHT: bold"><td>Code</td><td>Description</td><td>Priority</td><td>Quantity</td><td>Unit</td><td>Complete by</td></tr><tr><td>ELE003</td><td>AUTOMATIC ARM BARRIER: FIND FAULT AND RECTIFY</td><td>U</td><td>1</td><td>IT       </td><td>25/01/2022 16:40:52</td></tr></table></b></p><p>The priority is: <b>U</b></p><p>Vulnerabilities: <b>Not found Not found</b></p><p>Additional Information&nbsp;: <b></b></p><p>Requested appointment for this repair is :&nbsp;<b>Mon 08:00- 12:00,  12:00- 14:00,  14:00- 16:00.</b></p><p>Appointment Notes&nbsp;: <b></b></p><p>Address to attend the repair is :<br /><br /><b>Not found</b></p><p>&nbsp;</p>]]>
                        </Body>
                        <Attachments>
                            <Attachment Item="1" Type="File">
                                <Body>
                                    <![CDATA[Uploaded file]]>
                                </Body>
                                <ItemName>
                                    <![CDATA[Not found]]>
                                </ItemName>
                            </Attachment>
                        </Attachments>
                    </Email>
                </Task>
            </TaskTemplate>
        </Action>
        <Action name="Action2" type="KF_ROL_TASK">
            <ActionCode>REQUEST</ActionCode>
            <ActionCodeDesc>Your repair request</ActionCodeDesc>
            <HasSubActions>False</HasSubActions>
            <Priority>R</Priority>
            <PriorityID>26060</PriorityID>
            <TaskTemplate ID="REQUEST" AutoClose="False">
                <Name>Your repair request</Name>
                <Notifications />
                <Reassignments />
                <Task Type="Email" Item="1">
                    <SentDate />
                    <UserID />
                    <Description>
                        <![CDATA[Your Repair Request]]>
                    </Description>
                    <Email Sent="True" Attachments="False">
                        <Addresses>
                            <To>[e-mail]</To>
                            <From>[e-mail]</From>
                            <CC></CC>
                            <BCC></BCC>
                        </Addresses>
                        <Subject>Your Repair Request</Subject>
                        <Body Merge="True" Merged="True">
                            <![CDATA[<p>Dear&nbsp;</p><p>Your repair request dated&nbsp;&nbsp;Thu 20 Jan 2022 - 16:40&nbsp;has been recorded; you can use the reference&nbsp;operator\148&nbsp;if you need to contact us about the repair.</p><p>If this repair is accepted we will contact you with next steps.</p><table cellspacing="1" cellpadding="1" width="800" border="1"><tbody><tr><td>Your repair request relates to:</td><td>Automatic barriers; automatic barrier; won't close; Car park</td></tr><tr><td>You entered the following additional information:</td><td></td></tr><tr><td>Your preferred appointment slot:</td><td>Mon 08:00- 12:00,  12:00- 14:00,  14:00- 16:00.</td></tr><tr><td>You entered the following notes regarding the appointment:</td><td></td></tr><tr><td>You answered the following questions:</td><td>Which component is not working? <b>automatic barrier</b><br />What's the problem? <b>won't close</b><br />Where is it? <b>Car park</b><br /></td></tr></tbody></table><p><br />&nbsp;The repair may need to be inspected. If so, you&nbsp;will be contacted by one of our&nbsp;team to arrange a visit.</p><p>&nbsp;Should you wish to speak to one of our&nbsp;team about this repair, or in the case of an emergency please call:&nbsp;<strong>XXXXX XXXXXX</strong><br /><br />&nbsp;If you want to discuss a repair you have already reported, please let us know your repair order number. This helps us find the details on our computer quickly.</p><p>&nbsp;Website:&nbsp;<b>www.XXXX.co.uk</b><br />&nbsp;Email: <strong><a href="mailto:[e-mail]">[e-mail]</a></strong></p>]]>
                        </Body>
                        <Attachments />
                    </Email>
                </Task>
            </TaskTemplate>
        </Action>
        <SubAction name="SubAction1" owner="OFFICE" type="SCRIPT_CAPTURE">
            <ParentActionCode>OFFICE</ParentActionCode>
            <SubActionKey>PhotoPath</SubActionKey>
            <SubActionValue></SubActionValue>
        </SubAction>
    </Call>
    <ROLDetail>
        <ROLDetail>
            <Appointments>Mon 08:00- 12:00,  12:00- 14:00,  14:00- 16:00. </Appointments>
        </ROLDetail>
        <CompanyInfo>
            <Email />
            <EmergencyTel />
            <Name />
            <Website />
        </CompanyInfo>
    </ROLDetail>
    <Status>1</Status>
    <GUID>ccf56fc0-8d1e-4671-93f7-902810659537</GUID>
</root>

Enquiries Online (minimal JSON example)

{
  "root": {
    "Call": {
      "name": "Call1",
      "type": "EOL",
      "OriginatingSystem": "org870a925a",
      "Config": {},
      "CategoryId": "41552",
      "CategoryText": "Estate management",
      "TopicId": "41554",
      "TopicText": "Garage rental",
      "CallText": "Garage rental",
      "LogDate": "21/01/2022 09:39:12",
      "UserCode": "operator",
      "ScriptPath": {},
      "ExpenditureCode": {},
      "ContractCode": {},
      "PreAuthoriseRequired": {},
      "ReasonCode": {},
      "ReasonText": {},
      "Recharge": "0",
      "RechargeCode": {},
      "RechargeCost": "0.00",
      "ScheduleId": {},
      "SiteVisit": {},
      "AdditionalInfo": "Example additional information",
      "SpecialInstructions": {},
      "RepairCount": "0",
      "AdviceCount": "1",
      "ActionCount": "3",
      "SubActionCount": "3",
      "Advice": {
        "name": "Advice1",
        "defer": "0",
        "sequence": "",
        "AdviceCode": "EOL011",
        "AdviceCodeDesc": "Garage rental",
        "AdviceHtml": {}
      },
      "Action": [
        {
          "name": "Action1",
          "type": "KF_EOL_TASK",
          "ActionCode": "REQUEST",
          "ActionCodeDesc": "Your enquiry details",
          "HasSubActions": "False",
          "Priority": "1",
          "PriorityID": "29884",
          "TaskTemplate": {
            "ID": "REQUEST",
            "AutoClose": "False",
            "Name": "Your enquiry details",
            "Notifications": {},
            "Reassignments": {},
            "Task": {
              "Type": "Email",
              "Item": "1",
              "SentDate": {},
              "UserID": {},
              "Description": {},
              "Email": {
                "Sent": "False",
                "Attachments": [
                  "False",
                  {}
                ],
                "Addresses": {
                  "To": {},
                  "From": "[e-mail]",
                  "CC": {},
                  "BCC": {}
                },
                "Subject": "Your enquiry details  Fri 21 Jan 2022 -09:39",
                "Body": {
                  "Merge": "True",
                  "Merged": "False"
                }
              }
            }
          }
        },
        {
          "name": "Action2",
          "type": "KF_EOL_TASK",
          "ActionCode": "OFFICE",
          "ActionCodeDesc": "Email office with enquiry details",
          "HasSubActions": "False",
          "Priority": "1",
          "PriorityID": "29884",
          "TaskTemplate": {
            "ID": "OFFICE",
            "AutoClose": "False",
            "Name": "Email office with enquiry details",
            "Notifications": {},
            "Reassignments": {},
            "Task": {
              "Type": "Email",
              "Item": "1",
              "SentDate": {},
              "UserID": {},
              "Description": {},
              "Email": {
                "Sent": "False",
                "Attachments": [
                  "False",
                  {}
                ],
                "Addresses": {
                  "To": {},
                  "From": "[e-mail]",
                  "CC": {},
                  "BCC": {}
                },
                "Subject": {},
                "Body": {
                  "Merge": "True",
                  "Merged": "False"
                }
              }
            }
          }
        },
        {
          "name": "Action3",
          "type": "KF_EOL_TASK",
          "ActionCode": "SURVEY",
          "ActionCodeDesc": "Customer Suggestions",
          "HasSubActions": "True",
          "Priority": "3",
          "PriorityID": "29886",
          "TaskTemplate": {
            "ID": "SURVEY",
            "AutoClose": "False",
            "Name": "Customer Suggestions",
            "Notifications": {},
            "Reassignments": {},
            "Task": {
              "Type": "Email",
              "Item": "1",
              "SentDate": {},
              "UserID": {},
              "Description": {},
              "Email": {
                "Sent": "True",
                "Attachments": [
                  "False",
                  {}
                ],
                "Addresses": {
                  "To": "[e-mail]",
                  "From": "[e-mail]",
                  "CC": {},
                  "BCC": {}
                },
                "Subject": "Customer Sat Survey Results",
                "Body": {
                  "Merge": "True",
                  "Merged": "True"
                }
              }
            }
          }
        }
      ],
      "SubAction": [
        {
          "name": "SubAction1",
          "owner": "SURVEY",
          "type": "SCRIPT_CAPTURE",
          "ParentActionCode": "SURVEY",
          "SubActionKey": "Survey01",
          "SubActionValue": "test"
        },
        {
          "name": "SubAction2",
          "owner": "SURVEY",
          "type": "SCRIPT_CAPTURE",
          "ParentActionCode": "SURVEY",
          "SubActionKey": "SurveyCSAT",
          "SubActionValue": "5 - Very Satisfied"
        },
        {
          "name": "SubAction3",
          "owner": "SURVEY",
          "type": "SCRIPT_CAPTURE",
          "ParentActionCode": "SURVEY",
          "SubActionKey": "SurveyNPS",
          "SubActionValue": "10 - Promoter"
        }
      ]
    },
    "ROLDetail": {
      "CompanyInfo": {
        "Email": {},
        "EmergencyTel": {},
        "Name": {},
        "Website": {}
      }
    },
    "Status": "1",
    "GUID": "748a5422-d0a4-42e5-a936-7ffbabbccdfa"
  }
}

Enquiries Online (minimal XML example)

<?xml version="1.0"?>
<root>
  <Call name="Call1" type="EOL">
    <OriginatingSystem>org870a925a</OriginatingSystem>
    <Config/>
    <CategoryId>41552</CategoryId>
    <CategoryText>Estate management</CategoryText>
    <TopicId>41554</TopicId>
    <TopicText>Garage rental</TopicText>
    <CallText>Garage rental</CallText>
    <LogDate>21/01/2022 09:39:12</LogDate>
    <UserCode>operator</UserCode>
    <!-- ScriptPath format designed for task formatting! -->
    <ScriptPath><![CDATA[html|What type of application is this? <b>apply to rent a garage</b><br />|html|Where would you prefer to rent a garage? <b>Bucklow Hill</b><br />|html|How would you rate this experience? <b>5 - Very Satisfied</b><br />|html|How likely is it that you would recommend us to a friend? 0 (not likely at all)  to 10 (extremely likely) <b>10</b><br />|html|How could we improve your experience? <b>test</b><br />|]]></ScriptPath>
    <ExpenditureCode/>
    <ContractCode/>
    <PreAuthoriseRequired/>
    <ReasonCode/>
    <ReasonText/>
    <Recharge>0</Recharge>
    <RechargeCode/>
    <RechargeCost>0.00</RechargeCost>
    <ScheduleId/>
    <SiteVisit/>
    <AdditionalInfo>Example additional information</AdditionalInfo>
    <SpecialInstructions/>
    <RepairCount>0</RepairCount>
    <AdviceCount>1</AdviceCount>
    <ActionCount>3</ActionCount>
    <SubActionCount>3</SubActionCount>
    <Advice name="Advice1" defer="0" sequence="">
      <AdviceCode>EOL011</AdviceCode>
      <AdviceCodeDesc>Garage rental</AdviceCodeDesc>
      <AdviceHtml><![CDATA[<p>We offer a limited number of garages for rent. Our garages are clean, dry units and we are able to offer packaging to protect your belongings.<br /><br />You will be the only keyholder for your garage and can access it 24 hours a day, 7 days a week. We can add you to our garage waiting list, to be notified when one becomes available.<br /><br /><b>Cost</b><br />The rent for garages in the city is:</p><ul><li>Tenants: &pound;XX.XX per week (depending on area)</li><li>Others: &pound;XX.XX per week (depending on area)</li></ul><p>We have reduced rental charges available if you are:</p><ul><li>Buying or leasing a car, or have bought a car through the Motability Scheme or privately</li><li>Receive the Higher rate Disability Living Allowance with a mobility component</li></ul><p>This does not apply automatically to all Blue Badge Holders. You must provide proof you qualify for the reduced rent and provide a copy of your car documents.</p>]]></AdviceHtml>
    </Advice>
    <Action name="Action1" type="KF_EOL_TASK">
      <ActionCode>REQUEST</ActionCode>
      <ActionCodeDesc>Your enquiry details</ActionCodeDesc>
      <HasSubActions>False</HasSubActions>
      <Priority>1</Priority>
      <PriorityID>29884</PriorityID>
      <TaskTemplate ID="REQUEST" AutoClose="False">
        <Name>Your enquiry details</Name>
        <Notifications/>
        <Reassignments/>
        <Task Type="Email" Item="1">
          <SentDate/>
          <UserID/>
          <Description><![CDATA[Your enquiry]]></Description>
          <Email Sent="False" Attachments="False">
            <Addresses>
              <To/>
              <From>[e-mail]</From>
              <CC/>
              <BCC/>
            </Addresses>
            <Subject>Your enquiry details  Fri 21 Jan 2022 -09:39</Subject>
            <Body Merge="True" Merged="False"><![CDATA[<p><img alt="" src="http://dev.touch-base.com/KFResources/Ext/ivoldemobanner.png" /></p><p>Dear&nbsp;<b></b>&nbsp;thank you for your enquiry made via the On-Line Enquiry Service.</p><p>Your enquiry dated&nbsp;<b>Fri 21 Jan 2022 -09:39</b> has been recorded;</p><p>You answered the following questions</p><p><b>What type of application is this? <b>apply to rent a garage</b><br />Where would you prefer to rent a garage? <b>Bucklow Hill</b><br />How would you rate this experience? <b>5 - Very Satisfied</b><br />How likely is it that you would recommend us to a friend? 0 (not likely at all)  to 10 (extremely likely) <b>10</b><br />How could we improve your experience? <b>test</b><br /></b></p><p>Should you wish to speak to one of our members of staff about this enquiry please call: <b>01869242967</b></p><p>If you want to discuss an enquiry you have already made, please let us know your enquiry reference number. This helps us find the details on our website.</p><p>Website: <b>www.omfax.co.uk</b><br />Email: <b>[e-mail]</b></p><p><img alt="" src="http://dev.touch-base.com/KFResources/Ext/omfaxlogo.gif" /></p>]]></Body>
            <Attachments/>
          </Email>
        </Task>
      </TaskTemplate>
    </Action>
    <Action name="Action2" type="KF_EOL_TASK">
      <ActionCode>OFFICE</ActionCode>
      <ActionCodeDesc>Email office with enquiry details</ActionCodeDesc>
      <HasSubActions>False</HasSubActions>
      <Priority>1</Priority>
      <PriorityID>29884</PriorityID>
      <TaskTemplate ID="OFFICE" AutoClose="False">
        <Name>Email office with enquiry details</Name>
        <Notifications/>
        <Reassignments/>
        <Task Type="Email" Item="1">
          <SentDate/>
          <UserID/>
          <Description><![CDATA[Enquiry received]]></Description>
          <Email Sent="False" Attachments="False">
            <Addresses>
              <To/>
              <From>[e-mail]</From>
              <CC/>
              <BCC/>
            </Addresses>
            <Subject/>
            <Body Merge="True" Merged="False"><![CDATA[<p>An enquiry has been made by &nbsp;on Fri 21 Jan 2022 -09:39.</p><p>This enquiry relates to : </p><table cellspacing="1" cellpadding="1" width="200" border="1"><tbody><tr><td>Address</td><td></td></tr><tr><td>&nbsp;</td><td></td></tr><tr><td>&nbsp;</td><td></td></tr><tr><td>Town</td><td><p></p></td></tr><tr><td>Postcode</td><td><p></p></td></tr></tbody></table><p>&nbsp;Email: </p>]]></Body>
            <Attachments/>
          </Email>
        </Task>
      </TaskTemplate>
    </Action>
    <Action name="Action3" type="KF_EOL_TASK">
      <ActionCode>SURVEY</ActionCode>
      <ActionCodeDesc>Customer Suggestions</ActionCodeDesc>
      <HasSubActions>True</HasSubActions>
      <Priority>3</Priority>
      <PriorityID>29886</PriorityID>
      <TaskTemplate ID="SURVEY" AutoClose="False">
        <Name>Customer Suggestions</Name>
        <Notifications/>
        <Reassignments/>
        <Task Type="Email" Item="1">
          <SentDate/>
          <UserID/>
          <Description><![CDATA[Customer Sat Survey Results]]></Description>
          <Email Sent="True" Attachments="False">
            <Addresses>
              <To>[e-mail]</To>
              <From>[e-mail]</From>
              <CC/>
              <BCC/>
            </Addresses>
            <Subject>Customer Sat Survey Results</Subject>
            <Body Merge="True" Merged="True"><![CDATA[<p>Date: <b>Jan 21 2022 09:39:12</b><br /><br />Tenant: <b></b><br />Address: <b></b><br /><br /><br />CSAT:<b>5 - Very Satisfied</b><br /><br />NPS:<b>10 - Promoter</b><br /><br />Customer Comment:<b>test</b></p>]]></Body>
            <Attachments/>
          </Email>
        </Task>
      </TaskTemplate>
    </Action>
    <SubAction name="SubAction1" owner="SURVEY" type="SCRIPT_CAPTURE">
      <ParentActionCode>SURVEY</ParentActionCode>
      <SubActionKey>Survey01</SubActionKey>
      <SubActionValue>test</SubActionValue>
    </SubAction>
    <SubAction name="SubAction2" owner="SURVEY" type="SCRIPT_CAPTURE">
      <ParentActionCode>SURVEY</ParentActionCode>
      <SubActionKey>SurveyCSAT</SubActionKey>
      <SubActionValue>5 - Very Satisfied</SubActionValue>
    </SubAction>
    <SubAction name="SubAction3" owner="SURVEY" type="SCRIPT_CAPTURE">
      <ParentActionCode>SURVEY</ParentActionCode>
      <SubActionKey>SurveyNPS</SubActionKey>
      <SubActionValue>10 - Promoter</SubActionValue>
    </SubAction>
  </Call>
  <ROLDetail>
    <CompanyInfo>
      <Email/>
      <EmergencyTel/>
      <Name/>
      <Website/>
    </CompanyInfo>
  </ROLDetail>
  <Status>1</Status>
  <GUID>748a5422-d0a4-42e5-a936-7ffbabbccdfa</GUID>
</root>

Customizing the KeyNamics for Power App Portal JavaScript

All client-side JavaScript required for KeyNamics for Power Apps portals is located within the keyfax.js JavaScript file. This file is added to your portal as a web file and referenced from the portal page that launches KeyNamics.

KeyNamics for Power Apps portals offers a single window.keynamics.init(options) method to both configure and initialize KeyNamics. The keynamics.init method would typically be called from the page load event within your portal page.

Important KeyNamics for Power Apps portals JavaScrip Properties

When initializing the KeyNamics for Power Apps portals JavaScript you can define a number of optional properties. These are described further below.

<script>
    $(document).ready(function () {
        window.keynamics.init({
            /* The default entity name */
            currentEntityName: "Global",
            /* The currently authenticated portal users contactId from the contact entity within Dynamics. */
            /* This is not applicable for model driven app types and only used for portal app types */
            /* This must be a valid GUID for authenticated users or an empty string for anonymous users. */
            currentContactId: "",
            /* The default originating system / organization name for portals */
            originatingSystem: win.location.host || "",
            /* The default user name for on-line */
            userName: "KFROL_User",
            /* The default optional parentId */
            parentId: "",
            /* The default language */
            lang: "en-gb",
            /* The default client (for example repairs, enquiries, repairs-online, enquiries-online, web, outlook, mobile etc) */
            /* This controls the Keyfax configuration and script type that will be loaded via the company & mode mappings */
            client: "repairs-online",
            /* The default launch behavior for Keyfax (iframe or popup) */
            launchType: "popup",
            /* If provided Keyfax DOM elements will be appended to the selector */
            appendTo: "#WebResource_Keyfax",
            /* The Id of the field containing the currently authenticated portals users contact Id */
            contactIdFieldId: "contact_id"
        });
    });
</script>

Available KeyNamics for Power Apps portals JavaScrip Events

When initializing the KeyNamics for Power Apps portals JavaScript you can define a number of optional events. These are described further below.

<script>
    $(document).ready(function () {
        window.keynamics.init({
            onKeyfaxCompleted: function () {
                // your code here
            },
            onKeyfaxCancelled: function () {
                //  your code here
            },
            onKeyfaxError: function () {
                //  your code here
            }
        });
    });
</script>

Understanding how KeyNamics is aware of the authenticated portal users

To ensure KeyNamics for Power Apps portals is aware of the authenticated portal user you must include the following liquid code within any portal page containing the keyfax.js JavaScript file. This liquid code populates a hidden field with the users contactid if they are authenticated within your portal...

<div data-gb-custom-block data-tag="if">

<input type="hidden" id="contact_id" value="{{user.contactid}}" />            

</div>

With this liquid code present within the portal page you can leverage the "Portal - the authenticated portal users contactid" source type option available within KeyNamics field mappings to automatically obtain the authenticated portal users contactid from the contacts entity within Dynamics as shown below...

image

The mapping can then be used to perform subsiquent FetchXML queries to obtain additional contact details...

image

In this example we are obtaining basic tenant address information to pass to the <Tenant/> element within the Keyfax start-up data - this automatically passes the tenants address as defined within Dynamics to the Keyfax script.