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.

    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, TEXT(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).

    For help about creating fields, see Managing Object Fields.

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.

    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.

    For help about creating fields, see Managing Object Fields.

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

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.

    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, TEXT(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)
    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.

    For help about creating fields, see Managing Object Fields.

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.

    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, TEXT(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)
    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 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.
    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.

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

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.

    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'

    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.

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.

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

    Use the following URL https://login.salesforce.com/apex/ONB2__JobsSetup, or, if you are already logged in, append apex/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 (App Launcher > 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. 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_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.