Skip to main content

Crm Field Configuration

This package contains functions for retrieving and updating CRM Fields and CRM Fields Mappings data.

CRM Field Configuration​

Types: CrmObjectType and SalesloftObjectType​

Important types to know about are the difference amongst CRM Object Type and Salesloft Object Type.

Salesloft Object Type's fields can be mapped to one or more CRM Object Type's fields. People can have mappings to both a Lead and a Contact, while Account and Opportunity can only be mapped to Account and Opportunity fields respectively.

Getting CRM Fields​

This function or hook retrieves a list of CRM Fields for the appropiate CRM Object Type. These CRM Fields are used to be mapped to the appropiate standard or custom fields.

Please refer to the Glossary for what CRM Fields can contain.

import {
  getCrmFields
} from '@shared/crm-field-configuration'

async function myFunction() {
  const leadCrmFields = await getCrmFields('Lead')
  const contactCrmFields = await getCrmFields('Contact')
}

As a React Hook:

import React  from 'react'
import {
  useCrmFieldsQuery,
  useCrmFieldsQueries
} from '@shared/crm-field-configuration'
import { QueryClientProvider } from '@rhapsody/query-client'

export const MyComponent = (props) => {
  const { data, isInitialLoading, error } = useCrmFieldsQuery('Account', { updatableOnly: false, throwIfNotOk: false, enabled: true })
  // useCrmFieldsQueries is used to retireve crm fields for multiple CRM Object Types
  const { data: peopleCrmFields, isInitialLoad: arePeopleCrmFieldsLoading, error } = useCrmFieldsQueries({crmObjectTypes: ['Contact', 'Lead']})
  return <h1>Hello</h1>
}

export const FieldsConfiguration = (props) => {
  return (
    <QueryClientProvider>
      <MyComponent />
    </QueryClientProvider>
  )
}

useCrmFieldsQuery has configurable options built in already that allow you have have all or only updateable only CRM Fields, handling errors, and preventing fetching data if it dependent on another piece of data.

useCrmFieldsQueries is used to retrieve CRM fields for more than one CRM Object Type and will return an array of query data instead of one. Ideally this is used for People SL Object Type because it holds two CRM Object Types; Lead and Contact. This hook has the configuration as useCrmFieldsQuery with two additional arguments: canFetchCrmFields and canFetchLeadCrmFields to determine if we want to enable the query (canFetchCrmFields) and to determine if we want to fetch Lead CRM Fields. This only occurs on Hubspot CRM teams.

  • updatableOnly CRM Fields are those that have a pre-set direction (or authority) on inbound fields (Salesloft <- CRM). This is defaulted to false in order to retrieve all CRM Fields.
  • throwIfNotOk handles errors more elegantly in order to return proper information from error. This is defaulted to false.
  • enabled allows you to refrain from fetching crm fields but the default is set true unless told otherwise.

Getting mappings​

This function or hook returns the list of mappings of each Salesloft Object Type.

import {
  getCrmFieldsMappings
} from '@shared/crm-field-configuration'

async function myFunction() {
  const peopleMappings = await getCrmFieldsMappings('People')
}

As a React Hook:

import {
  useCrmFieldsMappings
} from '@shared/crm-field-configuration'

export const MyComponent = () => {
  const { data: mappings, isLoading } = useCrmFieldsMappings('Account')
  return mappings.map((mapping) => <p>{mapping.id}</p>)
}

export const FieldsConfiguration = () => {
  return (
    <QueryClientProvider>
      <MyComponent />
    </QueryClientProvider>
  )
}

Getting enriched mappings​

This hook returns the list of mappings of each Salesloft Object Type while enriching data that can sometimes end up missing when a SL Field that has a mapping has a missing crm field data. This hook goes through an extra step in order to fill those missing gaps by providing the required CRM Fields for each CRM Object Type.

As a React Hook:

import {
  useCrmFieldsMappings
} from '@shared/crm-field-configuration'

export const MyComponent = () => {
  const { data: accountCrmFields, isInitialLoading: isAccountCrmFieldsLoading } = useCrmFieldsQuery('Account')
  const { data: mappings, isInitialLoading } = useCrmFieldsWithMappings({objectType: 'Account', crmFieldsList: accountCrmFields, enabled: true})
  return mappings.map((mapping) => <p>{mapping.id}</p>)
}

export const FieldsConfiguration = () => {
  return (
    <QueryClientProvider>
      <MyComponent />
    </QueryClientProvider>
  )
}

Creating a Salesloft Custom Field​

The process to creating a Salesloft custom field requires a Salesloft field label and its intended value type first. The response from the function provides a parameterized version of the field label in order to create a mapping (next section). Standard fields already have a paramterized version of their field label.

If you are creating a custom field for Account or Opportunity, you need to provide field_type key in the payload. Account needs to be replaced as company. The field_type need to be lowercase.

CRM Object Typefield_type
Accountcompany
Peopleperson
Opportunityopportunity

You will need a field_type, name and value_type, which can either be date, text, or picklist.

import {
  createCustomField
} from '@shared/crm-field-configuration'

async function myFunction(currentField) {
  const customFieldResponse = await createCustomField({
    field_type:
      crmObjectType === 'Account' ? 'company' : crmObjectType.toLowerCase(),
    name: currentField.field_label,
    value_type: currentField.value_type,
  })
}

Creating or Updating a mapping​

To update a mapping or attach a mapping to a custom field newly created, you need the Salesloft Object Type and mapping information that is being created or updated as either the CrmFieldMappings or CrmFieldPeopleMappings type.

import {
  createUpdateCrmFieldMapping
} from '@shared/crm-field-configuration'

async function myFunction(currentField) {
  const accountResponse = await createUpdateCrmFieldMapping('Account', {
    field_label: currentField.field_label,
    value_type: currentField.value_type,
    field: customFieldResponse.parameterized,
    ...currentField.crm_object_type_mappings[crmObjectType],
  })
  
  // ..or for People we need to send back contact and/or lead mapping information

  const peopleResponse = await createUpdateCrmFieldMapping('People', {
    field_label: currentField.field_label,
    value_type: currentField.value_type,
    field: customFieldResponse.parameterized,
    contact: {},
    lead: {},
  })
}

Deleting a custom field​

To remove a custom field from the list of fields created among a Salesloft Object Type, you need to pass the Salesloft custom field id.

import {
  deleteCrmCustomField
} from '@shared/crm-field-configuration'

async function myFunction(field) {
  await deleteCrmCustomField(field.custom_field_id)
}

Deleting a mapping​

Deleting a mapping is known as clearing. To remove a mapping from a standard or custom field, you need the Salesloft Object Type, CRM Field and CRM Field Label,which are values available if a CRM Field has been mapped.

import {
  deleteCrmFieldMapping
} from '@shared/crm-field-configuration'

async function myFunction(field) {
  await deleteCrmFieldMapping(
    'People',
    field.mapping.field,
    field.mapping.field_label
  )
}

Custom Field Options​

A custom field's options can also be known as the picklist values. Those values come along as field_options when retrieveing mappings in getCrmFieldMappings or useCrmFieldMappings for each field, if the field has a value type of picklist. You have two functions available to you, to update the options or check their usage.

To update the list of options from either removing, replacing, deactivating, or activating you need the id of the custom field, the list of options in an arranged format, and the list of replacements. Please refer to available types to verify format required.

import {
  updateCrmCustomFieldOptions
} from '@shared/crm-field-configuration'

async function myFunction(
  custom_field_id: number, 
  options: CrmCustomFieldOption[], 
  replacements: CrmCustomFieldOptionReplacement[]
  ) {
    await updateCrmCustomFieldOptions({
      custom_field_id,
      custom_field_options,
      replacements,
    })
}

When a user tries to remove or replace an option, we need to check the usage of option for example in Automation Rules

import {
  checkCrmCustomFieldOptionUsage
} from '@shared/crm-field-configuration'

async function myFunction(option) {
  const { custom_field_id, id } = option
  const response = await checkCrmCustomFieldOptionUsage(
    custom_field_id,
    id
  )
  return response
}

Standard Field Options vs Custom Field Options​

At the moment there are standard fields that are considered to have the value_type as picklist but these are not custom fields. Account Tier is the only one for now that has options that can be edited.

A custom field and it's options can be removed while a standard one can only have it's options edited.

You CANNOT retrieve a standard field's options through getCrmFieldsMappings or useCrmFieldsMappings. You must use useStandardPicklistData

import {
  useStandardPicklistData
} from '@shared/crm-field-configuration'

export const MyComponent = (salesloftFieldName) => {
  const { data: standardPicklistData, isLoading: standardPicklistDataLoading } =
    useStandardPicklistData(salesloftFieldName)
}

export const FieldsConfiguration = () => {
  return (
    <QueryClientProvider>
      <MyComponent />
    </QueryClientProvider>
  )
}

Import Requirements​

To understand the services for handling Import Requirements warning when attempting to clear a mapping, please refer to README.md within this package

If you're outside of Github please refer to this link.

Glossary​

  • Salesloft standard field - these are properities of Salesloft Object Types that are always present. Most standard fields cannot change their properties, but there are a few special cases that can. Example: Stage

    • All standard fields can be mapped to one or more CRM Fields.

  • Salesloft custom field - user defined Salesloft fields that include metadata about the field. Refer to type CustomField.

  • Salesloft field - an object that contains the metadata for a field in Salesloft. Can be a standard or custom field. Refer to the type SalesloftField in CrmFieldMappings

  • Salesloft field label - the displayable version of the name of the Salesloft Field Name.

  • Salesloft field name - In the code this is refered to as just field. This is similiar to the Salesloft Field API Name. It is a parameterized version of the Salesloft Field Label, it is used as the unique identifier for each standard or custom field to be accessed individually to edit the field.

    • example: Salesloft field label: new field and Salesloft field name: new_field
    • When creating a custom field, a user can create the Salesloft field label also known as name in the payload and the Salesloft field name is part of the object returned response also known as the parameterized value.
    • When updating a standard field or custom field, the Salesloft field label is known as field_label and the Salesloft field name is referred to as field in the payload.

  • Salesloft value type - is the type of the Salesloft Field. It can be text, date, or picklist.

  • mapping - The definition of the rules connecting a Salesloft Field to a CRM Field which includes the direction the data can flow between the systems as well as the authority that defines which systems data to prefer when theres a conflict (also known Data Reconcile). Refer to type CrmFieldMappings

  • CRM Field - an object that contains the metadata for a field in the CRM. Refer to the type CrmField to see what it can contain.

    • picklistValues and options are considered the same values. Please use options, picklistValues are deprecated.
    • The error key is return upon only if the user's personal connection is not connected and considered to be outside of the model from data retrieved from the CRM but returned from the server as indication on why the metadata could not be retreieved from the CRM.