> For the complete documentation index, see [llms.txt](https://docs.rillet.com/EjmEP4KZ9BVp9j2ho4Mh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rillet.com/EjmEP4KZ9BVp9j2ho4Mh/integrations/crm/salesforce-integration/salesforce-custom-object-and-custom-field-mapping-for-rillet-contract-creation.md).

# Salesforce Custom Object & Custom Field Mapping for Rillet Contract Creation

Use **Salesforce** object and field mapping to bring your sales data into **Rillet** as **Rillet Draft Contracts**, **Rillet Customers**, and **Rillet Products**. Select the source objects in **Salesforce**, map their fields to the **Rillet** objects you want created, and decide when records are ready to sync.

### Before You Begin

* Identify the Salesforce objects that hold your agreements and line items.
* Identify the fields you want to import and the conditions that make a record ready for finance to review.
* Have a Rillet default product and your intended sync-from date ready for setup.

### Open Salesforce Setup

Follow these steps to open Salesforce setup:

1. Click your **company logo** in the lower-left corner of the screen.
2. Select **Organization Settings**.

   <figure><img src="https://612265232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNpXFVFZpTQck3vIrjmHB%2Fuploads%2FKLB75oH9oiM82BgW8zYm%2Fimage.png?alt=media&amp;token=fbefe8e2-1ae4-43b9-843b-fb2095266bc0" alt=""><figcaption></figcaption></figure>
3. Go to **Integrations**, then select **Salesforce**.<br>

   <figure><img src="https://612265232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNpXFVFZpTQck3vIrjmHB%2Fuploads%2F1vbcQ6xlsWxy3jkN7bLB%2Fimage.png?alt=media&amp;token=0bcaf119-b655-4d27-a30e-f7dbf1742f43" alt=""><figcaption></figcaption></figure>

The new setup flow then walks you through **Contracts**, **Contract line items**, **Customers**, and **Products**, before finishing with **Trigger and sync**.

### General Principles

Rillet creates one contract per source record, so choose the Salesforce object that best represents an agreement with your customer, such as an Opportunity, Order, or a custom Booking object. This guide uses the default **Opportunity** and **OpportunityLineItem** objects for an annual platform subscription.

Salesforce links these records using **reference fields** (fields that hold another record's ID):

| Record      | Reference field | Points to              |
| ----------- | --------------- | ---------------------- |
| Line item   | `OpportunityId` | Its parent Opportunity |
| Opportunity | `AccountId`     | Its customer Account   |
| Line item   | `Product2Id`    | Its Product            |

{% hint style="info" %} <mark style="color:$info;">**Note:**</mark>

The **Salesforce object** and **Salesforce field** selectors throughout this setup display Salesforce **API names**, which can differ from the labels you see in Salesforce: Opportunity Product uses the API name `OpportunityLineItem`, Product uses `Product2`, and a custom object might use `Booking__c`. Ask your Salesforce administrator to confirm the object and field API names before mapping them.
{% endhint %}

If you use custom objects, your line-item object must likewise link back to the object selected for Contracts. For a field mapping, choose a field on the source record or follow **one lookup** to a related record, such as `Opportunity → Account → Name`.

### Map Your Contracts

Complete these steps to map your Contracts:

1. Open **Contracts** in the setup sidebar.
2. Select the Salesforce object that contains your agreements under **Source object**, choosing from the selector's suggested standard objects and available custom objects.
3. Fill in the **Mandatory** rows under **Field mapping**, including `name`, `amount`, and `close_date`.
4. Select the **Salesforce object** and **Salesforce field** that contain the value to import for each row, using the **Rillet Format** column to check the expected format and example.
5. Map any **Optional** fields you need, such as `currency`, `start_date`, and `end_date`.
6. Click **Continue**.<br>

   <figure><img src="https://612265232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNpXFVFZpTQck3vIrjmHB%2Fuploads%2FunKrCViQjB3PcYM2Rne6%2Fimage.png?alt=media&amp;token=156239bc-1a9e-46a1-8297-996b06b4df29" alt=""><figcaption></figcaption></figure>

{% hint style="info" %} <mark style="color:$info;">**Note:**</mark>

Since **Opportunity** is the default value for **Source object**, its field mappings come prefilled, including `Opportunity.Name` for `name`, `Opportunity.Amount` for `amount`, and `Opportunity.CloseDate` for `close_date`. Review them and complete any additional fields you need.
{% endhint %}

Map your agreement start and end date fields if you need contract term dates.

### Map Your Contract Line Items

Take these steps to map your Contract Line Items:

1. Open **Contract line items**.
2. Select the **Source object** that contains your line items. For this example, select `OpportunityLineItem`.
3. Map the mandatory `quantity` and `unit_price` fields.
4. Add optional mappings where needed, such as `list_price`, `discount_percentage`, `start_date`, and `end_date`.
5. Click **Continue**.

   <figure><img src="https://612265232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNpXFVFZpTQck3vIrjmHB%2Fuploads%2FaVE4ReWiu9fyxobeF5w0%2Fimage.png?alt=media&amp;token=ef4a52fc-2156-4926-8701-d84efc9ccc77" alt=""><figcaption></figcaption></figure>

{% hint style="info" %} <mark style="color:$info;">**Note:**</mark>

Since **OpportunityLineItem** is the default value for **Source object**, its `OpportunityId` field links each line to the Opportunity selected in Contracts, and its field mappings come prefilled, including `OpportunityLineItem.Quantity` for `quantity` and `OpportunityLineItem.UnitPrice` for `unit_price`. For a custom line-item object, use the equivalent reference to your contract source object.
{% endhint %}

Each record from the line-item source becomes a line on the Rillet contract, so map your line-item start and end date fields if individual items have their own service periods.

### Map Your Customers

Use these steps to map your Customers, whose **Source object** is inherited from **Contracts** rather than offered as a separate dropdown:

1. Open **Customers**.
2. Find the `name` row under **Field mapping → Mandatory**.
3. Select the Account referenced by the Opportunity in that row's **Salesforce object** column, shown as `Opportunity.AccountId · Account`.
4. Choose `Name` in **Salesforce field**.
5. Map the optional email, billing address, and shipping address fields you want to import using the relevant source object and field for each row.
6. Click **Continue**.<br>

   <figure><img src="https://612265232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNpXFVFZpTQck3vIrjmHB%2Fuploads%2F4FGpZ1BU6pWLcdeoHaFP%2Fimage.png?alt=media&amp;token=a63a6ac0-4019-468d-acee-65c01110d9a3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %} <mark style="color:$info;">**Note:**</mark>

Rillet matches customers by their Salesforce record, so later syncs fill in fields that are still blank in Rillet without overwriting existing values, except shipping addresses, which are filled only when the customer is created.
{% endhint %}

### Map Your Products

Follow these steps to map your Products, whose **Source object** is inherited from **Contract line items** rather than offered as a separate dropdown:

1. Open **Products**.
2. Review the **Default product** selection.
3. **(Optional):** Use **Always use this product** if your setup should use that product for every imported line item.
4. Find the `name` row under **Field mapping → Mandatory**.
5. Select `OpportunityLineItem.Product2Id · Product2` in **Salesforce object**, and select `Name` in **Salesforce field**.
6. Add optional `description` and `currency` mappings as needed.
7. Review **Include in ARR / MRR** under **Defaults**, which controls inclusion in annual and monthly recurring revenue metrics.
8. Click **Continue** to open **Trigger and sync**.<br>

   <figure><img src="https://612265232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNpXFVFZpTQck3vIrjmHB%2Fuploads%2FvghIeufZhByJSHc0AfjW%2Fimage.png?alt=media&amp;token=85dd5d8e-5c28-4210-ad4a-921685ce4c66" alt=""><figcaption></figcaption></figure>

{% hint style="info" %} <mark style="color:$info;">**Note:**</mark>

Product mappings and defaults apply only when a product is created, so later changes in Salesforce or to these mappings do not update products already imported into Rillet. Edit existing products directly in Rillet instead, or contact Support for a bulk update.
{% endhint %}

### Map Salesforce Picklists to Rillet Custom Fields

Complete these steps to map a Salesforce picklist to a Rillet custom field:

1. Scroll to **Custom fields** in **Contract line items** or **Customers**, and click **Add custom field**.
2. Select the destination **Rillet** custom field.
3. Choose the **Salesforce object**, then the picklist in **Salesforce field**.
4. Review the Salesforce selections and the available Rillet custom-field values with your Rillet representative before starting the sync. This setup maps fields. It does not provide a value-by-value translation table.

This brings Salesforce picklist selections into Rillet custom fields used in accounting. A picklist is a Salesforce field with a predefined set of choices. In the **Contract line items** and **Customers** steps, **Custom fields** are available. They are not available on the **Contracts** header or in the **Products** step of this setup flow.

### Override a Mapping with a Fixed Value

Take these steps to override a mapping with a fixed value:

1. Open the row's **Salesforce field** selector and select **Use a fixed value instead**.

   <figure><img src="https://612265232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNpXFVFZpTQck3vIrjmHB%2Fuploads%2FQqaKehvNsATH9q7QDr9x%2Fimage.png?alt=media&amp;token=c63def9c-2e85-4dee-9150-b15aff2bb4d2" alt=""><figcaption></figcaption></figure>
2. Enter the value in the **Fixed** input, using the expected Rillet format.

   <figure><img src="https://612265232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNpXFVFZpTQck3vIrjmHB%2Fuploads%2F8g8wp3i9j3eKBAjvKtD6%2Fimage.png?alt=media&amp;token=9940c371-3cad-4476-8322-2f4afebf40f0" alt=""><figcaption></figcaption></figure>

Use a fixed value when a Rillet field should have the same value for every record imported through this setup. For example, set the contract line-item `quantity` to `1` when each Salesforce line represents one subscription, so Rillet uses that value instead of reading the Salesforce quantity.

{% hint style="info" %} <mark style="color:$info;">**Note:**</mark>

Fixed values are available in **Contracts**, **Contract line items**, **Customers**, and **Products**, including custom-field rows where supported. The exceptions are customer `name`, product `name`, and line-item `list_price`, which must come from Salesforce.
{% endhint %}

To switch back, select **Use a Salesforce field instead** on the row and choose the source field again. Keep in mind that a fixed value replaces the field mapping rather than acting as a fallback for when Salesforce is blank, so the customer and product update rules described above still apply.

### Set Your Sync Criteria

Use these steps to choose when a Salesforce record is ready to create a draft contract:

1. Review the **Source object** under **Trigger** in **Trigger and sync**.

   <figure><img src="https://612265232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNpXFVFZpTQck3vIrjmHB%2Fuploads%2FTpcuX1ecgGrHwThBVDmS%2Fimage.png?alt=media&amp;token=911ed17c-c0c9-43db-abad-9763779cba3b" alt=""><figcaption></figcaption></figure>
2. Choose **Sync on creation of source object**, or select **On conditions** to set eligibility criteria.
3. Click **Add condition** for conditional syncing.

   <figure><img src="https://612265232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNpXFVFZpTQck3vIrjmHB%2Fuploads%2F2e0OrkmWx46nJu4ObnXp%2Fimage.png?alt=media&amp;token=f4fdb831-2a9a-48fb-9e4a-14d7de2cf009" alt=""><figcaption></figcaption></figure>
4. Choose a field on the contract source object, use the **equals** operator, and select a **Value**.

   <figure><img src="https://612265232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNpXFVFZpTQck3vIrjmHB%2Fuploads%2FBVw3RjaSurqETuOBnzys%2Fimage.png?alt=media&amp;token=a6dffb66-8e1c-4c1a-b279-869b9f295d6c" alt=""><figcaption></figcaption></figure>
5. Review **Sync data from** under **Sync** and choose the date for your setup.
6. Confirm the configuration with your Rillet representative, then use **Save changes** to save it, or **Start Sync** when you are ready to begin syncing.<br>

   <figure><img src="https://612265232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNpXFVFZpTQck3vIrjmHB%2Fuploads%2FZwGdQEGk2rX4zDbbbGDO%2Fimage.png?alt=media&amp;token=160e4d6f-daf3-4a02-984e-b160924352e1" alt=""><figcaption></figcaption></figure>

For an Order-based setup, select `Order` instead of `Opportunity` as your contract source, then choose **Status** as the field, **equals** as the operator, and **Activated** as the value, as shown above. This configuration brings in eligible activated Orders while leaving draft Orders in Salesforce. Since organizations can customize their own status values, use whichever status represents readiness for accounting in your Salesforce workflow.

### Review the Draft Contract

After a qualifying record syncs, review the resulting draft contract in Rillet. Check the contract details, line items, customer, product, and mapped custom-field values against the Salesforce source before completing your contract review, following the general [**Salesforce Integration**](https://docs.rillet.com/EjmEP4KZ9BVp9j2ho4Mh/integrations/crm/salesforce-integration) contract review workflow.

### Frequently Asked Questions (FAQ)

<details>

<summary>How do I get access?</summary>

Contact your Rillet representative, since Early Access is being rolled out individually with assisted setup.

</details>

<details>

<summary>Can I sync invoices, contracts, and customer changes back to Salesforce?</summary>

Syncing invoices, contracts, and customer changes back to Salesforce isn't available in this new version of the integration yet, but it's on the roadmap for a future release.

</details>

<details>

<summary>Can I use a custom Salesforce object instead of an Opportunity?</summary>

You can select an available custom object in the **Source object** selector for Contracts instead of the default Opportunity, and you can also choose a custom source object for Contract line items. Customers inherit the contract source, and Products inherit the line-item source.

</details>

<details>

<summary>Can I map custom Salesforce fields?</summary>

You can select the source object and custom field in the relevant field-mapping row, then check the expected format shown for the Rillet destination field.

</details>

<details>

<summary>Can I map Salesforce fields to Rillet metadata?</summary>

Picklist mapping currently supports Rillet custom fields used in accounting. Metadata mapping isn't supported in this release, but it's planned for a future one.

</details>

### See Also

To learn more about the Salesforce integration and custom fields in **Rillet**, review these articles:

* [**Salesforce Integration**](https://docs.rillet.com/EjmEP4KZ9BVp9j2ho4Mh/integrations/crm/salesforce-integration)
* [**Salesforce Bi-Directional Sync: Invoices, Contracts, and Customers**](https://docs.rillet.com/EjmEP4KZ9BVp9j2ho4Mh/integrations/crm/salesforce-integration/salesforce-bi-directional-sync-invoices-contracts-and-customers)
* [**Salesforce Managed Package Integration Overview**](https://docs.rillet.com/EjmEP4KZ9BVp9j2ho4Mh/integrations/crm/salesforce-integration/salesforce-managed-package-integration-overview)
* [**Fields Overview**](https://docs.rillet.com/EjmEP4KZ9BVp9j2ho4Mh/settings-and-config/custom-fields/fields-overview)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rillet.com/EjmEP4KZ9BVp9j2ho4Mh/integrations/crm/salesforce-integration/salesforce-custom-object-and-custom-field-mapping-for-rillet-contract-creation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.