Field configuration & data mapping
Getting and reading the field-config
Every use case and solution field — built-in or custom — is described by a field-config record with:
| Property | Meaning |
|---|---|
key | The exact string to use in custom_fields when reading or writing. |
type | One of: dropdown, dropdown-multiselect, input, textarea, searchable-text, scoring-rubric, calculated, and others. |
dropDownOptions.options[] | For dropdown types: the list of valid {key, value, csvKey} entries. value is the display label a human sees; key is what you send in the API. |
If you’re integrating via the MCP server, ask for “the field definitions” or “what are the valid options for the <field> dropdown” and the server will return this directly (see MCP server) — this is the fastest way to get a live, authoritative list without a separate REST call.
Mapping checklist (do this before your first write)
Map every source field to its option key
Map every source field to its AlignAI option key (not label) for each dropdown.
Confirm every key exists in the current field-config
Confirm every key you plan to write actually exists in the current field-config — don’t assume a key from documentation or a prior environment is still valid.
Get missing fields added before go-live
If your source system needs a new field that doesn’t exist yet in AlignAI, get it added to the field-config before your pipeline goes live — writing to a nonexistent key is accepted silently and just creates junk (see Writing data).
Decide date and URL formatting up front
Decide your date and URL formatting up front (see Writing data) — get this wrong in a bulk load and you’ll be re-running the whole batch.
Field keys can differ between production and QA. Don’t assume a field key that works in QA will work unchanged in production — pull the field-config for each environment separately and reconcile the differences before you go live.
Reference example: model-output → AlignAI field mapping
This is the shape used by AlignAI’s own reference ML pipeline integration, useful as a template if you’re pushing data from an AI-generated triage/scoring pipeline into AlignAI:
Passed through directly:
source_id ← your idea_id; name ← your idea_name; plus problem/opportunity description, status, theme, and timestamps, all written into custom_fields.
Model-generated fields:
Quality scores (grammar, complexity, clarity, convincing, informative, objectivity), unbiased_final_score_ratio, idea_summary, solution_type, tags, problem_or_solution, bert_topic, is_duplicate, duplicate_count, duplicates_json.
Governance / human-review fields:
duplicateDecision, duplicateReviewNote, pipeline_run_date.
Use this as a starting template, but always validate the actual key names against your environment’s live field-config — custom fields and their keys vary by AlignAI tenant.