Configuration Steps

Configuration steps

1. Embedding CRMConnector iFrame

Embedding the CRMConnector iFrame involves integrating an external web application or service within your own web page. This is typically done by using an HTML <iframe> element, which allows you to embed another HTML page within the current page. The CRMConnector iFrame will display the CRMConnector interface, enabling users to interact with the CRM system directly from your application.

To embed the CRMConnector iFrame, you need to:

1. Obtain the URL of the CRMConnector application.
2. Add an <iframe> element to your HTML code with the src attribute set to the CRMConnector URL.
3. Optionally, set additional attributes like width, height, allow and style to control the appearance and behavior of the iFrame.

Example

<iframe src="https://crmconnector.example.com" width="600" height="400" style="border:none;" allow="camera; microphone"></iframe>

2. Authentication

Authentication is a crucial step in ensuring that only authorized users can access the CRMConnector. This process typically involves verifying the identity of users through various methods such as usernames and passwords, OAuth tokens, or API keys. Proper authentication ensures that sensitive data is protected and that users have the appropriate permissions to interact with the CRM system

3. Detection and Service Initialization

• CRMConnect checks the embedded iFrame's source URL and tries to match it to one of the pre-integrated CRMs.
• If it detects a non-matching URL, the CustomCRM service will be started, hence beginning the 2-way handshake communication, using the postMessage Web API

4. 2-way Handshake Communication

• The CRMConnector will send a ready ping to the ClientApplication
• The ClientApplication will receive the ready ping and send back a ready ping, having the role of ACK (Acknowledge).
• The CRMConnector will then send a requestCrmData in order to fetch the ClientCRM data and use it to start the system.
• The ClientApplication will fetch the requested data and send it back to the CRMConnector.
• From now on, both CRMConnector and ClientApplication will be permanently communicating via postMessage.

Example

// CRMConnector sends the ready ping
// ClientApplication receives the ready ping and sends the ACK back
// This is a piece of code from an in-place message event handler
// This needs to be implemented in the client app.
export const processCRMConnectorMessages = async (event) => {
  if (event.origin !== CRM_CONNECT_ORIGIN) { 
    return; 
  }
  const { action, data } = event.data;
  if (action === 'ready') {
    sendReadyPingToCRMConnector();
  }
}

// Example of sendReadyPingToCRMConnector() implementation
const sendReadyPingToCRMConnector = () => {
  publishMessage(clientIframe, CRM_CONNECT_ORIGIN, 'ClientAppMessage', 'ready');
}

// CRMConnector receives the ready ping from the ClientApplication
// and sends back the requestCrmData action
// ClientApplication uses the CRM's API in order to fetch the required data
// Builds an object following the required format (see each of the feature's subcategories)
// And sends it back to the CRMConnector

export const processCRMConnectorMessages = async (event) => {
  if (event.origin !== CRM_CONNECT_ORIGIN) { 
    return; 
  }
  const { action, data } = event.data;
  if (action === 'ready') {
    sendReadyPingToCRMConnector();
  } else if (action === 'requestCrmData') {
    sendCRMData();
  }
}

// Example of sendCRMData() implementation
const sendCRMData = () => {
  // Note that loadCrmConfiguration() method must be implemented
  loadCrmConfiguration().then(data => {
    if (!data) {
      return;
    }
    publishMessage(clientIframe, CRM_CONNECT_ORIGIN, 'ClientAppMessage', 'crmData', data);
  });
}

// Example of publishMessage() implementation
const publishMessage = (src, dest, type, action, data = {}) => {
  const msg = { type, action, data };
  src.contentWindow.postMessage(msg, dest);
}

//Example of publishMessage() usage
publishMessage(clientIframe, CRM_CONNECT_ORIGIN, 'ClientAppMessage', <action>, <data>);

5. Continuous Messaging:

To handle requests and data exchanges between applications, it is essential to implement permanent messaging. You can achieve this by following the example provided above, which demonstrates how to process CRM connector messages and send CRM data. Ensure that your implementation includes the processCRMConnectorMessages function to handle incoming messages. This setup will facilitate continuous communication between your applications.