Skip to content

Automatically Building Subscriptions

Automatic subscription building helps managing subscriptions if your business requires to deal with a large or variable (increasing) number of subscriptions.

The way to set up the subscription builder depends on the nature of your products and the representation of your source data in Salesforce:

Remember that subscriptions and their items are in a parent-child relationship. So if your source data is stored in a parent-child relationship, like opportunities and opportunity products, for example, you can set up these objects to produce the subscriptions based on the parent object and the subscription items out of its child objects. Since these objects (opportunities, orders, etc.) usually are account-specific, you can, this way, bill an account-specific set of products under some account-specific conditions.
▶ See Setting Up Parent-Child Objects

Now assume that you bill identical products on equal conditions to multiple accounts. In this case, your source data may reside on a single object - there is just the account or a contract that holds all information. In this context, JustOn recommends to make use of master subscriptions - subscription "models" that already include the items and that are copied for each target object.
▶ See Setting Up Master Subscriptions

Finally, there may be data in addition to the configured fields for master subscriptions or objects in a parent-child relationship, or from customized source objects whose records hold all information. If you need to create or update subscriptions based on this data, which is not accessible otherwise, you set up specific data mappings to retrieve it.
▶ See Setting Up Data Mapping

Info

You can combine multiple sources, providing the corresponding setup.

In a nutshell, setting up JustOn to automatically create subscriptions comprises the following major tasks:

Note

You must configure the subscription builder depending on the nature of your business and your source data. If necessary, you can combine multiple sources, providing the corresponding setup.

For further help with setting up the subscription builder, contact the JustOn support team.

Info

For the purpose of this documentation, we assume the minimum required steps to illustrate the subscription builder setup. For a complete overview of the subscription builder setup options, see here.

Setting Up Parent-Child Objects

To allow for individually configured items when building subscriptions, you can use objects that are in a parent-child relationship, like opportunities with opportunity products. If set up accordingly, the subscription builder takes the parent object (■ opportunity) to produce the subscription, and the child objects (■ opportunity products) to produce the subscription items.

subscr_build_ON_field
Building subscriptions based on accordingly configured objects

Both the parent object and the corresponding child objects require a number of ON fields. Hence, building subscriptions based on configured objects requires the following setup tasks:

Configuring Parent Object

The subscription builder requires a number of ON fields on the parent object.

  1. Navigate to the fields list of the parent object.
  2. Create the following new fields.
    For help about creating fields, see Managing Object Fields.
API Name Data Type Description
ON_Account Lookup (Account)
Formula (Text)
Links to the related account.
Specifies the Salesforce account ID or external ID.
When using a formula, the mapping formula is CASESAFEID(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_CurrencyIsoCode Formula (Text) Sets the subscription currency to the source object currency if
a) you use multiple currencies and
b) the account currency differs from the source object currency.
The formula is TEXT(CurrencyIsoCode).

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 Fields on Objects.

Configuring Child Object

The subscription builder requires a number of ON fields on the child object.

  1. Navigate to the fields list of the child object.
  2. Create the following new fields.
    For help about creating fields, see Managing Object Fields.
API Name 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.

Info

Depending on your use case and its requirements, you can add more fields to have them copied to the generated subscription items. For details, see ON Fields on Objects.

Next steps:

Enabling Subscription Generation

Setting Up Master Subscriptions

A master subscriptions is a subscription "model" that is copied for each target. The target is the object whose records are the basis for subscriptions, like accounts, contracts, cases, quotes, etc. If set up accordingly, the subscription builder can generate an individual subscription for each new account, contract, case, quote, etc. that you create.

subscr_build_master_subscr
Building subscriptions based on a master subscription

Building subscriptions based on master subscriptions requires the following setup tasks:

Creating Master Subscription

Basically, a master subscription is a usual subscription that is not assigned to an account. That is, you just create a subscription, add all items and define any required conditions to be cloned, but do not assign it to an account.

  1. Open the Subscriptions tab.
  2. Click New.
  3. Specify the details as required.
    Add the required items and define the required conditions.
    Do not assign the subscription to an account.
    The subscription name will be used as an input parameter when configuring the target object. JustOn recommends to prefix the master subscription name with MASTER.
  4. Click Save.

Info

For details, see Creating Subscriptions

Configuring Target Object

The subscription builder requires a number of ON fields on the target object.

  1. Navigate to the fields list of the target object.
  2. Create the following new fields.
    For help about creating fields, see Managing Object Fields.
API Name Data Type Description
ON_Account Lookup (Account)
Formula (Text)
Links to the related account.
Specifies the Salesforce account ID or external ID.
When using a formula, the mapping formula is CASESAFEID(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
Specifies the name of the master subscription (which serves as a template and will be cloned).
If configured as a formula field, the master subscription name is used for every record.

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 Fields on Objects.

Next steps:

Enabling Subscription Generation

Setting Up Data Mapping

Data mappings allow for retrieving the data required for creating or updating subscriptions and their items from virtually any fields of any objects. Generally, you can apply mappings to get data

  • in addition to the configured fields when using master subscriptions or objects in a master-detail relationship, or
  • from customized source objects whose records hold all (variable) information for creating subscriptions and items.

subscr_build_mapping Building subscriptions based on a mapping

Building subscriptions based on data mapping requires the following setup tasks:

Configuring Source Object

The subscription builder requires a number of ON fields on the source object.

  1. Navigate to the fields list of the source object.
  2. Create the following new fields.
    For help about creating fields, see Managing Object Fields.
API Name Data Type Description
ON_Account Lookup (Account)
Formula (Text)
Links to the related account.
Specifies the Salesforce account ID or external ID.
When using a formula, the mapping formula is CASESAFEID(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_MappingName Text (255)
Formula
Specifies the name of the document that contains the field mapping definition in JSON.
If configured as a formula field, the mapping name is used for every record.
ON_Mapping Text Area (Long) Specifies the field mapping definition in JSON.
Takes precedence over ON_MappingName.
ON_CurrencyIsoCode Formula (Text) Sets the subscription currency to the source object currency if
a) you use multiple currencies and
b) the account currency differs from the source object currency.
The formula is TEXT(CurrencyIsoCode).

Creating Mapping Definition

The field mapping is defined in JSON notation and can either be stored as a Salesforce document or directly in a field on the record that is to be invoiced. See also Configuring Source Object.

To save the data mapping directly on the object:

  1. Navigate to the fields list of the source object.
  2. Click Edit in the row of the ON_Mapping field.
  3. Specify the mapping definition in the text area.
    For details about the mapping definition, see Using Data Mapping.
  4. Click Save.
    ▶ This makes the mapping definition available for the invoice builder.

To refer to the data mapping saved as a document:

  1. Create the mapping definition and save it as a file.
    For details about the mapping definition, see Using Data Mapping.
  2. Open the Salesforce Documents tab.
    The Documents tab is accessible in the Salesforce Classic UI only.
  3. Click New.
  4. Specify the details as required and upload the mapping definition file.
    For details, see Upload and Replace Items on the Documents Tab in the Salesforce Help.
    Note that the document record name will be used as an input parameter for ON_MappingName.
  5. Click Save.
    ▶ This makes the mapping definition available for the object configuration and thus for the subscription builder.

Tip

Use a JSON validator before uploading the mapping to Salesforce.

Next steps:

Enabling Subscription Generation

Enabling Subscription Generation

Irrespective of the configured data source for the subscription build, you must create a subscription build filter.

Once set up, there are three ways to invoke the subscription building process:

Creating Subscription Build Filter

To define which objects and records to include in the subscription build process, you create a new custom filter.

  1. In Setup, open Custom Settings.
    In Salesforce Lightning, navigate to Custom Code > Custom Settings.
    In Salesforce Classic, navigate to Develop > Custom Settings.
  2. Click Manage in the row of Filters.
  3. Create the following filter for the subscription build.
    For help about creating filters, see Filters.
Field Required Description Example Value
Name Specifies the filter name, will be available as an option picklist value when triggering the operation
Target Specifies the API name of the target object Order
Opportunity
MyObject__c
Child Relation (✓) Specifies the name of the child object. Required if you create items based on the child records.
For master-detail relations, use the API name of the detail object. In case of standard Salesforce objects, you can use Workbench to find the correct name.
For parent-child relations, use the relationship name of the child object.
OrderItems
CO_Order_Line_Items__r
Use Case Specifies the filter use case, must be SubscriptionBuilder SubscriptionBuilder
Condition Specifies a condition (SOQL WHERE clause) to restrict the set of included records
For details, see SOQL SELECT Syntax in the Salesforce Help.
Status = 'Activated'

Adding Subscription Build Button Component (Salesforce Lightning)

To add a new button for manual subscription generation to the record detail page in Salesforce Lightning:

  1. Open a record detail page of the target object.
    Navigate to a contract, opportunity, account, etc. as required.
  2. Click cog in the upper right corner to open the Setup menu, then select Edit Page.
  3. Drag the custom Lightning component NewSubscriptionFromSObject to the intended region of the record page.
  4. Click Save, then Activate.
    For details about editing Lightning pages, see Create and Configure Lightning Experience Record Pages in the Salesforce Help.

▶ This allows you to manually trigger the subscription build process from the detail page of the configured target object (account, contract, case, quote, etc.) by clicking the New Subscription button.

Creating Subscription Build Button (Salesforce Classic)

Adding a new button for manual subscription generation involves two steps:

  • Creating the button
  • Adding the button to the record detail page

To create the button:

  1. Navigate to the Buttons, Links, and Actions page of the target object.
  2. Create the following button.
    For help about creating buttons, see Managing Buttons or Links.
Detail Value
Label For example, New Subscription
Display Type Detail Page Button
Behavior Execute JavaScript
Content Source OnClick JavaScript
Content window.location.href = '/apex/ONB2__NewSubscriptionFromSObject?id={!ObjectAPIName.Id}';
You must replace ObjectAPIName with the API name of your target object.

To add the button to the page layout:

  1. Navigate to the page layout definition of the target object.
  2. Add the new button to the page layout.
    For help about modifying page layouts, see Managing Page Layouts.

▶ This allows you to manually trigger the subscription build process from the detail page of the configured target object (account, contract, case, quote, etc.).

Scheduling Subscription Build Job

You can set up a job in order to have subscriptions build automatically on a regular basis.

The subscription build job does not require additional parameters. That is, you can set up the job directly for the corresponding batch chain SubscriptionBuilderChain. For details, see Scheduling Concepts.

To schedule the subscription build batch chain, you can use either JustOn's Scheduled Jobs page or Salesforce's Schedule Apex functionality. For details, see Scheduling a Job.

Via JustOn's Scheduled Jobs page:

  1. Open the Scheduled Jobs page.
    Open the JobsSetup page directly, or navigate to Visualforce Pages > JobsSetup in Setup, and open the preview.
  2. From the Apex Job drop-down list, select Batch Chain Job.
  3. In the Job Name field, specify SubscriptionBuilderChain.
  4. From the Start Time drop-down list, select the preferred execution time.
  5. Optionally, edit the displayed cron expression to adjust the execution time.
  6. Click Schedule.
    ▶ This sets up the subscription build to be executed at the specified time.

Info

From the Scheduled Jobs page, you can also run the batch chain immediately.

Via Salesforce's Schedule Apex functionality:

  1. In Setup, open Apex Classes.
    In Salesforce Lightning, navigate to Custom Code > Apex Classes.
    In Salesforce Classic, navigate to Develop > Apex Classes.
  2. Click Schedule Apex on top of the list.
  3. Specify the details as required.
    • Job Name: SubscriptionBuilderChain
    • Apex Class: ScheduledBatchChain
    • Frequency: Weekly or Monthly (with an according weekday or day of month setting)
    • Start
    • End
    • Preferred Start Time
  4. Click Save.
    ▶ This sets up the subscription build to be executed at the specified time.

For more details about job scheduling, see Scheduling a Job in the JustOn documentation and Schedule Apex in the Salesforce Help.

You can also invoke the subscription builder using the following code in the Force.com Developer Console (see Developer Console Functionality in the Salesforce Help):

new ONB2.ChainRunner()
.execute(
    new ONB2.ChainFactory().getByName('SubscriptionBuilderChain')
);

Calling Subscription Build Web Service

Some business use cases may require to invoke the subscription builder remotely from external systems. To this end, you can call the subscription builder using a REST web service. The web service accepts one ore more records and creates subscriptions in the same way as the local batch job.

API URL

The web service is available via

https://INSTANCE.salesforce.com/services/apexrest/ONB2/subscription_builder/1/

Replace INSTANCE with the actual Salesforce instance or custom domain where JustOn is installed and running.

Authentication

The web service supports two authentication mechanisms:

  • OAuth 2.0
  • Session ID

For details, see Step Two: Set Up Authorization in the Force.com REST API Developer's Guide.

JSON Structure for Web Service Call

The web service accepts HTTP POST requests. The body of the request must contain a valid JSON data structure. Basically, the JSON structure represents a deserialized sObject and lists a number of records. The keys are mapped to field names of the subscription or the item.

Info

The JSON code can also include child records.

The key ON_Account__c is mandatory at the parent record. It can refer to a Salesforce ID or an external ID. When referring to an external ID, you must also refer to an existing mapping that holds the externalIdFields variable for Account__c (see externalIdFields). The keys ON_MasterSubscription__c, ON_MappingName__c and ON_UseCase__c on the parent record are used in the same way as for accordingly configured objects (see ON Fields on Objects).

Keys that start with ON_ are directly mapped to subscription or item fields. Fields without the ON_ prefix can only be referenced and used by a corresponding mapping (see Using Data Mapping).

[
    {
        "parent":{
            "ON_Name__c":"Sample Name 1",
            "ON_Account__c":"Sample External Id 1",
            "ON_MasterSubscription__c":"Master Subscription Name",
            "ON_MappingName__c":"Mapping Name",
            "ON_UseCase__c":"NEW",
            "ON_StartDate__c":"2015-12-01",
            "ON_Template__c":"Salesforce Template Id"
        },
        "children":{
            "SUBSCRIPTION_FEE":{
                "ON_Name__c":"SUBSCRIPTION_FEE",
                "ON_Price__c":47.11,
                "ON_Quantity__c":1,
                "ON_BillingType__c":"Recurring"
            },
            "SUPPORT_HOURS":{
                "ON_Name__c":"SUPPORT_HOURS",
                "ON_Price__c":100.0,
                "ON_BillingType__c":"Transactional"
            }
        }
    },
    {
        "parent":{
            "ON_Name__c":"Sample Name 2",
            "ON_Account__c":"Salesforce Account Id",
            "ON_MasterSubscription__c":"Other Master Subscription Name",
            "ON_MappingName__c":"Mapping Name",
            "ON_Status__c":"Active",
            "ON_Template__c":"External Template Id",
            "ON_Contact__c":"External Contact Id"
        }
    }
]

Web Service Response

The response of the web service holds a result record for each record from the request:

[
    {
        "success":true,
        "subscriptionId":"Salesforce Id",
        "buildError":null,
        "index":0
    },
    {
        "success":true,
        "subscriptionId":"Salesforce Id",
        "buildError":null,
        "index":1
    }
]

The response always returns the HTTP status code 200 once the body of the request can be successfully parsed. Otherwise, the system will return an HTTP status code 500 with the error in the body of the response. For details about possible HTTP status codes, see RestResponse Class in the Apex Developer Guide.

Error Handling

If the subscription build fails before the database insert (like, for example, with a missing account, a missing mapping, or a missing master subscription), it is marked as failed. Other subscriptions passed with the same request may still succeed, however.

If the error occurs during the database insert, all subscriptions of the request will fail:

[
    {
        "success":false,
        "subscriptionId":null,
        "index":0,
        "buildError":"Batch persisting of Subscriptions failed."
    },
    {
        "success":false,
        "subscriptionId":null,
        "index":1,
        "buildError":"Item upsert: Name=SUBSCRIPTION_FEE : REQUIRED_FIELD_MISSING: Required fields are missing: [ONB2__Title__c]; fields  [ONB2__Title__c]"
    },
    {
        "success":false,
        "subscriptionId":null,
        "index":2,
        "buildError":"Batch persisting of Subscriptions failed."
    }
]

Return to JustOn Administration.