CRM field mapping

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 and Salesforce. The objects involved are described in 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. 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

The Alguna record you choose decides which fields you can map and when the record is written: 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.

​

Salesforce: moving from the Alguna custom fields

The Alguna custom fields on the Salesforce Account are written by the subscription sync in 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. 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 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. 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

​

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