> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CRM field mapping

> Choose which Alguna values are written onto HubSpot and Salesforce records, from deal totals to subscription line items

Field mapping decides which Alguna values are written onto records in your CRM. Use it to put a quote's MRR, ARR, contract dates, and signer on the deal, to keep a subscription record up to date, or to send each subscription product to a line item. It works the same way for [HubSpot](/docs/integrations/crm/hubspot) and [Salesforce](/docs/integrations/crm/salesforce). The objects involved are described in [How Alguna works](/docs/concepts/how-alguna-works).

Values flow one way, from Alguna to your CRM, so Alguna is the source of truth for every field you map. Field mapping is configured in the dashboard. There's no public API for it.

## For admins

### Open field mappings

Go to **Settings → Connections → Integrations → CRM** and open the **Field mappings** tab. You need the **Integration manage** permission to make changes.

The cards across the top show each mapped object, how many mappings it has, and which Alguna record it's written from. A green dot means the object is enabled and has mappings.

If more than one CRM is connected, choose a **Default CRM** on the **Settings** tab first. Alguna maps fields onto that CRM.

### Map fields onto deals

Every CRM connection comes with a deal object: **Deal** in HubSpot, **Opportunity** in Salesforce. Alguna fills it from the deal's primary quote. See [how quotes and deals are linked](/docs/integrations/crm/hubspot#how-quotes-and-deals-are-linked).

<Steps>
  <Step title="Select the deal object">
    Click the **Deal** or **Opportunity** card.
  </Step>

  <Step title="Add a mapping">
    Click **Add mapping**. On the left, select the Alguna field, such as **ARR** or **Contract start date**. On the right, select the CRM field it should fill.
  </Step>

  <Step title="Save">
    Add as many mappings as you need, then click **Save field mappings**. Changes apply once you save.
  </Step>
</Steps>

The deal object can't be deleted or disabled. You can turn off **Write automatically** if you'd rather update deals only on demand.

### Map another object

You can also write Alguna data onto other CRM objects:

* **HubSpot:** companies, contacts, tickets, quotes, line items, products, and custom objects
* **Salesforce:** any standard or custom object the connected Salesforce user can read, create, and update, such as Account or Contract

<Steps>
  <Step title="Add the object">
    Click **Map an object**. Choose the **Alguna record** the data comes from and the **CRM object** it should be written to.
  </Step>

  <Step title="Set a parent for child records">
    Phase item and phase item tier records sit under a parent. Choose the **Parent mapped object**, then name the link between them. In HubSpot, that's an association label. If no association with that name exists yet, Alguna creates it in HubSpot when you save. In Salesforce, choose the lookup field on the child object that points to the parent object.
  </Step>

  <Step title="Add field mappings">
    Click **Add**, then map fields as you would for deals.
  </Step>
</Steps>

The Alguna record you choose decides which fields you can map and when the record is written:

| Alguna record | One CRM record per | When it's written |
| - | - | - |
| Quote | Quote | Only by an automation, such as the **Create CRM Record** action |
| Subscription | Subscription | On every change, once the subscription is active |
| Phase item | Product on a subscription. Its parent must be a Subscription object. | With its subscription |
| Phase item tier | Pricing tier on a product. Its parent must be a Phase item object. | With its phase item |

A *phase* is a period of a subscription with its own pricing, and a *phase item* is one product in that phase. To send subscription products to HubSpot line items, map a **Phase item** record onto **line\_items**, with your subscription object as its parent. In Salesforce, map it onto a custom object for subscription lines that has a lookup field to your subscription object.

Alguna creates these records the first time it writes them and updates the same records after that. When a product or tier is removed from a subscription, Alguna deletes its record from the CRM. Subscriptions that are still being negotiated, such as drafts or sent quotes, aren't written until they're active.

<Note>
  In HubSpot, Alguna needs read access to your custom object schemas to list custom objects. If you connected HubSpot before this was available and only see standard objects, reconnect HubSpot. In Salesforce, formula and other calculated fields aren't offered, because they can't be written.
</Note>

### Salesforce: moving from the Alguna custom fields

The [Alguna custom fields](/docs/integrations/crm/salesforce#alguna-custom-fields) on the Salesforce Account are written by the subscription sync in [External sync](/docs/integrations/external-sync). Field mapping replaces it with records and fields you choose. You can't enable a **Subscription** mapped object on an integration while that subscription sync is still set up, so remove the subscription configuration from External sync first, then map the values you need. Contact `support@alguna.io` if you'd like help moving over.

### Use a formula

Click **fx** on a mapping row to write a calculated value instead of a single field. Click it again to go back to a single field.

| Formula | Writes |
| - | - |
| `arr * 0.1` | 10% of the deal's ARR |
| `product_arr("prod_a", "prod_b")` | The ARR from the lines selling those products |
| `product_mrr("prod_a")` | The MRR from the lines selling that product |
| `arr - product_arr("prod_a")` | ARR from everything except one product |
| `product_count()` | How many distinct products the deal sells |
| `tier(1, "rate")` | The rate of the first pricing tier. Phase item objects only. |
| `overage_tier(1, "rate")` | The rate of the first overage tier. Phase item objects only. |

Formulas can use `mrr`, `arr`, and `acv`, the operators `+ - * / %`, and parentheses. Pass product IDs to `product_arr()` and `product_mrr()`. With no arguments, they cover the whole deal. `tier()` and `overage_tier()` accept `rate`, `min_units`, `max_units`, `fixed_fee`, and `percentage`.

Worth knowing:

* A product the deal doesn't sell counts as zero instead of causing an error, so an out-of-date product ID quietly lowers the result
* `product_arr()` can be less than `arr`, because contract-level adjustments such as minimum spend, ramps, and contract discounts don't belong to any single product
* Tier positions start at 1. If you ask for a tier that doesn't exist, the field is left empty instead of being set to zero.

Click **How formulas work** in the editor for the full reference.

### Match field types

Map each Alguna field onto a CRM field of a compatible type:

| Alguna field type | CRM field types |
| - | - |
| Text | Text, picklist |
| Date | Date, date and time |
| Currency | Currency, number |
| Number | Number |
| Yes/no | Checkbox |
| Reference (an ID) | Reference, text |
| Formula | Currency, number |

Alguna only lists CRM fields it can write to. Each CRM field can be mapped only once.

### When values are written

**Deals and opportunities** are written:

* Whenever the primary quote changes
* When the quote's subscription changes, while the quote is a draft, pending approval, or sent
* When the quote is signed

Alguna only writes to deals that already have a linked quote. It never creates deals from field mapping.

**Subscription, phase item, and phase item tier records** are written whenever an active subscription changes.

Alguna only sends a value when it has changed since the last write. If a write fails, Alguna retries it automatically.

### Write automatically

When **Write automatically** is on, Alguna writes the object whenever its source changes. When it's off, Alguna only writes the object when you click **Sync now** on a quote's deal card or when an automation does it. Objects under a parent follow the parent's setting.

### Empty values

When there's no value to send, for example because a deal has no primary quote, Alguna clears the CRM field so it never shows an out-of-date number. Yes/no fields are set to *no* instead of being cleared. Dates are written as `YYYY-MM-DD`.

### Required fields

If a CRM object requires fields to be filled in when a record is created, Alguna shows a warning listing them. You can still save, because a workflow in your CRM, such as a HubSpot workflow or a Salesforce flow, might fill them in. If nothing does, new records will fail to sync, so map each required field or choose one as the parent link.

### Turn off, remove, or delete

* The **Enabled** switch turns an object on or off without losing its mappings. Each mapping row also has its own active switch.
* Removing a mapping stops Alguna updating that field. It doesn't clear the value already in your CRM.
* **Delete object** removes the object, its mappings, and every object under it. This can't be undone.

### Fields you can map

The fields on offer depend on the object's Alguna record.

| Group | Fields | Available on |
| - | - | - |
| Quote | Quote ID, Quote name, Quote status, Quote kind, Quote link, Quote expiry, Quote signed at, Contract start date, Contract end date, Billing start date, Signer name, Signer email | Quote |
| Customer | Customer ID, Customer name, Customer CRM ID | Quote, Subscription, Phase item |
| Revenue | MRR, ARR, ACV, TCV, Currency | Quote, Subscription, Phase item |
| Subscription | Subscription ID, Subscription name, Subscription status | All |
| Subscription settings | Currency, Plan ID, Plan name, Contract period type, Contract duration (months), Auto-issue invoices, Auto-pay invoices, Invoice payment terms, Auto-renew, Renewal period type, Renewal duration (months), Activated at, Discount type, Discount amount, Discount duration type, Discount duration value | Subscription, Phase item |
| Opportunity | Opportunity CRM ID | Quote, Subscription, Phase item |
| Opportunity | Renewal opportunity name, Expansion opportunity name | Subscription, Phase item |
| Phase | Phase start date, Phase end date | Phase item |
| Phase item | Phase item ID, Product ID, Product name | Phase item, Phase item tier |
| Phase item | Product SKU, Overage SKU, Bundle ID, Bundle name, Pricing model, Pricing model summary, Pricing summary, Billing frequency, Billing interval count, Billing interval unit, Invoice payment terms, Quantity, Unit rate, Unit rate is blended, Total, Percentage, Metered, Overage unit rate, Tier count, Overage tier count, Discount type, Discount amount, Discount duration type, Discount duration value, Phase item MRR, Phase item ARR | Phase item |
| Pricing tier | Tier index (starts at 0), Tier kind, Tier min units, Tier max units, Tier rate, Tier fixed fee, Tier percentage | Phase item tier |

Some values are only available in certain cases:

* Quote, revenue, and subscription values need the CRM record to have a linked quote. A record written from a signed quote always has one.
* Opportunity values need the subscription's primary quote to be linked to a CRM deal or opportunity
* Tier and overage values only exist for tiered prices

### Troubleshooting

| Message | What to do |
| - | - |
| "…a field may only be mapped in one direction" | That CRM field is already mapped. Remove the other mapping first. |
| "…is not available when mapping…" | That Alguna field isn't offered for this object's Alguna record. Check [Fields you can map](#fields-you-can-map). |
| "formula does not compile" | Check the formula against [Use a formula](#use-a-formula) |
| "cannot change a mapped object while enabled field mappings target it" | Turn off the object's mappings before changing it |
| "cannot change a mapped object while an enabled mapped object still parents off it" | Turn off or delete the objects under it first |
| "cannot enable a subscription mapped object while the legacy subscription sync is active for this integration" | Remove the subscription configuration from External sync first. See [moving from the Alguna custom fields](#salesforce-moving-from-the-alguna-custom-fields). |
| "…is not a lookup field on…" | Salesforce only. The parent link must be a lookup field on the child object. |
| "…is not writable on…" | Salesforce only. Choose a lookup field the connected user can edit. |
| "…does not reference…" | Salesforce only. Choose a lookup field that points to the parent object. |
| A required-field warning on an object | Map the required fields, or check that a workflow in your CRM fills them |

## For sales reps

Some fields on your deals and opportunities, such as MRR, ARR, TCV, contract dates, and signer, may be filled in by Alguna. They always reflect the deal's primary quote.

* Don't edit these fields in your CRM. Your change will be replaced the next time the value changes in Alguna.
* If a number looks wrong, check which quote is the deal's primary quote. In HubSpot, it's marked **Primary on this deal** in the **Alguna - Deal Quotes** card. In Salesforce, check the quotes linked to the opportunity in Alguna.
* To change a value, update the quote in Alguna


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.