requestCustomFieldsValues

Mandatory: No

Description: The requestCustomFieldsValues feature in the Client App enables the CRM Connector to request and retrieve the specified custom fields from a CRM in a required format. This ensures that the custom fields are accurately fetched and formatted according to the application's needs.

Implementation Example

// This is a part of the mandatory in-place event message handler
const processCRMConnectMessageData = async (event) => {
  if (event.origin !== CRM_CONNECT_ORIGIN) { 
      return; 
  }

  const { action, data } = event.data;
  if (action === 'requestCustomFieldsValues') {
    processRequestCustomFieldsValues(data);
  }
};

const processRequestCustomFieldsValues = async (data) => {
  const customFields = await getCustomFieldsValues(data.object);
  publishMessage(clientIframe, CRM_CONNECT_ORIGIN, 'ClientAppMessage', 'customFieldsDataResponse', customFields);
}

const getCustomFieldsValues = async (object) => {
  const voiceCustomFields = []; // Filter the voice custom fields from the object parameter (There might be empty string values so they must be filtered out)
  const digitalCustomFields = []; // Filter the digital custom fields from the object parameter (There might be empty string values so they must be filtered out)
  const customFields = {
    digital: await getCustomFieldAttributes(digitalCustomFields),
    voice: await getCustomFieldAttributes(voiceCustomFields)
  };
  // The required object MUST BE a stringified JSON object
  return JSON.stringify(customFields);
}

export const getCustomFieldAttributes = async (fieldNames) => {
  const returnedCustomFieldResult = {};
  const response = await <your_CRM_API_custom_fields_fetching_implementation>;

  if (response.status !== 200) {
    // Error handling mechanism
    return;
  }

  const customFields = []; // Retrieve the custom fields from your API Response
  if (!customFields.length) {
    return;
  }

  // Iterate through the customFields array and build the required object
  for (const field of customFields) {
    returnedCustomFieldResult[field.key] = parseCustomFieldAttributes(field);
  }
  return returnedCustomFieldResult;
}

export const parseCustomFieldAttributes = (customField) => {
  if (!customField) {
    return;
  }
  return {
    customFieldInfo: {
      // STRING: the text type, it is required to be named to STRING
      // PICKLIST: the dropdown type, it is required to be named to PICKLIST
      customFieldType: customField.type === 'text' ? 'STRING' : 'PICKLIST',
      customFieldLabel: customField.title
    }
  }
}

Message formats

CRM Connector

{ "type": "CRMConnectMessage", "action": "requestCustomFieldsValues", "data": <crmConnectorDataObject> }

CRM Connector data object format

{
  "object": {
    "digital": <array>, // String array of digital custom field names
    "fieldType": <string>, // The field type
    "voice": <array>, // String array of voice custom field names
  }
}

CRM Connector data object example

{
    "object": {
        "fieldType": "Task",
        "voice": [ "custom_voice1", "", "" ],
        "digital": [ "custom_digital1", "", "" ]
    }
}

Client Application

{ "type": "ClientAppMessage", "action": "customFieldsDataResponse", "data": <customFieldsObject> }

Custom Fields object format

{
  "digital": {
    [customDigitalFieldKey]: <customFieldObjectDetails>
  },
  "voice": {
    [customVoiceFieldKey]: <customFieldObjectDetails>
  }
}

Custom Fields object example

{
  "digital": {
    "custom_digital1": {
      "customFieldInfo": {
      "customFieldLabel": "Custom Digital Field 1",
      "customFieldType": "STRING",
      "customFieldSize": 25
      },
    }
  },
  "voice": {
    "custom_voice1": {
      "customFieldInfo": {
      "customFieldLabel": "Custom Voice Field 1",
      "customFieldType": "PICKLIST",
      "picklistDefaultValue": "Cat"
      },
      "customFieldOption": [
        { "name": "Dog", "value": "Dog" },
        { "name": "Cat", "value": "Cat" },
        { "name": "Pigeon", "value": "Pigeon" },
      ]
    }
  }
}

Custom Field object details format

{
  "customFieldInfo": {
    "customFieldLabel": <string>,
    "customFieldType": <string>,
    "customFieldSize": <number>, // Optional
    "picklistDefaultValue": <string>, // Optional
  },
  "customFieldOption": <array> // Optional (Array of <K:V> pairs)
}

Custom Field object details text example

{
  "customFieldInfo": {
    "customFieldLabel": "Custom Digital Field 1",
    "customFieldType": "STRING",
    "customFieldSize": 25 // Max text size
  },
}

Custom Field object details dropdown example

{
  "customFieldInfo": {
    "customFieldLabel": "Custom Voice Field 1",
    "customFieldType": "PICKLIST",
    "picklistDefaultValue": "Cat"
  },
  "customFieldOption": [
    { "name": "Dog", "value": "Dog" },
    { "name": "Cat", "value": "Cat" },
    { "name": "Pigeon", "value": "Pigeon" },
  ]
}