action.skip

Controlling Subscription Builder Setup Options

← Setting Up Billing Automation

This document summarizes the subscription builder setup options, irrespective of your business model and your source data.

When generating subscriptions and their corresponding subscription items, the subscription builder always evaluates multiple sources in the following order:

  • specific mapping documents
  • records of accordingly configured parent-child objects
  • remote data received by a REST web service
  • preconfigured master subscriptions

Thanks to this approach, you can combine multiple sources, providing the corresponding setup.

Info

For an introduction to the subscription builder and details about how to set it up, see Automatically Building Subscriptions.

ON Fields on Objects

The subscription builder requires a number of ON fields on objects if you build subscriptions based on master subscriptions, based on accordingly configured parent-child objects, or based on a data mapping.

Subscription Source Fields

For target objects (with master subscriptions) and parent objects (of a parent-child relationship), the following fields are available:

API Name Required Data Type Description
ON_Account Formula (Text) Specifies the Salesforce account ID or external ID.
The formula uses the API name of the field that links the object to the account, for example, AccountId.
ON_Subscription Lookup (Subscription) Links to the related subscription.
ON_SubscriptionBuildError Text (255) Shows the error message in case the subscription creation has failed.
ON_MasterSubscription Text (255)
Formula (Text)		 Required when using a master subscription. Specifies the name of the master subscription.
If configured as a formula field, the master subscription name is used for every record.
ON_MappingName Text (255)
Formula (Text)		 Specifies the name of the file that contains the field mapping in JSON to define the data to be retrieved.
If configured as a formula field, the mapping name is used for every record.
Deprecated, accessible via the Documents tab in the Salesforce Classic UI only. Use ON_MappingId instead.
When using the data mapping to build or update subscriptions, either ON_MappingName or ON_Mapping is required.
ON_MappingId Text (255)
Formula (Text)		 Specifies the 18-digit, case-safe Salesforce record ID of the file that contains the field mapping in JSON to define the data to be retrieved.
If configured as a formula field, the mapping ID is used for every record.
When using the data mapping to build or update subscriptions, either ON_MappingId or ON_Mapping is required.
ON_Mapping Text Area (Long) Specifies the field mapping in JSON to define the data to be retrieved.
Make sure to write all JSON code in a single line without spaces.
Takes precedence over ON_MappingId and ON_MappingName.
When using the data mapping to build or update subscriptions, either ON_MappingId or ON_Mapping is required.
ON_CurrencyIsoCode Formula (Text) Sets the subscription currency to the parent object currency if
a) you use multiple currencies and
b) the account currency differs from the parent object currency.
The formula is TEXT(CurrencyIsoCode).
ON_UseCase Text
Formula (Text)
Picklist		 Defines the use case (NEW, UPGRADE, REORDER) to create or modify the subscription. If the field is missing or not set, the use case is determined automatically.
ON_ExcludeFromUpgrade Formula (Text)
Text (255)		 Specifies items to exclude from being cloned and moved to the new subscription during UPGRADE. Expects a comma-separated list of order numbers.
ON_RelatedSubscription Lookup (Subscription)
Formula (Text)		 Specifies the related subscription, which can be used with the UPGRADE or REORDER use cases. This is useful if there are multiple active subscriptions available on the account.
ON_SubscriptionBuilderCriterion Formula (Text)
Text (255)		 The criterion provides an alternative way to specify the target subscription for UPGRADE or REORDER use cases (see also ON_RelatedSubscription): Source records will be matched to subscriptions with the same criterion in ONB2__SubscriptionBuilderCriterion__c.
ON_UpdateSubscription Checkbox Controls whether the already generated subscription linked by ON_Subscription is to be updated. Must be set by the user or a process.
After the update, the value is unchecked.
ON_FieldsToUpdate Text
Formula (Text)		 Specifies the subscription fields to be updated. Expects a comma-separated list of fields, like StartDate__c,EndDate__c.
If configured as a formula field, the mapping name is used for every record.
When using the subscription update, either a data mapping (specified using ON_MappingId or ON_Mapping) or this list of fields is required.
ON_AddNewChildren Checkbox Controls whether to create new items from new child records upon subscription update.
ON_LastSubscriptionUpdate DateTime Shows the time of the last update. Is set automatically when the subscription is updated.
ON_BalanceAssignmentKey Text
Formula (Text)		 Key to match invoices with pre-payment balances of the same source. Set on subscription build, to be copied to the invoice on invoice generation.

Item Source Fields

For child objects (of a master-detail relationship), the following fields are available:

API Name Required Data Type Description
ON_OrderNo Formula (Text) Key to match source data to a subscription item, must be unique for each detail of the same master.
ON_Price Formula (Currency) The net sales price of the item, required if the detail object is defined in subscription build filter.
ON_Quantity Formula (Number) The quantity of the item to be invoiced, required if the detail object is defined in subscription build filter.
ON_Title Formula (Text) The name or title of the item, required if the detail object is defined in subscription build filter.
ON_StartDate Formula (Date) The service period start of the item.
If the referenced field is of the type Date/Time, the operator DATEVALUE must precede the referenced field, like DATEVALUE(<datetime_field>).
ON_EndDate Formula (Date) The service period end of the item.
If the referenced field is of the type Date/Time, the operator DATEVALUE must precede the referenced field, like DATEVALUE(<datetime_field>).
ON_BillingType Formula (Text)
Picklist		 Specifies whether the object is invoiced once, on a recurring or a transactional base; possible values include One-Time, Recurring, Transactional.
ON_BillingPeriod Formula (Number) Specifies the time interval (in months) for the item to be considered in an invoice run.
ON_BillingUnit Formula (Text)
Picklist		 Specifies the time frame (Day or Month) used for the price calculation of the billing period
ON_FieldsToUpdate Text
Formula (Text)		 Specifies the item fields to be updated. Expects a comma-separated list of fields, like Title__c,Quantity__c,Price__c.
If configured as a formula field, the mapping name is used for every record.
When using the subscription update, either a data mapping (specified using ON_MappingId or ON_Mapping) or this list of fields is required.
ON_InvoiceLineItemType Text(255)
Formula(Text)		 Specifies the type of the invoice line item to be built from the subscription item.

Info

Depending on your use case and its requirements, you can add more fields to have them copied to the generated subscriptions or items, like, for example, ON_StartDate. For an overview of typically used fields, see Best Practice: Subscription Builder Source Data.

ON fields are directly mapped to the subscription or item fields. Fields that are not starting with ON_ can only be referenced and used by a data mapping, or, in case of subscription updates, via the field list in ON_FieldsToUpdate.

Tier Source Fields

For subchild objects (of a lookup relationship or a master-detail relationship), which are used to create price tiers or commission tiers, the following fields are available:

API Name Required Data Type Description
ON_Quantity Formula (Number) Specifies the item quantity until which the price defined in this tier is valid. If left empty, the defined tier price is valid for all quantities. Tiers are sorted by quantity with empty values last.
ON_Price Formula (Currency) Specifies the price to apply to quantities within the range of this tier. If left empty, the tier is not considered in the price lookup.
ON_Type Formula (Text) Specifies the price calculation method of this item for the current price tier (Default or Flat, see Price Tiers).
ON_Target Formula (Text) Specifies the target of this tier (Price or Commission).
ON_Commission Formula (Percent) The commission (percentage value) to apply to the price.
ON_StartDate Formula (Date) Specifies the first day of the validity period of this tier.
If the referenced field is of the type Date/Time, the operator DATEVALUE must precede the referenced field, like DATEVALUE(<datetime_field>).
ON_EndDate Formula (Date) Specifies the last day of the validity period of this tier.
If the referenced field is of the type Date/Time, the operator DATEVALUE must precede the referenced field, like DATEVALUE(<datetime_field>).
ON_SplitQuantity Formula (Checkbox) Specifies whether the item is to be split into a new invoice line item when it exceeds the quantity defined in this tier. Can be used for scaled prices or if you want to state a basic charge separately.

Use Cases

The subscription builder supports three different use cases for the subscription building. They map typical sales use cases:

Use Case Description
NEW Creates a new subscription.
REORDER Creates new items and adds them to an existing subscription. If there is no existing subscription, it builds a new subscription.
Adding a new child source record to an existing parent source record is covered with the subscription update including the option to create new items.
UPGRADE Creates a new subscription, sets an end date on the existing subscription and sets its status to Upgraded. Certain items (active, not already available, not excluded, matching service period) of the existing subscription are cloned and added to the new subscription.

Creates a new subscription.

NEW is set automatically if all of the following conditions are true:

  • the use case is empty
  • there is no existing active subscription for the target account

subscription_build_new

Creates new items and adds them to an existing subscription. If there is no existing subscription, it builds a new subscription.

REORDER is set automatically if all of the following conditions are true:

  • the use case is empty
  • there is exactly one existing active subscription for the target account
  • the start date of the source record (→ the new subscription) is empty

Adding a new child source record to an existing parent source record is covered with the subscription update including the option to create new items.

subscription_build_reorder

Creates a new subscription, sets an end date on the existing subscription and sets its status to Upgraded. The new subscription relates to the original subscription via the field Previous Subscription.

UPGRADE is set automatically if all of the following conditions are true:

  • the use case is empty
  • there is exactly one existing active subscription for the target account
  • the start date of the source record (→ the new subscription) is set, that is, not empty

Items of the existing subscription are cloned and added to the new subscription if all of the following conditions are true:

  • the item is not already available in the new subscription (according to the value of ON_OrderNo)
  • the item is not excluded by ON_ExcludeFromUpgrade (see ON Fields on Objects)
  • the item is active
  • the end date of the item is empty or after the start date of the new subscription

subscription_build_upgrade

JustOn can automatically determine and apply the subscription builder use cases if the relevant conditions are true and the field ON_UseCase is missing or not set.

Your business may, however, require to force a certain use case. In this case, use the field ON_UseCase on the subscription source record. This can be formula that determines the use case to set according to certain conditions, a picklist or a fixed value. If, for example, your sales use case will never need the subscription builder use case UPGRADE, you can set REORDER as a fixed value – this will update an existing subscription or create a new one if there is none.

Use cases example

To illustrate the use cases, assume the following example: You sell phone contracts, and you keep track of your deals using opportunities. For each opportunity you generate a subscription, which is finally invoiced.

When you close a deal with a new customer, the new (or updated) opportunity triggers the creation of a new subscription. This is covered with the use case NEW.

Now an existing customer orders an additional service, which you add as a new opportunity product on a new opportunity. This opportunity product becomes a new subscription item on the existing subscription. This is the use case REORDER – you add new subscription items, leaving the existing in place.

If, however, the customer decides to upgrade the calling plan, you usually refund the amount that is already paid for the rest of the current contract term. This is where you apply the use case UPGRADE: you create a new subscription that includes items for new products as well as credit items for products to be refunded, and the existing subscription terminates.

If you work with multiple active subscriptions, the use cases REORDER or UPGRADE require the items to be assigned to the related subscription. To this end, set a value in the field ON_RelatedSubscription on the configured target or master object (see ON Fields on Objects). If the field is empty on the first use, the subscription builder creates a new subscription and inserts the subscription ID of the new object. In a subsequent subscription build process, the related subscription is then identified by the value in the field, and the item is assigned to the related active subscription.

Reasons for multiple active subscriptions can be:

  • doing customer business with different clients via business entities,
  • setting different payment due terms for the items (on one invoice, all items must have an identical payment due),
  • offering several invoices to a customer for specific products

Enabling Subscription and Subscription Items Update

Certain business cases require automatically updating existing subscription fields or subscription item fields after the subscription has been built (applying one of the subscription builder use cases). This may be necessary, for example, after the value of a source object field has changed.

To enable the automatic subscription update:

  1. Add the fields ON_UpdateSubscription and ON_LastSubscriptionUpdate to the source object.

    Navigate to the fields list of the source object and create the fields as follows:

    API Name Data Type Description
    ON_UpdateSubscription Checkbox Must be selected (by a user or a flow) for the subscription to be updated.
    Is cleared automatically after completing the update.
    ON_LastSubscriptionUpdate DateTime Is set automatically when the subscription is updated.

    For details, see ON Fields on Objects.

    Depending on your business requirements, you can either have users select the checkbox ON_UpdateSubscription manually, or create a custom process to have it set automatically when certain conditions apply.

    Make sure not to create the checkbox ON_UpdateSubscription as a formula field. Doing so would produce errors when executing the subscription builder.

    Example flow for selecting ON_UpdateSubscription

    This example assumes that you build subscriptions based on orders. A modification to the order amount is to select the field Update Subscription and hence, trigger an update.

    Note that depending on your use cases, the flow setup, the objects to involve or the fields to watch as conditions will vary.

    Flow Element Option Example Value
    Start Object Order
    Trigger A record is updated
    Conditions Any Condition Is Met (OR)
    TotalAmount Is Changed {!$GlobalConstant.True}
    Update Records How to Find Records to Update and Set Their Values Use the record that triggered the flow
    Condition Requirements to Update Record None -- Always Update Record
    Set Field Values for the Order Record Field: ON_UpdateSubscription__c
    Value: {!$GlobalConstant.True}

  2. Define the target fields to be updated.

    To do so, you can either

    • Set up a data mapping using fieldsToUpdate (see Using Data Mapping) and configure ON_MappingName, ON_MappingId or ON_Mapping on the source object, or
    • Alternatively, configure the field ON_FieldsToUpdate on the source objects (see ON Fields on Objects)

  3. Optionally, enable the creation of new items from new child records.

    To do so, you can either

    • Configure the field ON_AddNewChildren on the parent source object (see ON Fields on Objects)

      JustOn evaluates the value of ON_OrderNo to decide whether to update an existing item or to create a new item: With an existing key, JustOn updates the corresponding item, whereas with a new one, it creates a new item.

      Example flow for selecting ON_AddNewChildren

      This example assumes that you build subscriptions and items based on orders and order products. Creating a new billable order product (or modifying an existing order product to make it billable) is to create a new item when updating the subscription.

      Note that depending on your use cases, the objects to involve or the flow setup (conditions, etc.) will vary.

      Flow Element Option Value
      Variable API Name OrderId
      Data Type Text
      Default Value {!$Record.Order.Id}
      Start Object Order Product
      Trigger A record is created or updated
      Conditions All Conditions Are Met (AND)
      1: ListPrice Is Changed {!$GlobalConstant.True}
      2: ListPrice Greater Than 0
      Assignment Variable Values OrderId Equals {!$Record.Order.Id}
      Get Records Object Order
      Filter Order Records All Conditions Are Met (AND)
      ID Equals {!OrderId}
      Update Records How to Find Records to Update and Set Their Values Specify conditions to identify records, and set fields individually
      Update Records of This Object Type Order
      Filter Order Records All Conditions Are Met (AND)
      ID Equals {!Get_Order.Id}
      Set Field Values for the Order Records ON_AddNewChildren__c {!$GlobalConstant.True}

    • Alternatively, set up the data mapping addNewChildren like

      "addNewChildren":true

      and configure ON_MappingName, ON_MappingId or ON_Mapping on the source object

Once set up, selecting the checkbox ON_UpdateSubscription triggers the automatic subscription update. The subscription builder "simulates" the use case NEW and copies the fields selected to be updated. After completing the update, the subscription builder deselects the checkbox ON_UpdateSubscription and sets a date in ON_LastSubscriptionUpdate.

Keeping Track of Source Records

Certain business use cases require keeping track of the source records based on which a subscription and its items have been created, for example, when updating subscriptions. To this end, there are two source fields on the item: SourceParentId and SourceChildId. JustOn automatically fills these fields during the subscription build process.

Once set, the fields keep track of the item's source records. This allows for unequivocally identifying multiple items with the same OrderNo. Following the subscription update example, JustOn only updates items whose values for SourceParentId match the IDs of the parent objects.

Excluding Certain Source Records

Assume that you want to exclude specific source records from being subject to the automatic subscription build based on certain conditions.

JustOn recommends to use a custom field on the source object that is then to be used as an exclude (or include) condition in the subscription build filter. In the easiest way, this custom field is a checkbox that is set using a formula or a flow based on your requirements.

Note

We advise against using validation rules to exclude source records from subscription building. Validation rules are a powerful means to ensure data quality, but this is not your goal here – you just want to set and check one condition. Besides, validation rules may have a considerable performance impact and may have unwanted effects on other business processes.

Think of the following example:

You build subscriptions from opportunities. Usually, the opportunity state is the perfect trigger to invoke the subscription builder: you define a corresponding condition in your subscription build filter. The condition is an expression (as used in an SOQL WHERE clause) that restricts the set of involved records, like Status = 'Activated' – this makes sure that only opportunities of the state Activated will be subject to the subscription build.

The opportunity state, however, may not be enough. Assume you want to exclude opportunities of a certain account. In this case, you add an exclude condition to the filter, like Status = 'Activated' AND ON_Account__c != '<ID>'.

Now assume you want to apply some custom logic to set a "trigger field" based on certain conditions. You create a custom checkbox, like Billable, to include only records where the checkbox is selected, excluding records where the checkbox is not selected. To cover this, your subscription build filter sets this condition: Status = 'Activated' AND Billable__c = true.

Info

You can set up the checkbox as a formula field or use Salesforce flows to have the checkbox selected automatically. This way, you can apply additional logic to determine whether a record is subject to the subscription build or not.