Creating the custom fields for user synchronization

Added in 24.04.

In this guide, you will learn how to create custom fields for user synchronization.

Note: Only Administrators can create the custom fields for user synchronization.

We will create a custom field Biography for user synchronization in this example.

Here is the GraphQL request to create the custom field.

In the setCommunitySalesforceSettings mutation, we are creating the custom field using the userSyncCustomField parameter.

mutation{
  setCommunitySalesforceSettings(
    settingsInput: {
        userSyncCustomField: "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<mappings type=\"users\">\n<!-- Mapping for single field -->\n<mapping>\n<crm> <!-- Salesforce field details -->\n<field-name>User_Biography__c</field-name> <!-- Salesforce field API name -->\n<mandatory>true</mandatory> <!-- To specify whether field is mandatory or not -->\n</crm>\n<lithium> <!-- Lithium field details -->\n<field-name>profile.biography</field-name> <!-- Lithium field name -->\n<default-value>admin</default-value> <!-- Default value against Lithium field, would be used when there is no data in Database -->\n<hardcoded-value></hardcoded-value> <!-- Hardcoded value against Lithium field. This overrides other values like from database or default -->\n</lithium>\n</mapping>\n<!-- Mapping for single field ends-->\n<!-- We can add mappings for multiple fields like as above-->\n</mappings>"
    }
  ) {
    result
    errors {
      __typename
    }
  }
}

The value for the userSyncCustomField should be set as an XML mapping of the CRM field with the Khoros profile fields.

From the sample XML in the above request, there are two main tags of single mappings.

1. <crm> tag - This tag represents CRM field details (Salesforce in our case).
   • <field-name> - This tag contains the Salesforce field API name.
   • <mandatory> - This is to specify whether this field is mandatory or not. If it is set as true, there must be a value against this field while synchronizing with Salesforce; otherwise, the particular entity would be skipped from the operation.
2. <lithium> tag - This tag contains Khoros community user profile field details.
   • <field-name> - This tag contains a community field name whose data is synched with Salesforce against the corresponding Salesforce field.
   • <default-value> - This value can be used if Salesforce declares the field as mandatory and there is no value for that field in Khoros.
   • <hardcoded-value> - This value overrides other data against the community field and would be synced with Salesforce (This may be a special case when you strictly want a specific value against any particular field).

Here is the response to the GraphQL request.

{
  "data": {
    "settingsInput": {
      "result": true,
      "errors": null
    }
  }
}

Retrieve the custom fields

You can retrieve the user synchronization custom fields using the below query.

{
  community {
    communitySalesforceSettings {
      canSet {
        failureReason {
          message
        }
      }
      userSyncCustomField {
        key
        value
      }
    }
  }
}

Here is the response to the GraphQL query.

{
  "data": {
    "community": {
      "communitySalesforceSettings": {
        "canSet": {
          "failureReason": null
        },
        "userSyncCustomField": {
          "key": "salesforce.user_sync_custom_field",
          "value": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<mappings type=\"users\">\n    <!-- Mapping for single field -->\n    <mapping>\n        <crm> <!-- Salesforce field details -->\n            <field-name>User_Biography__c</field-name> <!-- Salesforce field API name -->\n        </crm>\n        <lithium> <!-- Lithium field details -->\n            <field-name>profile.biography</field-name> <!-- Lithium field name -->\n        </lithium>\n    </mapping>\n    <!-- Mapping for single field ends-->\n    <!-- We can add mappings for multiple fields like as above-->\n</mappings>"
        }
      }
    }
  }
}