Purpose

This guide walks you through creating a custom field in Eightfold, mapping data into it, and making it available for search, filters, and analytics dashboards. Use it any time you need to bring a new piece of data — from your ATS, an integration, or a file — into Eightfold as a reusable field.

Before you start

Have this ready before you begin:

• The entity the field belongs to: Position, Candidate, Employee, or Application
• The customer field name and the source field path from your ATS or file
• The data type (string, integer, float, bool, or date)
• Whether the field needs to support search/filter and/or analytics
• A decision on scope: is this field only needed for sync logic, or does it need to be stored in the platform for search, filters, or analytics? If it must be stored and reused, it needs to go through the standard custom field flow in Platform Tools.

Choose your path

Step 1: Map the field through Custom Mapping

The Integration tool is the UI intended for custom_fields_v2 users to fetch and transform custom data and map it to either existing or new custom fields.

How to do it:

1. Go to Custom Mapping under Admin Console > Integration and select the relevant system.
2. Create a new mapping for the entity and map the source field path to custom_info.<field_name> using the appropriate macro.
3. Use Dry Run before saving to confirm the mapping resolves correctly.

Example mapping pattern:

✓ Validate:

• Check the raw JSON to confirm the source field is present.
• Check the entity JSON to confirm the mapped value appears at the expected custom_info.<field_name> path.
• Save the mapping into the integration system advanced configuration only after Dry Run passes.

If the source is CSV instead of API sync:

• The field must already exist in Admin Console before ingestion.
• Use a file named <FILE_GROUP_PREFIX>-CUSTOM-FIELDS-<FILENAME>.csv.
• Use headers in the format <cfType>_<dataType>_<fieldName>, such as efcustom_str_fullname or efcustom_bool_ismanager.
• Make sure the header field name exactly matches the configured custom field key.
• In File Ingestion, select system, entity type, CSV format, and operation, then validate the file before ingesting it.

Step 2: Add transformation logic with CFT (if needed)

CFT is for API-based ingestion. Use it when you need to modify, enrich, or derive values with Python instead of a simple macro mapping.

Where to find it: Admin Console > Integration > Integration Systems > Field Mapping > Custom Field Transformation (CFT)

Use CFT when you need to:

• Derive a new field from one or more existing fields
• Apply conditional logic, such as skip logic or field transformations
• Modify standard entity fields during sync

⚠ Important: If a custom field is only needed for logic during sync, you don't need to create it in Platform Tools. If the value must be stored and reused for filters or other platform behavior, create it through the standard custom field flow.

✓ Validate:

• Add the relevant transform_app_operations entry in ATS config so the transformation runs during sync.
• Use the Dry Run tool to verify the transformed value appears in the output entity dictionary.
• Confirm the transformed field lands in the expected custom_info or entity path before saving the configuration.

Step 3: Create the field in Platform Tools

Create the field in Admin Console > Integrations > Select ATS > Advanced > custom_fields_v2, then verify it under Admin Console > Platform Tools > Custom Fields after it is added.

How to access this screen: Admin Console > Platform Tools > Custom Fields > Manage tab. This opens the field creation form (Data Type, Field Name, Entity Type, and the checkbox list described below).

Create the field with these inputs:

Recommended data paths:

• Candidate / Application / Position: ats_data.custom_info.<field_name>
• Employee: data_json.employee.custom_info.<field_name>
• Calibration-specific position field: profile.custom_info.<field_name>

Analytics and dashboard setup:

• To flow into analytics, the custom field must appear in Admin Console > Platform Tools > Custom Fields and the appropriate Analytics checkbox(es) must be selected on the field definition.
• In the Dashboard Authoring Console, first check whether the field already exists in the dataset powering the analysis.
• If it is not native to the dataset, create the custom field and ensure the relevant Analytics checkbox is selected.

✓ Validate:

• Confirm the field is visible under Platform Tools > Custom Fields.
• Confirm the correct Analytics checkbox(es) are enabled for the surface(s) the field needs to reach (QuickSight/Native Dashboards, Talent Lake/DataHub, or both).

Quick checklist

• Map it through Custom Mapping in the ATS configuration / custom_fields_v2
• Identify entity, field key, data type, and source path
• Create the field in Admin Console > Platform Tools > Custom Fields with the correct data path
• Enable Search / Filter and Analytics only if needed
• Use CFT only if simple mapping is insufficient
• Validate in Dry Run before saving
• For CSV, pre-create the field and use exact header naming
• For analytics, verify the correct Analytics checkbox(es) are enabled for the surface(s) needed

Common mistakes to avoid

• Forgetting to pre-create the field before CSV ingestion
• Forgetting to enable the correct Analytics checkbox(es) when the field is needed in dashboards or reporting
• Ticking only one Analytics checkbox when the field needs to reach both QuickSight/Native Dashboards and Talent Lake/DataHub
• Using CFT for a use case that only needs a straightforward macro mapping