The Front-end Integration API is a functionality, that allows Pricefx Unity front-end to integrate with external applications' front-end. Either Pricefx Unity can embed the front-end of external application or the external application front-end can embed Pricefx Unity. Those 2 front-ends can then communicate using messaging.

Read on:

OLD DOCUMENTATION BELOW

The Front-end API is a functionality that allows Pricefx UI (Unity) to integrate with external applications. Either Pricefx UI can embed the UI of external application or the external application UI can embed Pricefx UI. Those 2 UIs can then communicate using messaging.

Pricefx UI (Unity) Embedding an External Application

It is possible to embed external applications which will be rendered in custom tabs on any CLIC detail page.
To do that, create a new CLIC type, i.e. a new Quote Type, with custom tabs configuration:

For further details about custom tabs, see Detail Page Layout and Dynamic Tabs.

The custom tab object should look like this:

{
  "name": "Survey",
  "type": "externalApp",
  "translationKey": "Survey",
  "parameters": {
    "externalAppUrl": "https://mysurvey.com/",
    "externalAppParameters": [
      {
        "some-flag": ""
      },
      {
        "quoteId": "id"
      }
    ]
  }
}

The possible fields in parameters are:

"externalAppParameters": [
  {
    "some-flag" : ""
  },
  {
    "quoteId" : "id"
  }
]

Please note that the application is embedded through an iframe, therefore it has some limitations as described in https://www.w3schools.com/tags/att_iframe_sandbox.asp. Currently, the permissions given are "allow-scripts allow-same-origin allow-forms allow-popups”.

Messaging support

It is possible to manipulate Unity through the usage of postMessage method: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage. It’s supported when Unity is embedded in some other platform, and also when another platform is embedded inside it.

To enable it, please append to your crm_config the following:

{
  ...otherConfigs,
  "feIntegration": {
    "active": true
  }
}

The messages must have 2 fields: source and type. For most messages, there will be also a payload field which will contain additional data for the sent message.

Source refers to the origin of the message, which can be either pfxParentMessage or pfxChildMessage.

Type is which kind of message is being sent, and can be any of the following described in the tables below.

Some kinds of messages will also return data, which will be also sent through postMessage.

Please note that the messages described in the table below (except for getUserData) has the same signature as in Interceptor CLIC API.

The messages available for both cases (where Unity is either the parent or child page) are:

{
  "source": "pfxParentMessage",
  "type": "getUserData"
}

{
  "source": "pricefx",
  "type": "GET_USER_DATA",
  "payload": {
    "locale": "en-gb",
    "email": "your@email.com",
    "loginName": "login.name",
    "roleNames": [...]
  }
}

{
  "source": "pfxChildMessage",
  "type": "getClicHeaderValue",
  "payload": {
    "fieldName": "externalRef"
  }
}

{
  "source": "pricefx",
  "type": "HEADER_VALUE",
  "payload": {
    "fieldName": "externalRef",
    "fieldValue": "externalReference"
  }
}

{
  "source": "pfxParentMessage",
  "type": "updateClicHeaderValue",
  "payload": {
    "fieldName": "externalRef",
    "fieldValue": "new externalRef"
  }
}

{
  "source": "pfxChildMessage",
  "type": "recalculate"
}

{
  "source": "pfxParentMessage",
  "type": "getClicLineItems",
  "payload": {
    "queryData": "AK_0001"
  }
}

{
  "source": "pricefx",
  "type": "LINE_ITEMS",
  "payload": {
    "queryData": "AK_0001",
    "lineItems": []
  }
}

{
  "source": "pfxParentMessage",
  "type": "addClicLineItems",
  "payload": {
    "lineItems": [
      {
        sku: "AK_0001',
        inputs: {
          Quantity: 3
        }
      }
    ]
  }
}

There are also messages which are exclusive to the case where Unity is embedded inside another application, since they manipulate window location:

{
  "source": "pfxParentMessage",
  "type": "newQuote",
  "payload": {
    "targetPageState": {
      "targetPageFields": {
        "externalRef": "created by message"
      }
    }
  }
}

{
  "source": "pfxParentMessage",
  "type": "navigate",
  "payload": {
    "targetPage": "priceShopPage",
    "id": "123"
  }
}

There are also events in Unity that will trigger a message. When submitting or recalculating a CLIC, a message will be sent containing all CLIC data, like below:

{
  "source": "pricefx",
  "type": "QUOTE_RECALCULATED",
  "payload": {
    "version": 7,
    "typedId": "2147493723.Q",
    "uniqueName": "P-2147493723",
    "label": "New Quote",
    "targetDate": "2023-05-29",
    "workflowStatus": "DRAFT",
    ...
  }
}

Implementation example

As you embed Unity inside another external application:

<iframe src="https://partition.pricefx.com" id="pfx-iframe"/>

You can start using it with the code below:

const iframe = document.getElementById('pfx-iframe');
const messageHandler = (event) => console.log(event.data);
window.addEventListener(messageHandler);
iframe.contentWindow.postMessage({
  "source": "pfxParentMessage",
  "type": "getUserData"
}, *);

In this case, you will attach a handler that logs the message it receives from Unity, and also will message Unity requesting the logged in user data.

On the other side, if you have an external application embedded in Unity:

const messageHandler = (event) => console.log(event.data);
window.addEventListener(messageHandler);
window.parent.postMessage({
  "source": "pfxParentMessage",
  "type": "getUserData"
}, *);

And you will have the same behavior as described for the first case.