Custom Attributes on Data Hub Schema Definitions

Custom Attributes

Review the following table to understand custom attributes on Data Hub schema definitions.

Attribute Name Applicable To Description Supported options Behavior when not set
sourceIdType Defined once at the root of the schema Analytics needs to know the type of the IDs used in Data Hub. uuid, base62, or integer Assumed to be integer
label Any field Analytics and ATS uses this as the default user-facing label when displaying data from the field.   If not set, a best effort ismade to create a user friendly label from the field name.

For example: interviewOutcome => Interview Outcome.
isPercent Any fields with a type of number

To identify a number as a percentage for display purposes.

 

For example, 0.5 displays as 50%.

 true or false Number is rendered as is.
isMonetary Any fields with a type of number

To identify a number field as being a monetary value.

 

A monetary value requires a currency code, see currencyField, isCurrencyField and isDefaultCurrency attributes for the rules around how this is chosen.

 true and false Required, otherwise the field is interpreted as a plain number.
currencyField Any fields with the isMonetary attribute This defines which other field in the payload contains the currency code to use.

Any valid ISO currency code.

 

For more details: Currency Encyclopedia

A fallback currency code for the monetary field is found by looking for any field marked as isDefaultCurrency.

 

If no field is found then it looks for the alphabetically first field with the isCurrencyField attribute.

 

If no field is found then Analytics uses the currency set on the root group for the customer.
isDefaultCurrency A single field with the isCurrencyField attribute This defines the default currency field to be used as a fallback for any monetary fields that do not specify a currencyField attribute. true or false With no default currency field set Data Hub looks for the alphabetically first field with the isCurrencyField attribute.
isCurrencyField Any fields containing an ISO currency code Identifies a field as a valid ISO currency value. true or false If not set, this field is treated as normal text with no currency validation or usage as a currency for monetary fields.
isOwner A single field containing a CorporateUser ID This defines the overall owner of the record. Any valid CorporateUser ID for the customer If not set, then the alphabetically first field with a link attribute pointing to CorporateUser is assumed as the owner.

isType

Up to eight fields that need to be indexed for fast filtering in Analytics

This defines fields that should be indexed for fast filtering in Analytics.

 

Any field with this attribute must have fewer than 10,000 unique values. For example, “Deal Status” is good because the likely unique values are “Closed-Won, Closed-Lost, Open, Archived”. Whereas “Candidate Name” is bad because the number of unique values is approximately equal to the number of records sent to Data Hub.

true or false

If not set, then data is still filterable in Analytics but metrics may run slower.

link

Any field containing IDs linking to other ATS or Data Hub entities

Defines the entity to which the link is pointing.

Example for a link to an ATS entity:

Copy 
{
  type: “ATS”,
  entity: “Candidate”
}

Example for a link to a Data Hub entity:

Copy 
{
  type: “DATA_HUB”,
  sourceSystem: “Automation”,
  entityType: “SurveySubmittal”
}

If not set, then this field is treated as a normal data field, neither Analytics nor ATS will recognize it as a link to another entity.

applyToContractOnDate

Any Bullhorn placement ID field

This attribute tells Analytics to assign the data hub record to the correct original/extension based on the date field. This is necessary for customers who use change requests for extensions.

Any other date field in the payload:

applyToContractOnDate: “dateCompleted”

Record is linked to the original placement in Analytics.

Example Schemas

Kitchen Sink

  • Defines status as isType for fast filtering in Analytics. This is acceptable because status does nothave a large number of unique values.
  • Uses the format of date-time for the paid_on field to indicate it should be treated as a date field instead of a normal string.
  • Defines retainer_fee as a monetary field with isMonetary and an explicit currency field of retainer_currency.
  • Defines extras_fee and total_fee as monetary fields without explicit currency fields, they will fall back to currency because it’s marked with isDefaultCurrency.
  • Links to the candidate entity in ATS with candidateId.
  • Links to a user entity in ATS with userId and has it marked with isOwner so that Analytics sees this as the overall owner of the record.
  • Links to another Data Hub entity with automationSurveyId, an Automation Survey Submittal.
Copy 
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "sourceIdType": "uuid",
    "properties": {
        "status": {
            "type": "string",
            "isType": true,
            "label": "Status"
        },
        "paid_on": {
            "type": "string",
            "format": "date-time",
            "label": "Paid On"
        },
        "retainer_fee": {
            "type": "number",
            "isMonetary": true,
            "currencyField": "retainer_currency",
            "label": "Retainer Fee"
        },
        "retainer_currency": {
            "type": "string",
            "isCurrencyField": true,
            "label": "Retainer Currency"
        },
        "extras_fee": {
            "type": "number",
            "isMonetary": true,
            "label": "Extras Fee"
        },
        "total_fee": {
            "type": "number",
            "isMonetary": true,
            "label": "Total Fee"
        },
        "currency": {
            "type": "string",
            "isCurrencyField": true,
            "isDefaultCurrency": true,
            "label": "Currency"
        },
        "candidateId": {
            "type": "integer",
            "label": "Candidate",
            "promoteTo": "candidateId",
            "link": {
                "type": "ATS",
                "entity": "Candidate"
            }
        },
        "userId": {
            "type": "integer",
            "isOwner": true,
            "label": "Owner",
            "promoteTo": "corporateUserId",
            "link": {
                "type": "ATS",
                "entity": "CorporateUser"
            }
        },
        "automationSurveyId": {
            "type": "integer",
            "label": "Automation Survey",
            "link": {
                "type": "DATA_HUB",
                "sourceSystem": "Automation",
                "entityType": "SurveySubmittal"
            }
        }
    }
}