> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/crm-integrations/salesforce-legacy.md). # Salesforce legacy > This article covers the Salesforce legacy integration: a connection that Younium runs and configures from Younium's integration settings, together with the original Younium package for Salesforce, installed in the Salesforce org. Customers using the newer Younium managed package, configured entirely inside Salesforce, use the [Salesforce Gen 2 Integration](/crm-integrations/salesforce.md). ## Synchronisation scope | Synchronisation | Direction | When it runs | | ----------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------- | | A single account | Salesforce → Younium | When an account with **Synch to Younium** selected is created, or one of its synchronised fields changes | | Accounts, in bulk | Salesforce → Younium | On demand, from the Salesforce integration settings in Younium | | Online payment details (Stripe ids) | Salesforce → Younium | When **Stripe Customer Id** or **Stripe Payment Method Id** changes on a synchronised account | | Opportunities, as new subscriptions, sales orders, change orders and renewals | Salesforce → Younium | On demand, with **Send to Younium** on the opportunity | | Renewals and cancellations of existing subscriptions | Salesforce → Younium | On demand, with **Renewal Order** or **Cancel Order** on a Younium Order | | Subscriptions (orders and their charges, with tiered and volume prices) | Younium → Salesforce | On the schedule of the **Export Younium subscriptions to Salesforce** job, at most every 30 minutes | | Invoices and credit notes | Younium → Salesforce | On the schedule of the **Export Younium invoices to Salesforce** job, at most every 30 minutes | | Invoice PDFs | Younium → Salesforce | On demand, with **Download Invoice PDF** on a Younium Invoices record | | Products, tiered and volume prices, and price book entries | Younium → Salesforce | On demand, from the Salesforce integration settings in Younium | | Price books and the legal entity record | Both directions | On demand, from the Salesforce integration settings in Younium, and at the start of every product synchronisation | Not in scope: contacts, invoice lines, payment records (an invoice carries only its settled amount), and changes made to accounts in Younium, because accounts travel only from Salesforce to Younium. *** ## Overview The Salesforce legacy integration is made up of two parts that work together. The first is a connection that Younium holds for one legal entity: Younium signs in to the Salesforce org as an integration user, reads accounts, and writes subscriptions, invoices, products and price book entries into Salesforce. The second is the original Younium package for Salesforce, installed in the org. It provides the objects and fields that Younium writes to, and it lets sales users work with Younium from inside Salesforce: accounts are sent to Younium as they are saved, products are chosen for an opportunity from the Younium catalogue, and an opportunity is sent to Younium as a new subscription, a sales order, a change or a renewal. Accounts and deals are owned by Salesforce. Sales teams mark which Salesforce accounts belong in Younium, quote from the Younium catalogue on the opportunity, and send the won deal to Younium. Everything that follows from the deal — the subscription as it is invoiced, changed and renewed, the invoices and the product catalogue itself — is owned by Younium and is copied back into Salesforce, so account teams see what each customer has bought and been invoiced without leaving Salesforce. The two parts meet at the account. Every Younium account that came from Salesforce carries the Salesforce account's id in its **Salesforce Id** field, and every order the package sends is placed on the Younium account with that id. *** ## Salesforce objects The package's objects and fields carry the namespace `Younium__` in Salesforce. The integration uses these objects: | Salesforce object | API name | What happens to it | | ------------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | **Account** | `Account` | Sent to Younium by the package, and read by Younium in bulk | | **Opportunity and Opportunity Product** | `Opportunity`, `OpportunityLineItem` | Built with the product selector and sent to Younium by the package | | **Younium setting (custom metadata)** | `Younium__Younium_setting__mdt` | Holds the package's settings, default values and field mappings, read by both parts | | **Younium Table Column (custom metadata)** | `Younium__Younium_Table_Column__mdt` | Holds the columns shown in the product selector and the change order form | | **Younium Legal Entity** | `Younium__Younium_Legal_Entity__c` | Represents a Younium legal entity; accounts, products and price books point to it | | **Younium Order** | `Younium__Y_Younium_Order__c` | Written by Younium, one per subscription; the starting point for change orders, renewals and cancellations | | **Younium Order charge** | `Younium__Younium_Order_charge__c` | Written by Younium, one per charge on a subscription | | **Volume/Tiered Pricing** | `Younium__Y_VolumeTiered_Pricing__c` | Tier prices for products and order charges, written by Younium, and for opportunity products, entered in Salesforce | | **Younium Invoices** | `Younium__Y_Younium_Invoices__c` | Written by Younium, one per posted or settled invoice | | **Product** | `Product2` | Written by Younium, one per charge in the Younium product catalogue | | **Price Book and Price Book Entry** | `Pricebook2`, `PricebookEntry` | Price books read by Younium; the Younium price book and its entries written by Younium | | **Younium Log** | `Younium__Log__c` | Records of the package's calls to Younium and their errors | The package must be installed in the org before the Younium side is connected; Younium does not create objects or fields in Salesforce. *** ## Authentication The integration connects in both directions, and each direction is set up separately. ### Younium to Salesforce The Younium side of the connection belongs to a Younium legal entity. Each legal entity that synchronises with Salesforce has its own connection, and it can point at a different Salesforce org from the other legal entities. Younium connects through a connected app in your Salesforce org and signs in as a dedicated Salesforce integration user, rather than as the person setting the integration up. The package includes a connected app for this, **Younium Connector**. Before you start you need, from Salesforce, the connected app's consumer key and consumer secret; the username, password and security token of the integration user; and the name of your Salesforce instance, which forms the address Younium connects to (`https://{instance}.salesforce.com`). The integration user needs access to the package objects listed above and to accounts, products and price books. You enter these details in the Salesforce integration settings in Younium and activate. Younium signs in to Salesforce with them straight away. If Salesforce accepts them, the details are stored and the connection is live. If Salesforce rejects them, activation fails with *Couldn't connect to salesforce, check if you are using the correct credentials.* and nothing is stored. The integration settings also offer a link that authorises Younium from Salesforce's own sign-in page for the connected app. Saving the settings generates a new link for the legal entity, and only the most recent link is accepted. Once Younium has been authorised this way, it keeps its access through that authorisation instead of signing in with the integration user's password. With a username and password connection, Younium signs in again at the start of every synchronisation, so nothing needs renewing by hand. The connection stops working when anything the sign-in depends on changes in Salesforce: the integration user's password or security token, the user being deactivated, or the connected app's consumer secret. Every exchange from Younium then fails until the new details are entered and the integration is activated again. With an authorised connection, a failure to renew access stops every exchange with *Couldn't fetch a new access token, contact Younium support.* > **Note on the integration user:** Because the connection is that user's sign-in, a routine password change or a reset security token in Salesforce silently stops synchronisation at the next run. A dedicated integration user whose password does not expire keeps the connection stable. ### The package to Younium The package signs in to Younium whenever a user sends something to Younium: an account, an opportunity, a renewal, a cancellation or a request for an invoice PDF. Each call is made for the legal entity of the account concerned, taken from the account's **Legal entity** field. An account without a legal entity cannot be sent. The package offers two ways of signing in, chosen with the **Use New Auth Type** Younium setting: | Use New Auth Type | How the package signs in to Younium | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | *FALSE* (the default) | With the username and password of a Younium user, held in the org's named credentials. The legal entity is identified by the name of the account's Younium Legal Entity record | | *TRUE* | With a client id and client secret for the Younium API, issued in Younium. The legal entity is identified by the **ID** of the account's Younium Legal Entity record | For the client id and secret, an administrator opens the **Credential Setup** tab. It shows two cards, **Sandbox Authentication Status** and **Production Authentication Status**. **Update Credentials** on a card opens **Enter Credentials**, where the **Client Id** and **Client Secret** are entered and saved; the values are stored encrypted in Salesforce. Each card tests its credentials against Younium and shows *Successfully authenticated to environment.* or *Not authenticated to environment.*; the refresh icon tests again. The connection lasts until the credentials are changed or revoked in Younium. A rejected sign-in stops the action the user started, and the reason is shown to the user and recorded in the Younium Log. *** ## Sandbox vs. Production ### Younium to Salesforce You choose whether the legal entity connects to a Salesforce production org or a Salesforce sandbox. The choice decides where Younium signs in: | Environment | Salesforce sign-in | | ----------- | ------------------------------ | | Production | `https://login.salesforce.com` | | Sandbox | `https://test.salesforce.com` | The sandbox choice is stored when the settings are saved, and activation signs in against the environment last saved. Save the settings with the right choice before activating. A sandbox has its own connected app credentials and its own integration user, so moving from a sandbox to production means entering production credentials and activating again, not only changing the choice. ### The package to Younium With client id and secret sign-in, a Salesforce sandbox talks to the Younium sandbox and a Salesforce production org talks to Younium production, so a refreshed sandbox never sends test deals to live Younium. The **Younium Environment Override** Younium setting overrides this. | Environment | Younium API | | ----------- | --------------------------------- | | Production | `https://api.younium.com` | | Sandbox | `https://api.sandbox.younium.com` | The credentials for each environment are held separately on the **Credential Setup** tab, so both can be stored at once. With username and password sign-in, the package always uses the address held in the org's named credentials. ### Settings | Setting | Description | Default | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------- | | **Younium Environment Override** | Younium setting. Blank follows the type of org; *Sandbox* or *Production* forces one Younium environment for client id and secret sign-in | Blank | *** ## Activation Activation signs in to Salesforce with the credentials entered in Younium. On success Younium stores the credentials and the instance address, marks the connection as live, and creates the custom fields the integration uses on Younium records (see [Custom fields created by the integration](#custom-fields-created-by-the-integration)). Activation does not run any exchange. Accounts, products and price books are synchronised when you start them, and subscriptions and invoices are exported when their jobs run. What the package sends from Salesforce does not depend on the Younium side being activated, but it relies on the accounts it refers to existing in Younium. *** ## Deactivation Deactivation removes the legal entity's Salesforce connection in Younium: the stored credentials, the record of when each exchange last ran, and the counts from the last runs. Every exchange that Younium runs stops working until the integration is connected again. The package's own connection to Younium is unaffected, and is removed by clearing its credentials in Salesforce. Nothing else is removed on either side. Records already created in Salesforce stay there, and the Younium custom fields holding Salesforce ids stay on Younium records with their values. > **Note on reconnecting:** Because deactivation forgets when each exchange last ran, the first runs after reconnecting treat every eligible record as new to the run: every eligible subscription and every posted or settled invoice is sent again, and every account marked for synchronisation is imported again. Records that kept their Salesforce ids in Younium are updated in place rather than duplicated, as long as the new connection points at the same Salesforce org. *** ## Save and Setup Saving the settings in Younium stores the connected app's consumer key and consumer secret and the sandbox choice, generates a new authorisation link (see [Authentication](#younium-to-salesforce)), and creates any of the integration's custom fields that are missing. Saving does not test the credentials; activation does. The integration's custom fields are also re-created, when missing, each time Younium signs in with the stored username and password. *** ## Custom fields created by the integration The integration creates the following custom fields on Younium records and uses them to remember which Salesforce record each Younium record corresponds to. Each field is shown in Younium under the name in the **Field** column. | Entity | Field | Type | Holds | | --------------------------- | ---------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | Account | **Salesforce Id** | Text | The id of the Salesforce account. The package finds the account and invoice account of every order it sends through this field | | Order | **Salesforce Order Id** | Text | The id of the Younium Order record in Salesforce | | Order | **Opportunity Id** | Text | Created by the integration; neither part reads or writes it | | Order product charge | **Salesforce Order Id** | Text | The id of the Younium Order charge record in Salesforce | | Order product charge | **Salesforce Product Id** | Text | The id of the Salesforce product for the charge, sent with the order charge | | Order product charge | **Pricebook** | List | A list of the price book names found in Salesforce (see [Price book synchronisation](#price-book-synchronisation)) | | Product | **Exclude product from Salesforce sync** | Checkbox | When selected, the product is left out of product synchronisation | | Product | **Pricebook Category** | Text | A price book category for the product, matched against the names in the **Pricebook** list | | Charge | **Salesforce Product Id** | Text | The id of the Salesforce product created for the charge | | Price details (on a charge) | **PricebookEntry Id** | Text | The id of the price book entry for that currency in the Younium price book | | Invoice | **Salesforce Invoice Id** | Text | The id of the Younium Invoices record in Salesforce | Field mappings (see [Younium settings in Salesforce](#younium-settings-in-salesforce)) add custom fields of their own: one Text custom field for each mapped Younium field that is not a standard field, named exactly as the mapping names it. > **Do not rename or delete these fields.** Both parts of the integration find them by name. A renamed field is re-created empty the next time Younium signs in, and Younium then loses track of which Salesforce records already exist. Do not clear the id values either: an order, charge, invoice or product whose id is cleared is matched again by the recovery rules below where they apply, and created again in Salesforce where they do not. An account whose **Salesforce Id** is cleared can no longer receive orders from Salesforce. *** ## Younium settings in Salesforce The package's settings live in **Younium setting** custom metadata records in Salesforce. Each record has a **Setting type**, and depending on the type a **Config value**, or a **Younium object**, **Salesforce field** and **Younium field**. ### Settings | Setting | Description | Default | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | **Initial term** | *Default values*. The default **Initial term (months)** of a new opportunity | 12 | | **Renewal term** | *Default values*. The default **Renewal term (months)** of a new opportunity | 12 | | **Use New Auth Type** | *TRUE* signs in to Younium with a client id and secret, *FALSE* with a username and password (see [Authentication](#the-package-to-younium)) | FALSE | | **Younium Environment Override** | See [Sandbox vs. Production](#the-package-to-younium) | Blank | | **Sync Auto Renewal In Change Order** | *TRUE* sends the opportunity's **Auto renewal** with a change order, so a change can switch auto-renewal on or off | FALSE | | **Show\_Description** | *TRUE* lets users edit the opportunity description in the product selector | FALSE | | **Show Effective Start Date** | *TRUE* shows the opportunity's **Effective start date** (new orders) or **Effective change date** (change orders) in the product selector | FALSE | | **Show\_TCV** | *TRUE* shows TCV in the product selector | TRUE | | **Show Charge Tier Description** | *TRUE* shows each tier's **Description** when tiers are edited | FALSE | | **Use Old Opportunity Product Table** | *TRUE* shows the product selector's earlier table of opportunity products | FALSE | | **Logging Level (NONE, ERROR, INFO)** | How much the package records in the Younium Log: *NONE*, *ERROR* or *INFO* | INFO | Several further records whose labels begin *(DEPRECATED)* are shipped with the package and have no effect. ### Field mappings A Younium setting with **Setting type** *Field mapping* maps a Salesforce field to a Younium field. The **Younium object** decides which exchange uses it and in which direction: | Younium object | Direction | Applied when | Behaviour | | ----------------------------------- | -------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *Account* | Salesforce → Younium | An account is sent by the package, or read in a bulk synchronisation | The Salesforce account field fills a Younium account custom field of the given name, created as Text when it does not exist. A change to a mapped field also makes the package send the account. Account mappings fill custom fields only, not standard account fields | | *Order* | Salesforce → Younium | An opportunity is sent | The Salesforce opportunity field fills the order custom field of the given name | | *Order charge* | Salesforce → Younium | An opportunity is sent | The Salesforce opportunity product field fills the order product's custom field of the given name | | *Order product charge* | Salesforce → Younium | An opportunity is sent | The Salesforce opportunity product field fills the order product charge's custom field of the given name | | *Younium Order (Salesforce)* | Younium → Salesforce | Subscriptions are exported | The Salesforce field on the Younium Order is filled from the order's custom field of the given name or, when the order has none, from the standard order field with that name | | *Younium Order charge (Salesforce)* | Younium → Salesforce | Subscriptions are exported | The same, for the Younium Order charge and the order product charge's fields | On export, dates and date-times read from standard fields are sent as `yyyy-MM-dd`, and a field with no value is left out. When a mapped Younium account field is a list custom field, the value from Salesforce is matched to a list item by its key and the item's value is stored. When an account is sent by the package, an unknown key fails the whole account with *No list item found with key: {key}*; in a bulk synchronisation the unknown key is reported in the integration log and the value is stored as it is. *** ## Eligibility and scope ### Legal entity Every exchange that Younium runs is for the legal entity whose connection is in use: only Salesforce accounts linked to that legal entity are imported in bulk, only Younium products owned by that legal entity are synchronised, and the price book Younium maintains is the one named after that legal entity. Everything the package sends goes to the legal entity of the account concerned. ### Accounts | Rule | Salesforce field | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The account is marked for synchronisation | **Synch to Younium** (`Younium__Y_Synch_to_Younium__c`) is selected | | The account has a legal entity | **Legal entity** (`Younium__Legal_entity__c`) points to a Younium Legal Entity record. In a bulk synchronisation, that record's **ID** must be the id of the connected Younium legal entity | An account that already exists in Younium is skipped in a bulk synchronisation when it has not changed in Salesforce since the previous one. ### Opportunities An opportunity can be sent to Younium only when: | Rule | Message when it fails | | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Is Synched To Younium** is not selected | *Opportunity is already synced with Younium. If you want to send this opportunity again, please uncheck the checkbox "Is synched to Younium" first* | | The account has a **Legal entity** | *Legal entity is not set on account.* | | The account has **Synch to Younium** selected | *The Account is not synced to Younium.* | | The **Invoice Account**, if set, has **Synch to Younium** selected | *Invoice Account not Synced to Younium* | | Every opportunity product's Salesforce product carries its Younium product, charge plan and charge ids | *Product {name} not synced correctly and is missing identifiers.* | | The **Order type** is *New order*, *Change order* or *Renewal Order* (unless **Order Mode** is *Sales Order*) | *No valid order type has been set for the opportunity.* | | A new order has an **Effective start date** | *Effective start date is required for new orders* | | A change order has an **Effective change date** | *Effective change date is required for change orders* | | A renewal has **Renewal term (months)** and **Next Renewal Term (Months)** | *Renewal term and Next renewal term are required for renewal orders* | The accounts must also exist in Younium with their **Salesforce Id**, which they do once they have been sent. ### Subscriptions exported to Salesforce | Rule | Detail | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Account | The order's account has a **Salesforce Id** | | Order type | Subscription. Sales orders are not exported | | Version | Only the latest version of each order | | Status | *Active*, *Cancelled* or *Deleted*. Draft and other statuses are not exported | | Changed since the last run | The order, or one of its custom fields, changed since the previous export. On the first run every eligible order is exported | A charge is exported only when its order was exported successfully in the same run, and then only when one of these holds: | Rule | Detail | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Changed since the last run | The charge, one of its custom fields, or its order product changed since the previous export | | Not yet in Salesforce | The charge has no **Salesforce Order Id**, and its order is not *Deleted*. Such a charge is sent whenever its order is in the run, not only in the run in which the charge itself changed | Only the latest version of each charge is exported. ### Invoices exported to Salesforce | Rule | Detail | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Account | The invoice's account has a **Salesforce Id** | | Status | *Posted* or *Settled*. Draft and cancelled invoices are not exported | | Changed since the last run | The invoice, or one of its custom fields, changed since the previous export. On the first run every eligible invoice is exported | Credit notes are exported on the same terms as invoices. ### Products synchronised to Salesforce | Rule | Detail | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Legal entity | The product belongs to the connected legal entity. Products shared from a parent legal entity are synchronised by the parent legal entity's own connection | | Exclusion | **Exclude product from Salesforce sync** is not selected | Every charge on every charge plan of an eligible product becomes one Salesforce product. Products are synchronised in full on every run; there is no changed-since filter. *** ## Sending accounts from Salesforce ### When it runs The package sends an account to Younium in the background when: | Event | Condition | | --------------------- | ---------------------------------------------------------------------------- | | An account is created | **Synch to Younium** is selected | | An account is edited | **Synch to Younium** is selected, and one of the synchronised fields changed | The synchronised fields are **Account Name**, **Synch to Younium**, **Legal entity**, the account currency, every billing and shipping address field, **Invoice email**, **Invoice CC Email**, **Org Nr**, **Tax reg Nr**, **Our reference**, **Your reference**, **Younium invoice template**, **Tax template**, **Payment terms**, **Accounts receivable account**, **Invoice Delivery Method**, **Electronic Invoice Address**, **Stripe Customer Id**, **Stripe Payment Method Id**, and every field in an *Account* field mapping. > **Note on bulk changes in Salesforce:** The package sends one account per save. When many accounts are saved together, as in a data import, only the first of them is sent, and accounts saved by background processes are not sent at all. Run a bulk account synchronisation from Younium to bring such accounts across. ### What happens Younium matches the account to a Younium account through **Salesforce Id**. When none matches, it creates a new account with Younium's default account values, the name and the Salesforce id, in the account's legal entity. The account is then updated with the fields below. Younium's answer is written to the account's **Younium Info** field: *{account number} : {account name} was updated from Salesforce into Younium at {date}* on success, or *There was an error when updating the account in Younium:* followed by the reason. A successful import is also recorded in the Younium integration log as *Imported/Updated account {account number} {account name} from Salesforce*. A failure to reach Younium at all is recorded in the Younium Log in Salesforce. When the account has no billing street, its shipping address is sent as the billing address too. ### Field mapping: account (Salesforce → Younium) Lookups take effect only when a matching record exists in Younium, so the package's picklists for these fields must hold values that match the names or codes in Younium. Fields marked *when filled* are written only when Salesforce has a value; the others are written as sent, so an empty value clears the Younium field. | Younium Field | Salesforce Field | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | **Account Name** (`Name`) | | **Salesforce Id** (new accounts) | The account id | | **External CRM Id** | The account id | | **Currency** | **Account Currency** (`CurrencyIsoCode`), matched on the currency code | | **Your reference** | **Your reference** (`Younium__Y_Your_reference__c`) | | **Our reference** | **Our reference** (`Younium__Y_Our_reference__c`) | | **Tax reg. nr** | **Tax reg Nr** (`Younium__Y_Tax_reg_Nr__c`) | | **Org number** | **Org Nr** (`Younium__Y_Org_Nr__c`) | | **Invoice email** (when filled) | **Invoice email** (`Younium__Y_Invoice_email__c`) | | **Invoice email Cc** (when filled) | **Invoice CC Email** (`Younium__Y_Invoice_CC_Email__c`) | | **E-Invoice Address** (when filled) | **Electronic Invoice Address** (`Younium__Electronic_Invoice_Address__c`) | | **Invoice delivery method** | **Invoice Delivery Method** (`Younium__Invoice_Delivery_Method__c`): *Email*, *Print*, *ElectronicInvoice*, *ExternalPrint* or *AutomaticElectronicRouting* | | **Tax template** | **Tax template** (`Younium__Tax_template__c`), matched on the tax template's name | | **Payment term** | **Payment terms** (`Younium__Payment_terms__c`), matched on the payment term's name | | **Accounts receivable** | **Accounts receivable account** (`Younium__Accounts_receivable_account__c`), matched on the financial account's code | | **Invoice template** | **Younium invoice template** (`Younium__Younium_invoice_template__c`), matched on the invoice template's description | | **External ERP Id** (when filled) | **ERP Id** (`Younium__ERP_Id__c`) | | Account custom fields (when filled) | Fields in *Account* field mappings | | **Invoice address street** and **Invoice address street 2** | **Billing Street** (`BillingStreet`), split at the first line break | | **Invoice address city** | **Billing City** (`BillingCity`) | | **Invoice address zip** | **Billing Zip/Postal Code** (`BillingPostalCode`) | | **Invoice address state** | **Billing State Code** (`BillingStateCode`) | | **Invoice address country** | **Billing Country Code** (`BillingCountryCode`), matched on the two-letter code | | **Delivery address street** | **Shipping Street** (`ShippingStreet`) | | **Delivery address city** | **Shipping City** (`ShippingCity`) | | **Delivery address zip** | **Shipping Zip/Postal Code** (`ShippingPostalCode`) | | **Delivery address state** | **Shipping State Code** (`ShippingStateCode`) | | **Delivery address country** | **Shipping Country Code** (`ShippingCountryCode`), matched on the two-letter code | The invoice address is written only when a billing street is sent, and the delivery address only when a shipping street is sent. A new address is described as *Billing address* or *Shipping address* in Younium. *** ## Bulk account synchronisation ### When it runs A bulk account synchronisation runs when you start it from the Salesforce integration settings in Younium. It is not scheduled. ### What happens Younium reads the *Account* field mappings, creates any missing account custom fields they name, and then reads every Salesforce account that meets the eligibility rules above. Each Salesforce account is matched to a Younium account through **Salesforce Id**. When no Younium account has that id, a new account is created with Younium's default account values, the account name and the Salesforce id. When one does, it is updated with the fields in the mapping below, unless it has not changed in Salesforce since the previous bulk synchronisation. The run ends by recording when it ran, and logs the number of new and updated accounts in the integration log as *{n} new, {n} updated*. A failure on one account is logged as *Couldn't import account with Salesforce Id: {id}* with the reason, and the run continues with the next account. When Younium cannot read the field mappings, the run stops with *Couldn't map Younium Settings in Salesforce to Younium Custom fields.* When it cannot read the accounts themselves, the run stops and logs *Couldn't import accounts salesforce query failed.* ### Field mapping: bulk account synchronisation (Salesforce → Younium) Lookups take effect only when a matching record exists in Younium. Fields marked *when filled* are only written when the Salesforce field has a value. Fields from older package versions that an org does not have are left out silently. | Younium Field | Salesforce Field | | ----------------------------------------- | --------------------------------------------------------------------------------------------------- | | **Name** (new accounts only) | **Account Name** (`Name`) | | **Salesforce Id** and **External CRM Id** | The account id | | **Site** | **Website** (`Website`) | | **Invoice email** (when filled) | **Invoice email** (`Younium__Y_Invoice_email__c`) | | **Invoice email Cc** (when filled) | **Invoice CC Email** (`Younium__Y_Invoice_CC_Email__c`) | | **E-Invoice Address** (when filled) | **Electronic Invoice Address** (`Younium__Electronic_Invoice_Address__c`) | | **Invoice delivery method** | **Invoice Delivery Method** (`Younium__Invoice_Delivery_Method__c`), matched by name, ignoring case | | **Accounts receivable** | **Accounts receivable account** (`Younium__Accounts_receivable_account__c`), matched on code | | **Tax template** | **Tax template** (`Younium__Tax_template__c`), matched on name | | **Payment term** | **Payment terms** (`Younium__Payment_terms__c`), matched on name | | **Invoice template** | **Younium invoice template** (`Younium__Younium_invoice_template__c`), matched on description | | **External ERP Id** (when filled) | **ERP Id** (`Younium__ERP_Id__c`) | | Account custom fields | Fields in *Account* field mappings | The invoice address is updated only when the account has a **Billing Country Code**, and the delivery address only when it has a **Shipping Country Code**. Both are mapped as for a single account, except that the shipping street is also split at its first line break into **Delivery address street** and **Delivery address street 2**. An unrecognised country code clears the country. *** ## Online payment details When **Stripe Customer Id** or **Stripe Payment Method Id** changes on an account with **Synch to Younium** selected, or **Synch to Younium** is selected on an account that already has one of them, the package sends the Stripe ids to the account's online payment details in Younium. | Change in Salesforce | Effect in Younium | | -------------------------------------------- | ---------------------------------- | | Stripe ids added to an account that had none | Online payment details are created | | Stripe ids changed | Online payment details are updated | | Both Stripe ids cleared | Online payment details are removed | The package first finds the Younium account by its **External CRM Id** and stores its Younium id in the account's **Younium Id** field. Younium's answer, or the error, is written to **Online Payment Details Info**. *** ## Selecting products on an opportunity **Select products** on an opportunity opens the Younium product selector. It offers the Younium products and charge plans that have an active Salesforce product with an entry in the opportunity's price book and currency. An entry with **Hide from Younium Product Selector** selected is not offered. When the opportunity's **Order Mode** is *Sales Order*, only products with one-off charges are offered. Choosing a product with **Select product** and its charge plans with **Select Charge Plans** adds one opportunity product per charge of each charge plan, in the products' **Sort Order**. Each starts with quantity 1, the entry's price as both **Sales Price** and **List**, *Align to order* for **Start on** and **End on**, and the charge's **Charge type**, **Price period**, **Billing period**, **Charge Model** and **Unit Of Measure**. The charges added together for one charge plan become one order product in Younium. **Save to opportunity** saves them. For tiered and volume charges, the product's tiers are copied to the opportunity product as Volume/Tiered Pricing records, where they can be changed with **Add Tier**, **Delete** and **Save Tiers**. Tiers cannot be changed for a product with **Tiers Locked in Product Picker** selected. Whenever the tiers or the quantity change, the package recalculates the opportunity product's total price and list price from the tiers: | Charge Model | Price | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *Volume* | The tier whose **From Quantity** to **To Quantity** range holds the quantity: its **Price** when its **Price Base** is *Flat*, otherwise its **Price** times the quantity | | *Tiered* | The sum over the tiers the quantity reaches: a *Flat* tier adds its **Price**, a *PerUnit* tier adds its **Price** for each unit within its range | On a one-off charge the package clears **Billing period**, **End on** and **End date**. Deleting an opportunity product deletes its tiers. The columns of the charge tables are set by **Younium Table Column** custom metadata records for the *Product Picker Charge Table* and the *Product Picker Existing Table*: each record names the opportunity product field, and sets whether the column is active, its order, its width and whether it is read-only. ### Settings | Setting | Description | Default | | -------------------------------------- | ----------------------------------------------------------------------------- | ------------ | | **Hide from Younium Product Selector** | On a price book entry. Leaves the entry's product out of the product selector | Not selected | | **Tiers Locked in Product Picker** | On a product. Prevents the tiers from being changed on the opportunity | Not selected | | **Sort Order** | On a product. The order in which a charge plan's charges are added | Blank | The Younium settings **Show\_Description**, **Show Effective Start Date**, **Show\_TCV**, **Show Charge Tier Description** and **Use Old Opportunity Product Table** also change the product selector (see [Younium settings in Salesforce](#settings)). *** ## Sending an opportunity to Younium ### When it runs **Send to Younium** on an opportunity sends it to Younium immediately. The result is shown on screen: *The Opportunity was successfully sent to Younium!*, or *Something went wrong, please give your administrator the following details:* followed by the reason. The package also provides the flow action **Send Opportunity to Younium (V2 API)**, which does the same from a flow an administrator builds. ### What a deal becomes | Order Mode | Order type | What happens in Younium | | -------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *Sales Order* | Any | A sales order is created | | *Subscription* | *New order* | A subscription is created | | *Subscription* | *Change order* | The subscription named by the opportunity's **YouniumOrderId** is changed from the **Effective change date**. When **Renewal term (months)** and **Next Renewal Term (Months)** are both set, the subscription is then also renewed | | *Subscription* | *Renewal Order* | The subscription named by **YouniumOrderId** is renewed with **Renewal term (months)** and **Next Renewal Term (Months)** | | *Subscription* | *Cancellation Order* | Nothing; the opportunity is rejected as having no valid order type | On success the opportunity's **Is Synched To Younium** is selected, and for new subscriptions, sales orders and changes **YouniumOrderId** holds the id of the Younium order. The order arrives in Younium on the account whose **Salesforce Id** is the opportunity's account, and is invoiced to the **Invoice Account**, or to the account when none is set. > **Note on change orders that also renew:** When the change succeeds but the renewal fails, the user sees *The change order was sent to Younium, but the renewal could not be performed. Please contact your administrator or create the renewal order manually*. The change is already in Younium, but the opportunity is not marked as synchronised. Opportunity products are matched to Younium by the Younium product, charge plan and charge ids that product synchronisation wrote to the Salesforce product. On a change order, an opportunity product of **Type** *Change* with an **Order product number** changes that existing order product, and its charges are identified by their **Order charge number**; other opportunity products are added as new order products. ### Field mapping: order (Salesforce → Younium) | Younium Field | Salesforce Field (on the opportunity) | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Account** | The account, found through the Younium account's **Salesforce Id** | | **Invoice account** | **Invoice Account** (`Younium__invoice_account__c`), or the account when blank, found the same way | | **Currency** | **Opportunity Currency** (`CurrencyIsoCode`) | | **Status** | **Younium Status** (`Younium__Younium_Status__c`): *Draft* or *Active*. For a sales order, *Draft* becomes an order draft and *Active* an order | | **Order type** | *Subscription*, or *SalesOrder* when **Order Mode** is *Sales Order* | | **Subscription type** | **Subscription type** (`Younium__Y_Subscription_type__c`): *Termed* or *Evergreen* | | **Effective start date** | **Effective start date** (`Younium__Y_Effective_start_date__c`) | | **Effective change date** | **Effective change date** (`Younium__Effective_change_date__c`) | | **Order date** | **Order date** (`Younium__Order_date__c`) | | **Initial term (months)** | **Initial term (months)** (`Younium__Y_Initial_term_months__c`) | | **Renewal term (months)** | **Renewal term (months)** (`Younium__Y_Renewal_term_months__c`) | | **Notice period (months)** | **Notice Period (Months)** (`Younium__Notice_Period_Months__c`), default 3 | | **Auto-renewal** | **Auto renewal** (`Younium__Y_Auto_renewal__c`); on a change order only when **Sync Auto Renewal In Change Order** is *TRUE* | | **Payment method** | **Payment method** (`Younium__Payment_method__c`): *Invoice* or *Stripe* | | **Description** | **Description** (`Description`) | | **Remarks** | **Remarks** (`Younium__Remarks__c`) | | **Your reference** | **Your reference** (`Younium__Y_Your_reference__c`) | | **Our reference** | **Our reference** (`Younium__Y_Our_reference__c`) | | **Your order number** | **Your order number** (`Younium__Y_Your_order_number__c`) | | **Buyer reference** | **Buyer Reference** (`Younium__Buyer_Reference__c`) | | Order custom fields | Fields in *Order* field mappings | A change order sends only **Effective change date**, the references, **Remarks**, **Invoice Account**, the mapped custom fields and, depending on the setting, **Auto renewal**, together with its products. ### Field mapping: order product charge (Salesforce → Younium) | Younium Field | Salesforce Field (on the opportunity product) | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Charge | The Salesforce product's **Younium Charge ID**, or the **Order charge number** for a changed charge | | **Description** (the charge name) | **Younium Charge name** (`Younium__Y_Younium_Charge_name__c`), or the product's **Younium Charge name** when blank | | **Charge type** | **Charge type** (`Younium__Y_Charge_type__c`) | | **Charge model** | **Charge Model** (`Younium__Charge_Model__c`) | | **Effective Start** | **Start date** (`Younium__Y_Start_date__c`) | | **Effective End** | **End date** (`Younium__Y_End_date__c`) | | **Start on** | **Start on** (`Younium__Y_Start_on__c`): *Align to order* or *Specific date* | | **End on** (not for one-off charges) | **End on** (`Younium__Y_End_on__c`): *Align to order* or *Specific date* | | **Billing period** (not for one-off charges) | **Billing period** (`Younium__Y_Billing_period__c`) | | **Price period** | **Price period** (`Younium__Y_Price_period__c`) | | **Quantity** (not for *Flat* charges) | **Quantity** (`Quantity`) | | **Unit** (not for *Flat* charges) | **Unit Of Measure** (`Younium__Unit_Of_Measure__c`) | | **Remarks** | **Remarks** (`Younium__Remarks__c`) | | **Billing timing** | Always in advance | | Order product custom fields | Fields in *Order charge* field mappings | | Order product charge custom fields | Fields in *Order product charge* field mappings | ### Field mapping: price details (Salesforce → Younium) For *Volume* and *Tiered* charges with tiers, one price detail is sent per Volume/Tiered Pricing record, in tier order. For all other charges, a single price detail is sent as tier 0. | Younium Field | Salesforce Field | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tier** | **Tier** (`Younium__Tier__c`), or 0 | | **Price** | Tiers: **Price** (`Younium__Price__c`). Otherwise **Total Price** for *Flat* charges and **Sales Price** for the rest | | **List Price** | Tiers: **List Price** (`Younium__List_Price__c`) on a subscription, and the opportunity product's list price on a sales order. Otherwise **List** (`Younium__List_price__c`), times the quantity for *Flat* charges | | **Description** | **Description** (`Younium__Description__c`) | | **From quantity** | **From Quantity** (`Younium__Minimum_Qty__c`) | | **To quantity** | **To Quantity** (`Younium__Maximum_Qty__c`) | | **Price base** | **Price Base** (`Younium__Price_Base__c`): *Flat* or *PerUnit* | *** ## Change orders **Create Change Order** on a Younium Order opens a form for a new change opportunity. The user fills in the opportunity fields the form shows — always **Opportunity Name**, **Close Date** and **Effective change date**, plus the fields set by **Younium Table Column** records for the *Change Order Table* (by default **Amount**, **Stage** and **Type**) — and selects the order charges to change. The package then creates the opportunity and its products, and shows *Change order successfully created* with a link to it. | Opportunity field | Value | | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Account** and **Invoice Account** | From the Younium Order, unless entered on the form | | **Price Book** | The Younium Order's **Price Book** or, when blank, the price book linked to its legal entity, unless entered | | **Currency** | The Younium Order's currency, unless entered | | **Auto renewal** | The Younium Order's **Auto renewal**, unless entered | | **Younium Status** | *Active*, unless entered | | **Order type** | *Change order*, unless entered | | **Younium Order**, **Order Number** and **YouniumOrderId** | Always from the Younium Order | Each selected charge becomes one opportunity product of **Type** *Change*, carrying the charge's Salesforce product, **Order charge number**, **Order product number**, **Charge type**, **Charge Model**, **Billing period**, **Price period**, **UOM** and name; its **Price** as **Sales Price** and **List** (0 when blank); and its **Quantity** (1 when blank or 0). The charge's tiers are copied to the new opportunity product. The opportunity is then edited as usual and sent with **Send to Younium**. A charge without a Salesforce product stops the change with *No SF\_Prod\_Id for the following order charge: {name}*, and a product with no entry in the price book and currency with *No pricebook entry found for the following productId: {id}*. A user without access to the objects and fields involved sees which object's permissions are missing. The package also provides the flow action **Create Change Order**, which creates the same change opportunity from a flow. *** ## Renewals **Renewal Order** on a Younium Order asks for **Renewal Term (Months)** and **Next Renewal Term (Months)** and renews the subscription in Younium with them. On success the user sees *You've renewed this order!*; otherwise *Renewal was not created.* with the reason. When the Younium Order has **Auto renewal** selected, the two terms are also stored on it. The flow action **Renew Younium Order** does the same from a flow, given the Younium Order and the two terms. *** ## Cancellations **Cancel Order** on a Younium Order asks for a **Cancellation Date** and a **First day of cancellation** and cancels the subscription in Younium with them. On success the user sees *You've cancelled this order!*, and the Younium Order is marked **Cancelled**, its **Order status** set to *Cancelled* and both dates stored on it. When Younium rejects the cancellation, the user sees *Cancellation was not created.* with the reason, and the Younium Order is left unchanged. The next subscription export brings the cancelled subscription's own values, including its **Cancellation date**, from Younium. *** ## Subscription export ### When it runs The **Export Younium subscriptions to Salesforce** job exports subscriptions on the schedule you set for it among Younium's jobs. It can run at most every 30 minutes. ### What happens Each eligible order (see [Eligibility and scope](#subscriptions-exported-to-salesforce)) is sent as a Younium Order in Salesforce. An order without a **Salesforce Order Id** is created under its account's Salesforce account, and the id Salesforce returns is stored in **Salesforce Order Id**. An order that has one updates that record. Once the orders have been sent, the charges of every order exported successfully in the run are sent as Younium Order charges under their order, created or updated on the same principle, with the id stored in the charge's **Salesforce Order Id**. For tiered and volume charges, one Volume/Tiered Pricing record per tier follows. The run records when it ran and logs *Exported {n} new subscriptions and updated {n} in Salesforce.* in the integration log. The job's result shows *Successfully exported Younium subscriptions to Younium Order objects in Salesforce* or *Couldn't Export Younium subscriptions to salesforce, try again or contact Younium support* followed by the reason. > **Note on deleted orders:** A *Deleted* order stays in Salesforce. It is updated with status *Deleted* and with **CMRR**, **TCV** and **ACV** of 0, so reports on Younium Orders stop counting it. ### Duplicate protection Before creating anything, the export looks for records in Salesforce that Younium created earlier but did not manage to record the id of: | Record | How it is found | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Order without a **Salesforce Order Id** | Among the Younium Orders under the account's Salesforce account, the one whose **Younium Order ID** is the order's Younium id | | Charge without a **Salesforce Order Id** or **Salesforce Product Id** | Among the Younium Order charges under the order's Salesforce record, the one whose **Younium order charge ID** is the charge's Younium id; both ids are restored from it | When a match is found, the id is restored in Younium and the record is updated instead of created again. ### Change orders and copied charges A charge added by a change order can carry the same **Salesforce Order Id** as the charge it was copied from. Two charges with one Salesforce id would overwrite the same Salesforce record. When charges on an order share a Salesforce id, the charge with the lowest charge number keeps it, and rows that share that charge number keep it too. Each of the others is first looked up in Salesforce by its own Younium charge id; when Salesforce already has a separate record for it, that record is linked. Otherwise the charge is created as a new Salesforce record and its id replaced. ### Failure behaviour and retries A record that fails in one run is queued for the next run, whether or not it changes in Younium in the meantime. | Situation | What happens | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Creating or updating an order fails | Logged as *Order {number} couldn't be created* or *couldn't be updated* with Salesforce's reason. The order is queued for the next run, its charges are not sent in this run, and the other orders carry on | | A charge's order has no Salesforce id | Logged as *Skipped charge {number} ... parent order has no Salesforce ID. The order must be exported first.* The order and all its charges are queued for the next run | | Creating the charges of an order fails | Logged as *Couldn't export order charges on order: {number}* with the charges and the reason. All charges of the order, and the order, are queued for the next run | | Updating the charges of an order fails | Logged as *Couldn't update order charges on Order: {number}*. Younium checks which of the order's stored charge ids no longer exist in Salesforce and clears them, so those charges are created again on the next run instead of failing every time. All charges of the order, and the order, are queued for the next run | | Looking up existing records in Salesforce fails | The orders or charges concerned are left out of this run and queued for the next, rather than risking a duplicate | | Sending tiered or volume prices fails | The run stops with *Couldn't export one or more volume/tiered mappings* and the job reports the error | Salesforce accepts or rejects each order's charges together: when one charge is rejected, none of that order's charges in the same request is saved. ### Field mapping: order (Younium → Salesforce) Object: Younium Order (`Younium__Y_Younium_Order__c`). Dates are sent as `yyyy-MM-dd`. | Younium Field | Salesforce Field | | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | **Order number** | **Order number** (`Younium__Order_number__c`) | | **Id** | **Younium Order ID** (`Younium__Younium_Order_ID__c`) | | **Version** | **Order version** (`Younium__Y_Order_version__c`) | | **Status** | **Order status** (`Younium__Y_Order_status__c`): *Active*, *Cancelled* or *Deleted* | | **Subscription type** | **Subscription type** (`Younium__Subscription_type__c`) | | **Auto-renewal** | **Auto renewal** (`Younium__Auto_renewal__c`) | | **Renewal term (months)** | **Renewal term (months)** (`Younium__Renewal_term_months__c`) | | **Effective start date** | **Effective start date** (`Younium__Effective_start_date__c`) | | **Effective end date** | **Effective end date** (`Younium__Effective_end_date__c`) | | **Effective cancellation date** (*Cancelled* orders only) | **Cancellation date** (`Younium__Y_Cancellation_date__c`) | | **Currency code** | **Currency** (`CurrencyIsoCode`) | | **CMRR** (0 when *Deleted*) | **CMRR** (`Younium__CMRR__c`) | | **TCV** (0 when *Deleted*) | **TCV** (`Younium__TCV__c`) | | **ACV** (0 when *Deleted*), when the org has the field | **ACV** (`Younium__ACV__c`) | | The **Salesforce Id** of the order's **Account** (on create) | **Account** (`Younium__Account__c`) | | The **Salesforce Id** of the order's **Invoice account**, when the org has the field and the invoice account has one | **Invoice Account** (`Younium__Invoice_Account__c`) | | Mapped fields | Fields in *Younium Order (Salesforce)* field mappings | ### Field mapping: order charge (Younium → Salesforce) Object: Younium Order charge (`Younium__Younium_Order_charge__c`). Dates are sent as `yyyy-MM-dd`. | Younium Field | Salesforce Field | | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | **Charge number** | **Order charge number** (`Younium__Order_charge_number__c`) | | **Id** | **Younium order charge ID** (`Younium__Younium_order_charge_ID__c`) | | **Description** (the charge name) | **Younium Charge Name** (`Younium__Younium_Charge_Name__c`), and the record name cut to 80 characters | | **Product number** of the order product | **Order product number** (`Younium__Order_product_number__c`) | | **Charge type** | **Charge type** (`Younium__Charge_type__c`) | | **Charge model** | **Charge model** (`Younium__Charge_model__c`) | | **Billing period** | **Billing period** (`Younium__Billing_period__c`) | | **Price period** | **Price period** (`Younium__Price_period__c`) | | **Quantity** | **Quantity** (`Younium__Quantity__c`) | | **Unit** | **UOM** (`Younium__UOM__c`) | | **Effective Start** | **Effective start date** (`Younium__Effective_start_date__c`) | | **Effective End** | **Effective end date** (`Younium__Effective_end_date__c`) | | **Remarks** (when filled), cut to 255 characters | **Remarks** (`Younium__Remarks__c`) | | **CMRR** | **CMRR** (`Younium__CMRR__c`) | | **TCV** | **TCV** (`Younium__TCV__c`) | | **CMRR** currency | **Currency** (`CurrencyIsoCode`) | | **ACV**, when the org has both ACV and price fields | **ACV** (`Younium__ACV__c`) | | **Price** of the charge's active price details (0 when there are none), on the same condition | **Price** (`Younium__Price__c`) | | **Salesforce Product Id** (when filled) | **SF\_Prod\_ID** (`Younium__SF_Prod_ID__c`) | | The order's **Salesforce Order Id** (on create) | **Younium order** (`Younium__Younium_order__c`) | | Mapped fields | Fields in *Younium Order charge (Salesforce)* field mappings | ### Field mapping: order charge tiers (Younium → Salesforce) Object: Volume/Tiered Pricing (`Younium__Y_VolumeTiered_Pricing__c`), for charges whose charge model is tiered or volume, when the org has that object. Each price detail row is matched to an existing record by the charge's Salesforce record and the tier number, and created when there is none. | Younium Field | Salesforce Field | | ------------------------------------ | ------------------------------------------------------------- | | The charge's **Salesforce Order Id** | **Younium Order Charge** (`Younium__Younium_Order_Charge__c`) | | **Tier** | **Tier** (`Younium__Tier__c`) | | **Description** | **Description** (`Younium__Description__c`) | | **From quantity** | **From Quantity** (`Younium__Minimum_Qty__c`) | | **To quantity** | **To Quantity** (`Younium__Maximum_Qty__c`) | | **Price** | **Price** (`Younium__Price__c`) | | **List Price** | **List Price** (`Younium__List_Price__c`) | | **Price base** | **Price Base** (`Younium__Price_Base__c`) | | The charge's **Quantity** | **Quantity** (`Younium__Quantity__c`) | | **Price** currency | **Currency** (`CurrencyIsoCode`) | *** ## Invoice export ### When it runs The **Export Younium invoices to Salesforce** job exports invoices on the schedule you set for it among Younium's jobs. It can run at most every 30 minutes. ### What happens Eligible invoices (see [Eligibility and scope](#invoices-exported-to-salesforce)) are sent account by account as Younium Invoices records under the Salesforce account. An invoice without a **Salesforce Invoice Id** is created, and the id Salesforce returns is stored in **Salesforce Invoice Id**; an invoice that has one updates that record. A settled invoice is sent again whenever it changes, so its status and settled amount stay current in Salesforce. Before creating anything, the export looks for invoices Younium created earlier without recording the id: among the Younium Invoices records under the account's Salesforce account, the one whose **Younium ID** is the invoice's Younium id. A match is linked and updated instead of created again. The run records when it ran and logs *Exported {n} new invoices and updated {n} in Salesforce.* in the integration log. The job's result shows *Successfully exported Younium Invoices to Younium Invoice objects in Salesforce*, or *Couldn't Export Younium invoices to salesforce, try again or contact Younium support* when the run cannot complete. ### Failure behaviour and retries Each account's invoices are sent separately, so one account's failure does not hold back the others. Salesforce accepts or rejects an account's invoices in each request together. | Situation | What happens | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Creating an account's new invoices fails | Logged as *Failed to create invoices for account* with the reason. Those invoices are queued for the next run | | Updating an account's invoices fails | Logged as *Some invoices couldn't be updated for account* or *Failed to update invoices for account* with the reason. All of that account's invoices in the run are queued for the next run | | Looking up existing invoices in Salesforce fails for an account | That account's invoices are left out of this run and queued for the next | Queued invoices are sent in the next run whether or not they change in Younium in the meantime. ### Invoice PDF **Download Invoice PDF** on a Younium Invoices record fetches the invoice's PDF from Younium and saves it as a file on the record, named after the invoice number. The user sees *PDF Successfully downloaded* and finds the file in the record's related files, or *PDF download error* with the reason. ### Field mapping: invoice (Younium → Salesforce) Object: Younium Invoices (`Younium__Y_Younium_Invoices__c`). Dates are sent as `yyyy-MM-dd`. | Younium Field | Salesforce Field | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **Invoice number** | **Invoice number** (`Younium__Invoice_number__c`) | | **Id** | **Younium ID** (`Younium__Younium_ID__c`) | | **Status** | **Status** (`Younium__Status__c`): *Posted* or *Settled* | | **Invoice date** | **Invoice date** (`Younium__Invoice_date__c`) | | **Due date** | **Due date** (`Younium__Due_date__c`) | | **Currency** | **Currency code** (`Younium__Currency_code__c`) and **Currency** (`CurrencyIsoCode`) | | **Subtotal Amount** | **Subtotal amount** (`Younium__Subtotal_amount__c`) | | **Tax Amount** | **Tax amount** (`Younium__Tax_amount__c`) | | **Total Amount** | **Total amount** (`Younium__Total_amount__c`) | | **Settled amount**; the **Total Amount** when the invoice is *Settled* | **Settled amount** (`Younium__Settled_amount__c`) | | **External ERP Id**, when the org has the field | **ExternalERPId** (`Younium__ExternalERPId__c`) | | The account's **Salesforce Id** (on create) | **Account** (`Younium__Account__c`) | *** ## Product synchronisation ### When it runs Product synchronisation runs when you start it from the Salesforce integration settings in Younium. It is not scheduled. ### What happens A run does four things in order, and stops at the first step that fails: | Step | What happens | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Legal entity and price book | The price book synchronisation below runs first, so the Younium Legal Entity record and the Younium price book exist | | Products | Every charge of every eligible product becomes a Salesforce product, created or updated | | Tiered and volume prices | For tiered and volume charges, one Volume/Tiered Pricing record per tier is created or updated against the Salesforce product | | Price book entries | Each Salesforce product gets price book entries in the standard price book and in the Younium price book, one per currency | The run records when it ran and logs *Exported {n} new products and updated {n} in Salesforce.* in the integration log. A failure is logged as *Couldn't synchronize products* with the reason. A charge with a **Salesforce Product Id** updates that Salesforce product. Before updating, Younium checks that the stored products still exist in Salesforce; a product deleted in Salesforce has its id cleared and is created again. New products are created in batches, and the id of each one is stored in the charge's **Salesforce Product Id** as each batch succeeds, so a failure in a later batch does not lose the ids already created. Tier records follow the same rule: a stored tier record deleted in Salesforce is created again. A product past its **End of sales** date, or whose charge plan is past its **End of sales** date, is sent as inactive, so the product selector no longer offers it. The Younium ids written to each Salesforce product are what the product selector and **Send to Younium** rely on: an opportunity product whose Salesforce product lacks them cannot be sent. ### Price book entries For each Salesforce product, Younium takes one price detail per currency: the one already linked to a price book entry, or otherwise tier 0. | Price book | Entry | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Standard price book | One active entry per product and currency, with unit price 0. Created once; an entry that already exists in Salesforce for that product and currency is left alone | | Younium price book of the legal entity | One active entry per product and currency, carrying the price. Its id is stored in the price detail's **PricebookEntry Id**, and later runs update the unit price | The unit price in the Younium price book is the price detail's **Price**; for tiered and volume charges it is 0, because the tier records carry the prices. When a price detail has no **PricebookEntry Id**, or the stored entry no longer exists in Salesforce, Younium first looks for an existing entry for that price detail by its id on the entry, then for an untagged entry for the same product, currency and price book, and links what it finds before creating a new one. Products shared from a parent legal entity can also be offered in a child legal entity's Younium price book. For those, the child legal entity's entry is found in Salesforce by product and currency each run, and its id is not stored on the parent's price detail. > **Note on failed price book entries:** When creating price book entries fails, the entries created earlier in the same run are deleted from Salesforce again, and the run stops with *Couldn't create custom pricebook entries, please try again or contact Younium support.* Running the synchronisation again starts the entries afresh. The org must have a standard price book; without one the run stops with *Couldn't fetch a Standard Pricebook from Salesforce.* ### Settings | Setting | Description | Default | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | | **Exclude product from Salesforce sync** | Custom field on the Younium product. When selected, none of the product's charges are synchronised. Selecting it later does not remove the product from Salesforce | Not selected | ### Field mapping: product (Younium → Salesforce) Object: Product (`Product2`), one per charge. | Younium Field | Salesforce Field | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Charge **Name** | **Product Name** (`Name`) and **Younium Charge name** (`Younium__Y_Younium_Charge_name__c`) | | Charge **Id** | **Younium Charge ID** (`Younium__Y_Younium_Charge_ID__c`) | | Product **Name** | **Younium Product name** (`Younium__Y_Younium_Product_name__c`) | | Product **Id** | **Younium Product ID** (`Younium__Y_Younium_Product_ID__c`) | | **Charge plan name** | **Younium Charge plan name** (`Younium__Y_Younium_Charge_plan_name__c`) | | Charge plan **Id** | **Younium Charge plan ID** (`Younium__Y_Younium_Charge_plan_ID__c`) | | Charge **Type** (*One-Off* for one-off charges) | **Charge type** (`Younium__Y_Charge_type__c`) | | Charge **Billing period** | **Billing period** (`Younium__Y_Billing_period__c`) | | Charge **Price period** | **Price period** (`Younium__Y_Price_period__c`) | | Charge **Model** | **Charge Model** (`Younium__Charge_model__c`) | | Charge **Model** is tiered | **(Deprecated) Tiered Pricing** (`Younium__Y_Tiered_Pricing__c`) | | Charge **Model** is volume | **Volume Pricing** (`Younium__Y_Volume_Pricing__c`) | | Charge **Unit of measure** | **Unit Of Measure** (`Younium__Unit_Of_Measure__c`) | | The **Legal entity**'s Younium Legal Entity record | **Younium Legal Entity** (`Younium__Legal_entity__c`) | | Not past the product's or charge plan's **End of sales** | **Active** (`IsActive`) | ### Field mapping: product tiers (Younium → Salesforce) Object: Volume/Tiered Pricing (`Younium__Y_VolumeTiered_Pricing__c`), for tiered and volume charges, one per price detail row owned by the connected legal entity. | Younium Field | Salesforce Field | | -------------------------------------- | ----------------------------------------------------------------------------- | | The charge's **Salesforce Product Id** | **Product** (`Younium__Product__c`) | | **Tier** | **Tier** (`Younium__Tier__c`) | | **Description** | **Description** (`Younium__Description__c`) | | **From quantity** | **From Quantity** (`Younium__Minimum_Qty__c`) | | **To quantity** | **To Quantity** (`Younium__Maximum_Qty__c`) | | **Price** | **Price** (`Younium__Price__c`) and **List Price** (`Younium__List_Price__c`) | | **Price base** | **Price Base** (`Younium__Price_Base__c`) | | The charge's **Default quantity** | **Quantity** (`Younium__Quantity__c`) | | **Currency** | **Currency** (`CurrencyIsoCode`) | ### Field mapping: price book entry (Younium → Salesforce) Object: Price Book Entry, the standard Salesforce object. | Younium Field | Salesforce Field | | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | The charge's **Salesforce Product Id** | **Product** (`Product2Id`) | | **Currency** | **Currency** (`CurrencyIsoCode`) | | **Price** (Younium price book; 0 for tiered and volume charges, and 0 in the standard price book) | **List Price** (`UnitPrice`) | | Price detail **Id** (Younium price book) | **Y\_ChargeDetail\_Id** (`Younium__Y_ChargeDetail_Id__c`) | | The standard price book or the legal entity's Younium price book | **Price Book** (`Pricebook2Id`) | | Always active | **Active** (`IsActive`) | | Always off (Younium price book) | **Use Standard Price** (`UseStandardPrice`) | *** ## Price book synchronisation ### When it runs Price book synchronisation runs when you start it from the Salesforce integration settings in Younium, and at the start of every product synchronisation. ### What happens | Step | What happens | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Legal entity record | Younium looks for the Younium Legal Entity record whose **ID** is the legal entity's Younium id. When there is none, it creates one with the legal entity's name and id | | Price book names into Younium | Every price book in the org other than the standard price book is added to the **Pricebook** list in Younium, with the price book's name as the value. In the item's key, commas, full stops and spaces become hyphens. Names already in the list are not added again, and nothing is removed from the list | | Younium price book | Younium makes sure a price book named *Younium-{legal entity name}* exists in Salesforce and is linked to the Younium Legal Entity record, creating it when it is missing | A successful run logs *Price books were synchronized* in the integration log; a failure logs *Couldn't synchronize pricebooks* with the reason. When the legal entity record cannot be found or created, the run stops with *Could not find a younium legal entity in salesforce*. The Younium Legal Entity record is what accounts point to with their **Legal entity** field, so running price book or product synchronisation once is the way to create it for a new connection. > **Note on renaming a legal entity:** The Younium price book is found by its name, *Younium-{legal entity name}*. After a legal entity is renamed in Younium, the next run creates a new price book under the new name, and new price book entries go into it. ### Field mapping: legal entity and price book (Younium → Salesforce) | Younium Field | Salesforce Field | | ------------------------------------------------ | ------------------------------------------------------------------------------- | | **Legal entity** name | **Younium Legal Entities Name** (`Name`) on the Younium Legal Entity | | **Legal entity** id | **ID** (`Younium__ID__c`) on the Younium Legal Entity | | *Younium-* followed by the **Legal entity** name | **Price Book Name** (`Name`) | | The legal entity's Younium Legal Entity record | **Younium Legal Entity** (`Younium__Younium_Legal_Entity__c`) on the price book | *** ## Logs in Salesforce The package records its calls to Younium, and every error Younium returns, as **Younium Log** records with their **Younium Log Entries**, under the **Younium Logs** tab. How much is recorded follows the **Logging Level (NONE, ERROR, INFO)** Younium setting. What Younium itself runs — exports, bulk synchronisations and account imports — is recorded in Younium's integration log instead. --- # 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.younium.com/crm-integrations/salesforce-legacy.md?ask=&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.