action.skip

Automatically Building Subscriptions

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

alt text

The way to set up the subscription builder depends on the nature of your products, your sales use cases 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.

For details, 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.

For details, 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.

For details, 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:

For the purpose of this documentation, we assume the minimum required steps to illustrate the subscription builder setup. For a complete overview of the available options, see Subscription Builder Setup Options.

Info

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 JustOn Support.

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 orders with order products. If set up accordingly, the subscription builder takes the parent object ( order) to produce the subscription, and the child objects ( order products) to produce the subscription items.

In order to create price tiers for items, JustOn also supports subchild relations. You can configure custom objects to hold the price tier information and relate them to the child objects via lookup or master-detail relations. The subscription builder then takes the subchild records to produce the price tiers for the subscription items.

subscr_build_ON_field
Building subscriptions based on accordingly configured objects

Note

When creating price tiers from subchild records, be aware of the following limitations:

  • Some Salesforce objects are not allowed to be the target of a lookup relation, including, for example, Order Product. When using one of these objects to create subscription items, it is not possible to configure a subchild object for creating price tiers.
  • When updating subscriptions automatically, any created price tiers are not included.

The parent object as well as the corresponding child (and, if applicable, subchild) 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.

    API Name 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.
    With Salesforce CPQ installed, make sure to relate to the correct Subscription object. For details, see this article.
    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 example, ON_StartDate. For details, see ON Fields on Objects. For an overview of typically used fields, see Best Practice: Subscription Builder Source Data.

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.

    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 a subscription build filter.
    ON_Quantity Formula (Number) The quantity of the item to be invoiced, required if the detail object is defined in a subscription build filter.
    ON_Title Formula (Text) The name or title of the item, required if the detail object is defined in a 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. For an overview of typically used fields, see Best Practice: Subscription Builder Source Data.

Configuring Subchild Object

The subscription builder uses records of a custom subchild object to create price tiers for an item. This requires a number of ON fields on the subchild object.

  1. Navigate to the fields list of the subchild object.
  2. Create the following new fields.

    API Name 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).

Info

Depending on your use case and its requirements, you can add more price tier-related fields to have them copied to the generated price tier. For details, see ON Fields on Objects and the Tier object.

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 and Items

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.

    Do not assign the subscription to an account. The field Account may be set as required, however. In this case, navigate to the Subscription page layout, open the field properties for the Account field and deselect the Required checkbox.

    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.

    For details, see Creating Subscriptions.

  5. In the Items section of the new subscription, click New.

  6. Specify the details as required.

    Mandatory parameters include

    • Title
    • Billing Type: Recurring, One-Time or Transactional, see General Billing Settings
    • Order No.: Key to match source data to a subscription item
  7. Click Save.

    This generates the new item. Repeat this step for every item to be cloned.

    For details, see Adding Items.

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.

    API Name 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.
    With Salesforce CPQ installed, make sure to relate to the correct Subscription object. For details, see this article.
    ON_SubscriptionBuildError Text (255) Shows the error message in case the subscription creation has failed.
    ON_MasterSubscription Text (255)
    or
    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 example, ON_StartDate. For details, see ON Fields on Objects. For an overview of typically used fields, see Best Practice: Subscription Builder Source Data.

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.

    API Name 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.
    With Salesforce CPQ installed, make sure to relate to the correct Subscription object. For details, see this article.
    ON_SubscriptionBuildError Text (255) Shows the error message in case the subscription creation has failed.
    ON_MappingName Text (255)
    or
    Formula (Text)
    Specifies the name of the file that contains the field mapping definition in JSON.
    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.
    ON_MappingId Text (255)
    or
    Formula (Text)
    Specifies the 18-digit, case-safe Salesforce record ID of the file that contains the field mapping definition in JSON.
    If configured as a formula field, the mapping ID is used for every record.
    ON_Mapping Text Area (Long) Specifies the field mapping definition in JSON.
    Make sure to write all JSON code in a single line without spaces.
    Takes precedence over ON_MappingId and 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).

    For help about creating fields, see Managing Object Fields.

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.

    Make sure to write all JSON code in a single line without spaces.

    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 Files tab.

  3. Click Upload Files.
  4. Select the file using your browser's file selection dialog.
  5. Click Done.

    This makes the mapping definition available for the object configuration and thus for the subscription builder.

    Note

    Be aware that you need the Salesforce record ID as the input parameter for ON_MappingId.

    Find the file record ID in the file URL. To retrieve it, click next to the file record, then select View File Details.

Info

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 various 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.

Note

The subscription build job always processes all available subscription build filters. Be aware that this may, consequently, produce multiple subscriptions for an account.

  1. Click to enter Setup, then 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.

    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 ( plural form). 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 lookup relations, use the relationship name of the child object.
    OrderItems
    CO_Order_Line_Items__r
    Subchild Relation () Specifies the name of the subchild object. Required if you create item price tiers based on custom subchild records.
    For master-detail relations, use the API name of the detail object.
    For lookup relations, use the relationship name of the child object.
    CO_Price_Tiers__r
    Use Case Specifies the filter use case, must be SubscriptionBuilder SubscriptionBuilder
    Condition Specifies a condition (SOQL WHERE clause, see SOQL SELECT Syntax in the Salesforce Help) to restrict the set of included records on batch processing
    Starting with JustOn 2.74, the SOQL expressions in filter conditions must not contain line breaks.
    For details about explicitly excluding/including records, see Excluding Certain Source Records.
    Status = 'Activated'

    For help about creating filters, see Filters.

Adding Subscription Build Button

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

Completing these steps 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.

Note

Be aware that this button will create a subscription for the target object without evaluating any defined filters.

Creating Subscription Build Button

To create the button:

  1. Navigate to the buttons list of the target object.

    In Salesforce Lightning, click to open the Setup menu and select Setup, then open Objects and Fields > Object Manager > Object > Buttons, Links, and Actions.

    In Salesforce Classic, open Setup > Build > Customize > Object > Buttons, Links, and Actions for standard Salesforce objects. For JustOn or custom objects, open Setup > Build > Create > Objects > Object, then scroll to the Buttons, Links, and Actions section.

  2. Click New Button or Link.

  3. Specify the following button details.

    Detail Value
    Label New Subscription
    Display Type Detail Page Button
    Behavior Display in existing window with sidebar
    Content Source URL
    Content /apex/ONB2__NewSubscriptionFromSObject?id={!ObjectAPIName.Id}
    You must replace ObjectAPIName with the API name of your target object.
  4. Click Save.

    For help about creating buttons, see Managing Buttons or Links.

Adding Subscription Build Button to Page

To add the button to the page layout:

  1. Navigate to the page layout definition of the target object.

    In Salesforce Lightning, click to open the Setup menu and select Setup, then open Objects and Fields > Object Manager > Object > Page Layouts.

    In Salesforce Classic, open Setup > Build > Customize > Object > Page Layouts for standard Salesforce objects. For JustOn or custom objects, open Setup > Build > Create > Objects > Object, then scroll to the Page Layouts section.

  2. Click Edit in the row of the layout you intend to modify.

  3. Add the New Subscription button to the page layout.

    In Salesforce Lightning, drag the button from the Mobile & Lightning Actions palette to the Salesforce Mobile and Lightning Experience Actions section.

    In Salesforce Classic, drag the button from the Buttons palette to the Custom Buttons area.

    JustOn ships a global New Subscription button that will not work as expected in the context of your target object. So make sure to select the correct button – check that it has the API name of the button that you have previously created (New_Subscription) and is of the type Custom Button.

    subscr_build_button
    Hovering the New Subscription button in the palette

  4. Click Save.

    For help about modifying page layouts, see Managing Pages.

Scheduling Subscription Build Job

You can set up a job in order to have subscriptions built 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.

Note

The subscription build job always processes all available subscription build filters. Be aware that this may, consequently, produce multiple subscriptions for an account.

Via JustOn's Scheduled Jobs page:

  1. Open the Scheduled Jobs page.

    Use the following URL https://login.salesforce.com/apex/ONB2__JobsSetup, or, if you are already logged in, append apex/ONB2__JobsSetup to your org's domain name.

    As of JustOn 2.52, you can access the Scheduled Jobs page via the JustOn configuration app ( > JustOn Configuration > Jobs Setup).

  2. From the Apex Job drop-down list, select Subscription Builder Job.

    The Job Name field is automatically set to SubscriptionBuilderChain.

  3. From the Start Time drop-down list, select the preferred execution time.

  4. Optionally, edit the displayed cron expression to adjust the execution time.
  5. 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. Click to enter Setup, then 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 Salesforce Developer Console:

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

Creating Flow for Starting Subscription Build

You can set up a custom flow in order to have subscriptions built automatically. For example, you can have the flow triggered when a custom checkbox field on the target object is selected, or when a specific field is set to a certain value.

Note

Depending on your use cases, the flow setup and the objects to involve will vary.

  1. Click to enter Setup, then navigate to Process Automation > Flows.
  2. Click New Flow.
  3. Select Record-Triggered Flow and click Create.
  4. Configure the Start element.

    Option Description
    Object The object whose record modifications are to trigger the subscription build
    Trigger The type of record change that triggers the flow
    Conditions The use case-specific trigger conditions, one or more filter criteria for evaluating certain field values
    Optimize for Actions and Related Records
  5. Click and add the following Action element.

    Option Description
    Action The Apex class to call, must be Build Subscription
    Input Values Invocable variables for the Apex class
    Filter: the (plain) name of the subscription build filter
    Object Id: the ID field of the relevant target object, like {!$Record.Id}

    Specify a label and an API name as required.

  6. Click Save.

    Specify a label and an API name as required.

  7. Click Activate.

    When the defined conditions are met, JustOn creates or updates the corresponding subscription, depending on the applicable subscription builder use case.

    For help about creating flows, see Flows in the Salesforce Help.

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 Salesforce Platform 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_MappingId__c":"Salesforce Id",
            "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_MappingId__c":"Salesforce Id",
            "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.