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 |
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
If no field is found then it looks for the alphabetically first field with the
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
Example for a link to a Data Hub entity: Copy
|
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:
|
Record is linked to the original placement in Analytics. |
Example Schemas
Kitchen Sink
- Defines
status
asisType
for fast filtering in Analytics. This is acceptable becausestatus
does nothave a large number of unique values. - Uses the
format
ofdate-time
for thepaid_on
field to indicate it should be treated as a date field instead of a normal string. - Defines
retainer_fee
as a monetary field withisMonetary
and an explicit currency field ofretainer_currency
. - Defines
extras_fee
andtotal_fee
as monetary fields without explicit currency fields, they will fall back tocurrency
because it’s marked withisDefaultCurrency
. - Links to the candidate entity in ATS with
candidateId
. - Links to a user entity in ATS with
userId
and has it marked withisOwner
so that Analytics sees this as the overall owner of the record. - Links to another Data Hub entity with
automationSurveyId
, an Automation Survey Submittal.
{
"$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"
}
}
}
}