...
The Front-end Integration API is a functionality , that allows the Pricefx Unity front-end to integrate with external applications' the front-end of external applications. Either Pricefx Unity can either embed the front-end of the external application or be embedded within the external application front-end can embed Pricefx Unity. Those 2 of the external application. These two front-ends can then communicate with each other using messaging.
Read on:
Child pages (Children Display) |
---|
OLD DOCUMENTATION BELOW
Tip |
---|
Available since version 11.0 (Paper Plane) |
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:
Code Block | ||
---|---|---|
| ||
{
"name": "Survey",
"type": "externalApp",
"translationKey": "Survey",
"parameters": {
"externalAppUrl": "https://mysurvey.com/",
"externalAppParameters": [
{
"some-flag": ""
},
{
"quoteId": "id"
}
]
}
} |
The possible fields in parameters are:
...
Parameter
...
Description
...
externalAppUrl
...
URL of the external application to be rendered.
...
externalAppParameters
...
Parameters, which will be passed in the URL as query string parameters.
The value of this externalAppParameters field can be either an object or an array of objects, depending on your needs.
If it is an object (with key-value pairs), the keys will be parsed as the string parameters keys and their corresponding value will be possible fields to be mapped from the CLIC object: externalRef, label, uniqueName and id. If an empty string is passed, it is parsed without any value.
If it is an array, it behaves the same way but fields will be provided in the final query string parameters in the same order as they are given.
Example of 2 parameters:
Code Block | ||
---|---|---|
| ||
"externalAppParameters": [
{
"some-flag" : ""
},
{
"quoteId" : "id"
}
] |
The example above will end up as query string ?some-flag"eId=123
.
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:
Code Block | ||
---|---|---|
| ||
{
...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:
...
Message type
...
Payload
...
Description
...
Example
...
Response
...
getUserData
...
none
...
Returns the logged user data.
...
Code Block | ||
---|---|---|
| ||
{
"source": "pfxParentMessage",
"type": "getUserData"
} |
...
Code Block | ||
---|---|---|
| ||
{
"source": "pricefx",
"type": "GET_USER_DATA",
"payload": {
"locale": "en-gb",
"email": "your@email.com",
"loginName": "login.name",
"roleNames": [...]
}
} |
...
getClicHeaderValue
...
fieldName: the field’s name which you would like to retrieve
...
Gets some header field’s value from the CLIC i.e. quote displayed. This is only enabled when a detail page is open.
...
Code Block | ||
---|---|---|
| ||
{
"source": "pfxChildMessage",
"type": "getClicHeaderValue",
"payload": {
"fieldName": "externalRef"
}
} |
...
Code Block | ||
---|---|---|
| ||
{
"source": "pricefx",
"type": "HEADER_VALUE",
"payload": {
"fieldName": "externalRef",
"fieldValue": "externalReference"
}
} |
...
updateClicHeaderValue
...
fieldName: the field’s name which you would like to update
fieldValue: the new value of this field
...
Updates some header field’s value. This is only enabled when a detail page is open.
...
Code Block | ||
---|---|---|
| ||
{
"source": "pfxParentMessage",
"type": "updateClicHeaderValue",
"payload": {
"fieldName": "externalRef",
"fieldValue": "new externalRef"
}
} |
...
none
...
recalculate
...
none
...
Recalculates the CLIC displayed. This is only enabled when a detail page is open.
...
Code Block | ||
---|---|---|
| ||
{
"source": "pfxChildMessage",
"type": "recalculate"
} |
...
none
...
getClicLineItems
...
queryData: can be either a query for more complex search or a string with the line item SKU
...
Returns the line items matching the given queryData criteria. This is only enabled when a detail page is open.
...
Code Block | ||
---|---|---|
| ||
{
"source": "pfxParentMessage",
"type": "getClicLineItems",
"payload": {
"queryData": "AK_0001"
}
} |
...
Code Block | ||
---|---|---|
| ||
{
"source": "pricefx",
"type": "LINE_ITEMS",
"payload": {
"queryData": "AK_0001",
"lineItems": []
}
} |
...
addClicLineItems
...
lineItems: an array of objects, each of them corresponding to one line item. It has one mandatory “sku” string field, and an optional object field called “inputs”, where it’s possible to pass line items inputs values
...
Add a list of SKUs to the current CLIC displayed, with the option of filling some of its inputs. This is only enabled when a detail page is open.
...
Code Block | ||
---|---|---|
| ||
{
"source": "pfxParentMessage",
"type": "addClicLineItems",
"payload": {
"lineItems": [
{
sku: "AK_0001',
inputs: {
Quantity: 3
}
}
]
}
} |
...
none
There are also messages which are exclusive to the case where Unity is embedded inside another application, since they manipulate window location:
...
Message type
...
Payload
...
Description
...
Example
...
Response
...
newQuote
newRebateAgreement
newContract
newCompensationPlan
...
targetPageState: the state of the newly created CLIC. Please check Context Linking , since this field follows the exact same signature as it’s used in Context Linking.
...
Creates a new quote/RBA/contract/compensation plan.
Values of this new CLIC can be passed through targetPageState, which reuses context linking and has the exact same API.
...
Code Block | ||
---|---|---|
| ||
{
"source": "pfxParentMessage",
"type": "newQuote",
"payload": {
"targetPageState": {
"targetPageFields": {
"externalRef": "created by message"
}
}
}
} |
...
none
...
navigate
...
targetPage
id
...
Navigates Unity to the given target page.
...
Code Block | ||
---|---|---|
| ||
{
"source": "pfxParentMessage",
"type": "navigate",
"payload": {
"targetPage": "priceShopPage",
"id": "123"
}
} |
...
none
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:
Code Block |
---|
{
"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:
Code Block | ||
---|---|---|
| ||
<iframe src="https://partition.pricefx.com" id="pfx-iframe"/> |
You can start using it with the code below:
Code Block | ||
---|---|---|
| ||
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:
Code Block | ||
---|---|---|
| ||
const messageHandler = (event) => console.log(event.data);
window.addEventListener(messageHandler);
window.parent.postMessage({
"source": "pfxParentMessage",
"type": "getUserData"
}, *); |
...