Integration Field Mapping — How Velaro Reads Your CRM Schema

This guide explains how Velaro's bots and AI tools read fields from your connected CRM or ERP (NetSuite, Dynamics 365, Salesforce, HubSpot, SAP, ServiceNow, Accela) — and from Velaro's own native CRM (contacts, deals, companies). It covers custom fields, when you need to resync, and when (if ever) you need to write a prompt instead of letting Velaro handle it automatically.

---

The short version

When you connect a CRM, Velaro automatically reads the actual schema of your account — every field, including your custom ones. The bot then only asks for fields that exist on your org, and never tries to read a field you don't have. If you add a brand-new custom field, you can either wait up to 24 hours for it to refresh automatically, or click Resync fields to pick it up immediately.

You almost never need to write prompts about your fields. Velaro handles it.

---

How it works (one diagram in words)

Customer connects integration
        ↓
Velaro calls the CRM's "describe my schema" endpoint
(NetSuite metadata-catalog, Salesforce describe, Dynamics EntityDefinitions, etc.)
        ↓
Schema is saved per-account (24h cache, auto-refresh)
        ↓
You map the fields you want the bot to use (admin → Field Mapping tab)
        ↓
Every bot skill (search, get, create, update) reads from your mapping
        ↓
Bot never sends a field your account doesn't have
Bot always knows which fields are required, so it asks for them

---

Why this is great (marketing language)

• Every customer's CRM is different — Velaro adapts to yours automatically. No engineering required. We discover your schema, including every custom field you've added.
• Custom fields work out of the box. Add a field in NetSuite or Salesforce, and the bot can read or write it after a 24h refresh — or instantly if you click Resync.
• The bot only asks for what's actually required on your account. If your NetSuite org marks email as required for creating a customer, the bot asks for the email before submitting. If your org doesn't require email, it doesn't ask. No hardcoded assumptions.
• No silent failures. If a field disappears from your CRM, Velaro tells the admin in the activity log instead of pretending the data isn't there.
• One pattern across every integration. NetSuite, Dynamics, Salesforce, HubSpot, SAP, ServiceNow, Accela — all use the same field-mapping system. Same admin UI, same behavior, same resync button.

---

When you need to resync

99% of the time you don't — the schema refreshes itself every 24 hours.

You should click Resync fields (or ask Moshky "resync my NetSuite fields") when:

• You just added a custom field in your CRM and want the bot to see it right now.
• You renamed or deleted a field in your CRM (the bot will keep trying the old name until the next refresh).
• The activity log says "field 'X' is not available on this org and was skipped" — that means the bot tried to read a field your account doesn't have. Either remove it from the mapping, or resync if you just added it.

How to resync

Admin UI: Settings → Integrations → (your integration) → Field Mapping tab → click Resync fields for the entity you changed (customers, contacts, cases, etc.).

Through Moshky / agent chat: "Resync my NetSuite fields for customers." Moshky calls the velaro_resync_integration_fields skill on your behalf.

Programmatically: POST /integration-field-mapper/{integration}/{entityType}/resync.

---

Are all integrations equal?

Yes, for the field-mapper layer — every supported CRM/ERP goes through the same flow:

Integration	Schema discovery endpoint	Custom fields	Resync button
NetSuite	metadata-catalog	✅	✅
Dynamics 365	EntityDefinitions/Attributes	✅	✅
Salesforce	sobjects/{Object}/describe	✅	✅
HubSpot	crm/v3/properties/{object}	✅	✅
SAP S/4HANA	service metadata	✅	✅
ServiceNow	sys_dictionary	✅	✅
Accela	record-type describe	✅	✅
Velaro CRM (native)	local DB + admin-defined custom fields	✅	✅

What varies is the list of operations each integration supports (e.g. NetSuite can create RMAs, HubSpot can't). That's the integration's own capability, not the field-mapper.

---

When do I need to write a prompt in the AI node?

Almost never for field discovery. The bot already knows your schema. Don't waste tokens describing fields the system already discovered.

You DO write a prompt when:

1. Business-specific behavior — "If a customer's tier is Enterprise, escalate immediately to a human." That's policy, not field discovery.

2. Choosing between multiple matching records — "If you find more than one customer matching the email, ask which company they're with." Logic, not schema.

3. Tone and persona — "Always sign off as Sarah from Acme Support."

4. Restricting which fields to use — "Don't reveal the internal score field to the customer." Policy on top of the mapping.

You do NOT write a prompt for:

• "The customer table has a field called account_tier" — the bot already knows.
• "When creating a lead, the email field is required" — the bot reads that from metadata.
• "Don't ask for phone because we don't use it" — turn it off in Field Mapping instead.

Rule of thumb: describe behavior in prompts, not data structure. The data structure is already known.

---

How to test it works on your account

1. Open the Field Mapping tab for your integration (e.g. Settings → Integrations → NetSuite → Field Mapping → Customer).

2. Confirm your custom fields appear in the list. If they don't, click Resync.

3. In a test chat, ask the bot to look up a real customer who has values in your custom fields. Confirm the response includes those values.

4. Add a brand-new custom field in your CRM, click Resync, then test the lookup again — the new field should now be returned.

5. Try to create a record with a field missing (e.g. "Create a customer named Acme") — the bot should ask you for any missing required fields before submitting, not after.

If any of those don't work, the activity log on the integration page will tell you why.

---

What if Velaro tries to read a field that doesn't exist on my account?

There's a safety net underneath the field mapper. If a field somehow slips through (e.g. it was deleted between yesterday's schema refresh and right now), Velaro catches the error, removes that one field from the query, retries, and writes an entry in the activity log so the admin sees it. Your customer never sees a broken response — the bot just returns the other fields.

This is a fallback, not the primary mechanism. If you ever see repeated "field X not available" entries in the activity log, click Resync — your schema is out of date.

---

Common questions

Q: I just connected a fresh CRM. Do I need to do anything?

A: No. Velaro pulls your schema on connect. Open the Field Mapping tab if you want to review what was found.

Q: I have 50 custom fields. Do I need to map all of them?

A: No. Only map the ones you want the bot to use. The rest are discovered but ignored.

Q: What happens if my custom field has special characters or a really long name?

A: It's stored exactly as your CRM exposes it. The field label in Velaro matches the label in your CRM.

Q: Can the bot create or update a custom field's value?

A: Yes, if the field is marked writable in your CRM and you've mapped it on the Create/Update side of the Field Mapping tab.

Q: Do I need to do anything when my CRM admin renames a field?

A: Click Resync after the rename. Existing mappings to the old name will be flagged in the activity log as missing.

Q: How often does the schema refresh on its own?

A: Every 24 hours, lazily — meaning the next request that needs the schema triggers the refresh in the background. You won't notice; the request still completes against the previous snapshot.

---

Related guides

• [Integrations Guide](/article/integrations-guide) — overview of all supported integrations
• [Bots & AI Guide](/article/bots-ai-guide) — how the bot uses your CRM data in conversations
• [Custom Fields Guide](/article/custom-fields-guide) — Velaro's own custom contact fields (different system; used for data Velaro collects, not data your CRM holds)
• [Integration Troubleshooting](/article/integration-troubleshooting-guide) — error patterns and what they mean