Subscription Builder Setup Options
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,
- build subscriptions based on accordingly configured parent-child objects, or
- build subscriptions based on a data mapping.
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. 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 | 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. |
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. | |
ON_EndDate | Formula (Date) | The service period end of the item. | |
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. |
Info
Depending on your use case and its requirements, you can add more fields to have them copied to the generated subscriptions. For details, see ON Field Mechanism.
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
.
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 (Default or Flat ). |
|
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. | |
ON_EndDate | Formula (Date) | Specifies the last day of the validity period of this tier. | |
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, which are set in the field ON_UseCase
on the source record:
If the field ON_UseCase
is missing or not set, the use case is determined automatically.
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 must 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 any new products, but also credit items for products to be refunded, and the existing subscription terminates.
NEW
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
REORDER
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 new subscription is empty
UPGRADE
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 new subscription 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
- the item is not excluded by
ON_ExcludeFromUpgrade__c
(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
Assigning Items to a Related Subscription
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
Info
The automatic subscription update functionality is available as of JustOn 2.43.
Certain business use cases require existing subscriptions or subscription items to be updated, for example, after the value of a source object field has changed.
Enabling subscription update involves the following tasks:
(1) Add the fields ON_UpdateSubscription
and ON_LastSubscriptionUpdate
to the source object (see ON Fields on Objects).
(2) Define the target fields to be updated, either
- Setting up a data mapping using
fieldsToUpdate
(see Using Data Mapping) and configuringON_MappingName
,ON_MappingId
orON_Mapping
on the source object, or - Alternatively, configuring the field
ON_FieldsToUpdate
on the source objects (see ON Fields on Objects)
Info
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 process for selecting ON_UpdateSubscription
This example assumes that you build subscriptions based on contracts. Any modification to a contract record is to select the field Update Subscription
and hence, trigger an update.
Note that depending on your use cases, the process setup and the objects to involve will vary. You can, for example, set conditions for monitoring specific fields for changes.
Option | Value |
---|---|
The process starts when | A record changes |
Object | Contract |
Start the process | when a record is created or edited |
Criteria for Executing Actions | No criteria - just execute the actions! |
Action Type | Update Records |
Record Type | Contract |
Criteria for Updating Records | No criteria - just update the records! |
Set new field values for the records you update | Field: Update Subscription Type: Boolean Value: True |
(3) Optionally, enable the creation of new items from new child records by either
-
Configuring 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. -
Alternatively, setting up the data mapping
addNewChildren
like"addNewChildren":"true"
and configuring
ON_MappingName
,ON_MappingId
orON_Mapping
on the source object
Info
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 to be updated as specified in the corresponding mapping fieldsToUpdate
or the field ON_FieldsToUpdate
. 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.
Info
The source record tracking functionality is available as of JustOn 2.48.1.