action.skip

Controlling Usage Data Billing Options

← Setting Up Billing Automation

When billing usage data, the continuous invoice run creates invoices and invoice line items directly out of objects that hold usage data. It uses the transaction builder functionality to itemize the consumption data. Although without creating "tangible" transaction records, it still uses (transient) transactions to do so – hence the name.

Note

This article summarizes advanced options for the transaction builder. For an introduction and a step-by-step guideline on setting up usage data billing, see Enabling Usage Data Billing.

Usage data billing, continuous invoice run, transaction builder?

Usage data billing is the general name for JustOn's approach to generate invoices from custom object records that represent product consumptions (volume or traffic data, service coverage, etc.).

The continuous invoice run is the key player in this operation: it creates invoices and invoice line items from the object records that hold usage data. As the name suggests, it can run multiple times, repeatedly aggregating new usage data to existing invoice line items as long as an invoice is Draft.

The continuous invoice run, for its part, relies on the transaction builder. This mechanism itemizes the consumption data – converting it to actually billable items.

The following options are available to control the transaction builder's behavior:

When actually building "tangible" transactions, the additional options include:

Fields on Custom Objects

The transaction builder requires a number of ON fields on objects that hold usage data to be itemized. There are two types of required fields:

Optionally, your business use cases may require additional price and quantity fields.

Controlling Fields

Controlling fields hold meta data for assignments or process control.

Note

JustOn checks the controlling fields when starting the transaction builder. If a required field is missing, it aborts the transaction building process.

API Name Required Data Type Description
ON_Type Formula (Text)
or
Picklist
Defines the type of the created transaction, either Transaction or Detail. Using transaction and transaction details allows for aggregating individual transactions while still keeping individual records.
When using the continuous invoice run, only Transaction is required.
ON_OrderNo Formula (Text)
or
Text
Represents the key to match source data to a subscription item.
If you use a lookup relation or a formula to determine the order no, make sure that your logic produces the same order no value for both the source object and the item.
If you get individual records for different types of usage data, you need a formula that yields the intended target item.
If you get different usage data types in one record, you specify a comma-separated list of target items.
ON_OrderNo2 Formula (Text)
or
Text
Optional, extends the field ON_OrderNo. Can be used to split the comma-separated list of target items, for example, for logical reasons, or if you use a complex formula that exceeds the size limit for one field.
ON_Subscription Lookup (Subscription) Links to the related subscription after the object records have been successfully processed. Is empty by default.
ON_Invoice Lookup (Invoice) Links to the related invoice after the object records have been successfully billed. Is empty by default.
If the produced invoice is canceled, the object records become subject to the invoice run again.
ON_LastError Text (255) Displays the error message if the transaction creation has failed. Is empty by default.
ON_TargetSubscription Lookup (Subscription)
or
Formula (Text)
Specifies the target subscription if there is more than one active subscription available.
ON_Account is ignored once this field is available, irrespective of whether it is empty or filled.
ON_Account Formula (Text) Specifies the Salesforce account ID or external ID, required if there is no or more than one account lookup on the object.
The formula uses the API name of the field that links the object to the account, for example, CASESAFEID(Account__c).
ON_ParentAccount Formula (Text) Links to the related parent account. Subscriptions of the parent account will also be considered when building transactions.
ON_AddToTransactionTable Checkbox Determines whether to show the itemized usage data records on the invoice, deselected by default.
Required when using the continuous invoice run.
ON_AddToCsv Checkbox Determines whether to export the itemized usage data records as CSV, deselected by default.
Required when using the continuous invoice run.
ON_Criterion Formula (Text)
or
Text
Defines a criterion to aggregate defined transactions to one invoice line item.
ON_InvoiceCriterion Formula (Text)
or
Text
Defines a criterion to group items on the same invoice.

Info

Depending on your use case and its requirements, you can add more fields in addition to the fields listed above. Using the ON Field Mechanism, JustOn fills and copies them to the generated invoices or invoice line items.

Data Fields

Data fields hold the actual usage data.

API Name Required Data Type Description
ON_Date Formula (Date)/
Formula (Date/Time)
or
Date
Displays the date on which the usage data record is considered for invoicing.
The formula return type depends on the source field.
If you create ON_Date as a formula field with the return type Date but the referenced field is of the type Date/Time, the operator DATEVALUE must precede the referenced field, like DATEVALUE(<datetime_field>).
ON_Quantity Formula (Number)
or
Number
Specifies the quantity or volume information as accumulated for the usage data record.
ON_Price Currency (13,5) Specifies the net sales price of the usage data record. If set, takes precedence over the price defined on the subscription item.
ON_Title Formula (Text)
or
TextArea
Can specify an individual (product) title. If set, takes precedence over the title defined on the subscription item.

Info

Depending on your use case and its requirements, you can add more fields in addition to the fields listed above. Using the ON Field Mechanism, JustOn fills and copies them to the generated invoices or invoice line items.

Note

Be aware that although JustOn usually does not create "tangible" transaction records, it still uses (transient) transactions to itemize the usage data. That is, any used data fields must be available on the custom object and on the transaction. Data fields on the custom object must have the same API name as the target field on the transaction, prefixed with ON_. Make sure that the data types are compatible.

For an overview of available fields on the transaction, see the Transaction object reference. If there is a field available for the piece of data you require, you must not create a new ON field on the transaction or the invoice line item, only on the custom object.

Aggregating individually priced source records

Think of usage data records that match with the same subscription item but that each define an individual price in the ON_Price field. Now the continuous invoice run must aggregate these prices. To support this, you configure the following fields on the transactional item:

Field Value
Transaction Price Field ON_Price__c
Aggregate Indiv. Priced Transactions (checkbox) true
Passing custom usage information to invoice

This example assumes that you want to display a custom piece of information ("SKU") retrieved from your usage data in the invoice line item table.

To this end, you

  • create the field ON_SKU on your custom usage data object, the Transaction object and the Invoice Line Item object
  • set the field ON_SKU to be aggregated via the field Transaction Aggregation Fields of the corresponding subscription item ({"ON_SKU__c":"LAST"})
  • add the field ON_SKU__c to the field Table Columns of the invoice template to be used

Doing so

  • copies the value from ON_SKU on the custom usage data object to ON_SKU on the (temporary) transaction
  • aggregates the values of ON_SKU of all transactions
  • copies the aggregated value to ON_SKU on the invoice line item
  • prints the value of ON_SKU of the invoice line item to the invoice line item table

Price and Quantity Fields

Certain business use cases require individual (account-specific) prices, price tiers or quantity information for consumption data. To this end, you can add multiple price and quantity fields to the source object. An (account-specific) subscription item can then retrieve the intended value from the specified source field. Doing so usually requires to aggregate the relevant values from multiple source records.

usage_indiv_price
Retrieving and aggregating individual source prices

If there are no specific field names defined on the item, the transaction builder uses the (standard) ON_Quantity and ON_Price fields on the source object.

Aggregating individually priced source records

Think of usage data records that match with the same subscription item but that each define an individual price in the ON_Price field. Now the continuous invoice run must aggregate these prices. To support this, you configure the following fields on the transactional item:

Field Value
Transaction Price Field ON_Price__c
Aggregate Indiv. Priced Transactions (checkbox) true

The following subscription item fields are available to specify custom price or quantity source fields for usage data. The configuration differs depending on whether you retrieve the data directly from the usage data records or from transaction records.

Using the continuous invoice run and without any aggregation logic involved, you can retrieve custom price and quantity information directly from the usage data records.

Note that the relevant fields do not need to be ON fields.

Item Field Description Example Value
Transaction Price Field Defines a source object field for the price that is to be used during the transaction building. ShippingAmount__c
Transaction Quantity Field Defines a source object field for the quantity that is to be used during the transaction building. Impressions__c
Transaction Price Tier Quantity Field Defines a source object field for the price tier quantity that is to be used during the transaction building. CombinedRequests__c
Transaction Commission Tier Price Field Defines a source object field for the commission tier price that is to be used during the transaction building. RevenueA__c
Using custom price and quantity fields

Assume you want to use customized price and quantity information for usage data. If your custom usage data object holds this data in ClickRevenue__c and Impressions__c, respectively, the corresponding item fields must specify the following values:

Field Value
Transaction Price Field ClickRevenue__c
Transaction Quantity Field Impressions__c

When referring to transaction fields, however, you must use the prefix transaction.:

Item Field Description Example Value
Transaction Price Field Defines a transaction field for the price that is to be used during the transaction building. transaction.ShippingAmount__c
Transaction Quantity Field Defines a transaction field for the quantity that is to be used during the transaction building. transaction.Impressions__c
Transaction Price Tier Quantity Field Defines a transaction field for the price tier quantity that is to be used during the transaction building. transaction.CombinedRequests__c
Transaction Commission Tier Price Field Defines a transaction field for the commission tier price that is to be used during the transaction building. transaction.RevenueA__c
Commission based on average sales volume

Assume you want to calculate the commission based on the average sales volume, for example, the basket amount of an order. You create a commission tier table, for example:

Tier Price Commission
A 50,00 10%
B 100,00 9%
C 150,00 8%
...

The usage data object Order requires a custom field to hold the sales volume for a single order. To calculate the average amount over a certain period, you set up JustOn to aggregate the individual values of this field (see Aggregating Additional Fields), and to use this as the basis for allocating the intended commission (see Price and Quantity Fields).

Modeling this use case so involves:

  • Creating the field ON_BasketAmount__c on the Order object to hold the sales volume
  • Creating the target field BasketAmount__c on the Transaction object
  • Specifying the field BasketAmount__c as the price source field in the item field Transaction Price Field like transaction.BasketAmount__c
  • Specifying the average calculation in the Item field Transaction Aggregation Fields like {"BasketAmount__c":"AVG"}
  • Specifying the commission tier price to be used in the Item field Transaction Commission Tier Price Field like transaction.BasketAmount__c
  • Selecting the Item checkbox Aggregate Indiv. Priced Transactions to combine transactions with individual prices

Consequently, JustOn calculates the average basket amount of all orders throughout the invoice run period, and allocates the commission tier as determined based on that average.

Aggregating Additional Fields

Certain business use cases require additional data fields on the source object (see Data Fields), which are then to be aggregated for the (transient) transaction. You can define the aggregation to take place using the field Transaction Aggregation Fields on the subscription item.

Info

Make sure that the fields to be aggregated are available with the same name on the source object, the transaction and the invoice line item.

The field value aggregation is to be defined as a JSON expression using the following pattern:

{"FIELDNAME1":"FUNCTION","FIELDNAME2":"FUNCTION"}

The following aggregation functions are available:

Function Supported Data Types Description
SUM Numeric and string values Adds up all values, preserves Null values.
MIN Numeric, Date and DateTime values Selects the minimum of all values, preserves Null values.
MAX Numeric, Date and DateTime values Selects the maximum of all values, preserves Null values.
LAST Numeric, string and Date values Selects the last processed value.
AVG Numeric Calculates the average value.
The AVG function is available as of JustOn 2.57.
  1. Open the subscription item for which you want to define the additional data aggregation.
  2. Click Edit.
  3. In the field Transaction Aggregation Fields, define the fields to be aggregated and the function to use as necessary.
  4. Click Save.

    This enables the additional field aggregation during the transaction generation.

Passing custom usage information to invoice

This example assumes that you want to display a custom piece of information ("SKU") retrieved from your usage data in the invoice line item table.

To this end, you

  • create the field ON_SKU on your custom usage data object, the Transaction object and the Invoice Line Item object
  • set the field ON_SKU to be aggregated via the field Transaction Aggregation Fields of the corresponding subscription item ({"ON_SKU__c":"LAST"})
  • add the field ON_SKU__c to the field Table Columns of the invoice template to be used

Doing so

  • copies the value from ON_SKU on the custom usage data object to ON_SKU on the (temporary) transaction
  • aggregates the values of ON_SKU of all transactions
  • copies the aggregated value to ON_SKU on the invoice line item
  • prints the value of ON_SKU of the invoice line item to the invoice line item table

Enabling Transaction Display

When billing usage data, you can configure JustOn Billing & Invoice Management to attach transaction tables to the invoice, either

Displaying Transaction Records on Invoices

You can configure JustOn to print a table of itemized usage data records (or, if applicable, transaction records) on an invoice. To this end, provide a corresponding configuration (in JSON notation) in the template field Transaction Records.

Configuration Options

The following configuration records are possible:

Keyword Data Type Possible Values Description
active Boolean true or false Activates the current configuration record.
title string The text to be printed above the transaction table.
name string object API name Specifies the source object for the transaction records to be displayed.
Note that the object needs a lookup relationship to the invoice.
invoiceFieldName string Specifies the field that holds the invoice number. Optional, required if there are more than one lookup fields.
fields list of strings field names Specifies the columns and their order to be rendered.
JustOn takes the column header from the field labels, and it considers the field types and applies the corresponding number and date formats of the template.
You can use the special field PosNo to display a running number of the records in a separate column.
calculationFields list of strings field names Specifies the fields (columns) whose values are to be added up.
order string Specifies a comma-separated list of fields whose values are to define the sort order of the records (optional).
conditions list of strings Specifies complex conditions (optional). Can be used to restrict the number of printed records, like Quantity > 1000.
Multiple conditions are separated by AND. String values must be enclosed in single quotes.
For more details, see the SOQL and SOSL Reference in the Salesforce Developer Documentation.
subtotal map: string => list<string> Specifies a map of fields to field lists. Determines that a subtotal is printed when a column (the "field") changes its value. The "field list" specifies the subtotal fields.
Configuration Examples

Show all records of the type Transaction__c that are related to the current invoice:

[{
    "active" : true,
    "title" : "Billed Transactions",
    "name" : "Transaction__c",
    "fields" : [ "Date__c", "ExternalId__c", "Description__c", "Quantity__c" ],
    "calculationFields" : [ "Quantity__c" ],
    "order" : "Type__c, Date__c"
}]

Show all records of the type Transaction__c that have set the type Foo, and hide records of the type Bar:

[{
    "active" : true,
    "title" : "Billed Transactions of type Foo",
    "name" : "Transaction__c",
    "fields" : [ "Date__c", "ExternalId__c", "Description__c", "Quantity__c" ],
    "order" : "Date__c",
    "conditions" : [ "Type__c = 'Foo'" ]
},
{
    "active" : false,
    "title" : "Billed Transactions of type Bar",
    "name" : "Transaction__c",
    "fields" : [ "Date__c", "ExternalId__c", "Description__c", "Quantity__c" ],
    "order" : "Date__c",
    "conditions" : [ "Type__c = 'Bar'" ]
}]

Show all transaction detail records that refer to the invoice via the field ONB2__Transaction__r.ONB2__Invoice__c:

[{
    "active" : true,
    "title" : "Billed Transaction Details",
    "order" : "Date__c",
    "name" : "TransactionDetail__c",
    "fields" : [ "Date__c", "Quantity__c", "Price__c" ],
    "invoiceFieldName" : "Invoice__c"
}]

Display a subtotal after each change of Description__c and Title__c:

[{
    "active" : true,
    "title" : "Billed Transactions",
    "name" : "Transaction__c",
    "fields" : [ "Date__c", "ExternalId__c", "Description__c", "Quantity__c" ],
    "calculationFields" : [ "Quantity__c" ],
    "order" : "Type__c, Date__c",
    "subtotal" : { "Description__c" : ["Quantity__c", "Price__c"],
                   "Title__c" : ["SingleIndividualCount__c"]}
}]

When invoicing objects in a parent-child relation, show the child records in the transaction table:

This example assumes you invoice Case records (= source parent object), with Product Consumed and Time Sheet Entry records (= source child objects) that represent the actual usage data, as outlined in Best Practice: JustOn for Field Service. Now you want two transaction tables to be displayed on the invoice PDF: one that lists the date, name and quantity of the products consumed and another one that lists the date and quantity of the time sheet entries.

Make sure to select ON_AddToTransactionTable on both the parent and the child records.

[{
    "active" : true,
    "title" : "Products Consumed",
    "name" : "ProductConsumed__c",
    "invoiceFieldName" : "ON_Invoice__c",
    "invoiceRelationshipFieldName" : "Case__r.ON_Invoice__r",
    "fields" : [ "ON_Date__c", "ON_Title__c", "ON_Quantity__c" ]
},
{
    "active" : true,
    "title" : "Spent Time",
    "name" : "TimeSheetEntry__c",
    "invoiceFieldName" : "ON_Invoice__c",
    "invoiceRelationshipFieldName" : "Case__r.ON_Invoice__r",
    "fields" : [ "ON_Date__c", "ON_Quantity__c" ]
}]
  1. Open the template to be edited.
  2. In the Transaction Records field, specify the transaction table configuration as required.
  3. Click Save.

    Once set up as required, this triggers JustOn to create the transaction table and print it to the invoice PDF. For details about regenerating the table, see Creating New Transaction Tables.

Note

Make sure that the checkbox fields

  • ON_AddToTransactionTable on the source object (see Controlling Fields) and
  • DisplayTransactionTables on the invoice

are selected.

Enabling Transaction Table Rebuild

Under certain circumstances, a user may need to rebuild the tables of itemized usage data records for an invoice. JustOn provides the option to do so. However, the button to trigger this operation may not be visible in the UI by default.

To enable the transaction table rebuild:

  1. Navigate to the object management settings of the Invoice object.
  2. Click Search Layouts.
  3. Click Edit in the row of the Invoices List View.
  4. In the Custom Buttons section, move Rebuild Transaction Tables to the Selected Buttons column.
  5. Click Save to save the modified page layout.

For help about modifying page layouts, see Managing Pages.

Attaching Transaction CSV to Invoices

You can configure JustOn to generate CSV files for itemized usage data records (or, if applicable, transaction records) to be attached to invoices. Use this functionality if the transaction tables as printed directly on invoices become too large or if you need the CSV files for a specific purpose.

To generate transaction CSV files, provide a corresponding configuration (in JSON notation) in the template field Transaction CSV.

Configuration Options

The following configuration records are possible:

Keyword Data Type Possible Values Description
active Boolean true or false Activates the current configuration record.
name string object API name Specifies the source object for the transaction records to be displayed.
Note that the object needs a lookup relationship to the invoice.
title string Part of the CSV file name, which is generated as follows InvoiceNo_ObjectName_Title_No.csv by default.
Can contain placeholders with all invoice-related objects as sources, including
Invoice/Default
Account
BusinessEntity
EmailContact
PaymentInstrument
RelatedInvoice
Subscription
Template
In addition, the built-in placeholder ObjectName is supported.
If title contains at least one placeholder, the file name is generated from the rendered title string only, replacing the default file name pattern except for the file number.
The title string [Name]_[ObjectName]_[InvoiceDate:yyyy-MM-dd] will generate the following file name: InvoiceNo_ObjectName_InvoiceDate_No.csv (with the date forced to the ISO format).
invoiceFieldName string Specifies the field that holds the invoice number. Optional, required if there are more than one lookup fields.
order string Specifies a comma-separated list of fields whose values are to define the sort order of the records (optional).
conditions list of strings Specifies complex conditions (optional). Can be used to restrict the number of printed records, like Quantity > 1000.
Multiple conditions are separated by AND. String values must be enclosed in single quotes.
For more details, see the SOQL and SOSL Reference in the Salesforce Developer Documentation.
config map Specifies a configuration that defines the columns and format of the CSV file. For details, see Defining CSV File JSON Configuration.
The config key must have a row setting with the following row definitions:
headerRow – A list of column labels to be printed at the start of each CSV file.
recordRow – A list of fields where each row corresponds to a transaction record.
Configuration Example
[{
"active" : true,
"name" : "Transaction__c",
"order" : "Type__c, Date__c",
"invoiceFieldName" : "Invoice__c",
"conditions" : [ ],
"config" : {
             "useASCII" : false,
             "rows" : {
                        "headerRow" : [ "Date", "ExternalId", "Description", "Quantity" ],
                        "recordRow" : [ "Date__c", "ExternalId__c", "Description__c", "Quantity__c" ]
                      },
             "rowOrder" : [ "headerRow","recordRow" ],
             "options" : {
                           "timeFormat" : "hh:mm a",
                           "language" : "en",
                           "groupingSeparator" : "",
                           "decimalSeparator" : ".",
                           "dateFormat" : "yyyy/MM/dd"
                         },
             "decimalPlaces" : { },
             "columnSeparator" : ","
           }
}]
  1. Open the template to be edited.
  2. In the Transaction CSV field, specify the transaction CSV file configuration as required.
  3. Click Save.

    Once set up as required, this triggers JustOn to create the transaction CSV file and attach it to the invoice when finalizing the invoice. For details about regenerating the table, see Creating New Transaction Tables.

    At the size of 2048 kB, JustOn splits the CSV attachment into a new file. So if there are many transaction records, JustOn produces multiple CSV files, putting a numbering to the file name like 2019-01515_Orders_All_1.csv, 2019-01515_Orders_All_2.csv, etc.

Note

To have JustOn create and attach the transaction CSV files, make sure, in addition, that

  • The checkbox field ON_AddToCsv on the source object (see Controlling Fields) is selected
  • In the template field Email File Types, CSV files are not excluded from being attached to emails.

    With the field empty (default), all files, including CSV, are attached except for transaction table HTML (which is printed to the PDF).

  • You execute a batch finalization.

Distributing Transactions Along Criterion

Usually, JustOn aggregates usage data records with the same key (ON_OrderNo, see Controlling Fields) and feeds the aggregated information into one subscription item. Certain business use cases may require, however, only particular usage data records (or, if applicable, transaction records) to be aggregated by a specific criterion. Doing so will split the item along the defined criterion and, consequently, produce multiple invoice line items.

To this end:

  1. Set the field ON_Criterion on the custom object.

    This can be a Formula (with the return type Text) or a Text field, which is then used to hold the actual distinguishing criterion.

  2. Select the checkbox Aggregate Indiv. Priced Transactions on the relevant subscription item(s).

Consequently, JustOn aggregates all usage data records with the same criterion to the same transaction and creates a single invoice line item.

Info

You can explicitly disable the aggregation feature for a subscription item by selecting the checkbox Ignore Item Criterion.

Note

Make sure not to confuse the item criterion ON_Criterion and the invoice criterion ON_InvoiceCriterion. They cover different use cases in different contexts. If necessary, the use cases can be combined, though.

When using price tiers, JustOn by default determines the price tier individually for each invoice line item as created on the basis of a specific transaction criterion. Selecting the checkbox Ignore Criterion For Price Tier Quantity, however, forces JustOn to ignore the criterion when determining the price tier.

Example: Price tiers for transactional item, split by criterion

Subscription settings

Item Order No. Billing Type
Product 1 PROD1 Transactional
Price Tier Quantity Price
A 100 10,00
B 5,00

Custom object records to be matched with the transactional item

Criterion Order No. Quantity
1 PROD1 30
1 PROD1 40
2 PROD1 50

JustOn produces two invoice line items – one for criterion 1, and one for criterion 2. Without selecting the checkbox Ignore Criterion For Price Tier Quantity, JustOn uses the individual quantities to determine the price tier. Accordingly, it applies price tier A for the two invoice line items:

Invoice Line Item Quantity Price
Product 1 70 700,00
Product 1 50 500,00

With the checkbox Ignore Criterion For Price Tier Quantity selected, however, JustOn combines the quantities and consequently applies price tier B:

Invoice Line Item Quantity Price
Product 1 70 350,00
Product 1 50 250,00

Distributing Items to Multiple Invoices

Generally, the invoice run creates one invoice per subscription. Certain use cases, however, require usage data or items to be invoiced separately. To support this, JustOn makes use of invoice criteria, which are a means for controlling the distribution of invoice line items to multiple invoices. Only invoice line items with the same criterion are included in one invoice, others are invoiced separately.

To enable the invoice criterion when billing usage data, that is, when processing transactional items, add the field ON_InvoiceCriterion to the custom usage data object.

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

    Field Label API Name Data Type
    Invoice Criterion ON_InvoiceCriterion Text (255)
    Formula (Text)

    For help about creating fields, see Managing Object Fields.

Using this field allows for grouping invoice line items. The scope of the criterion is limited to draft invoices, the current invoice run, and the service period of the current invoice run.

Info

If empty or not set, the invoice criterion is considered an empty criterion, which, consequently, does not distribute the invoice line items to multiple invoices.

Invoice criterion example

The following subscription configuration

Item Order No. Billing Type Quantity Price
Fee 3 PROD3 Transactional 10,00

with these custom object records to be matched with the transactional item

Invoice Criterion Order No. Quantity
A PROD3 3
A PROD3 5
B PROD3 7

produces two invoices with the following invoice line items:

(1) invoice for criterion A

Invoice Line Item Quantity Price
Fee 3 8 10,00

(2) invoice for criterion B

Invoice Line Item Quantity Price
Fee 3 7 10,00

Assigning Itemized Data to Specific Subscriptions

JustOn usually assigns the itemized usage data to items of the best matching subscription. Certain business use cases, however, require distributing the usage data to more than one subscription (using ON_ParentAccount, for example). You can explicitly define a subscription as the target for the usage data to prevent unwanted results in this case.

Using the checkbox field ON_ConversionTarget on the subscription, you can control this behavior.

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

    API Name Data Type Description
    ON_ConversionTarget Checkbox Determines whether the usage data as converted from custom objects is assigned to the current subscription.

    For help about creating fields, see Managing Object Fields.

Info

If the field ON_ConversionTarget is missing or deselected on all subscriptions, JustOn assigns the usage data to the first matching subscription.

Enabling Usage Data Billing to Multiple Parties

Generally, the transaction builder is set up to bill usage data to one recipient, usually via the account associated to the corresponding subscription. Certain business use cases, however, require billing transactions to multiple parties.

To cover these needs, you apply the configuration explained in Enabling Multiple Party Billing, namely

In addition, enabling usage data billing to multiple recipients involves the following tasks:

Creating Individual Subscriptions

To support multiple billing, you must create recipient-specific subscriptions with individual items.

  1. Create two subscriptions as required – one for the merchant, and one for the buyer.

    For details, see Creating Subscriptions.

  2. Add the items to the two subscriptions as required.

    Make sure that

    • The billing type is set to Transactional
    • Each item's value of the OrderNo field matches one of the possible values of the custom object's ON_OrderNo field (see Configuring Custom Object)

    For details, see Adding Items.

Configuring Transaction Record Display

To support multiple billing, you must configure two recipient-specific invoice templates with individually configured Transaction Records fields. To find the correct records, you must use the invoiceFieldName variable in the transaction table configuration.

  1. Create and configure two recipient-specific templates – one for the merchant, and one for the buyer.

    For details, see Working With Templates.

  2. For each template, specify the transaction table configurations as required.

    For details, see Displaying Transaction Records on Invoices.

Merchant-specific transaction table configuration:

[{
"active" : true,
"title" : "Billed Orders",
"name" : "Order",
"fields" : [ "EffectiveDate", "TotalAmount" ],
"invoiceFieldName" : "ON_InvoiceMerch__c"
}]

Buyer-specific transaction table configuration:

[{
"active" : true,
"title" : "Billed Orders",
"name" : "Order",
"fields" : [ "EffectiveDate", "TotalAmount" ],
"invoiceFieldName" : "ON_InvoiceBuy__c"
}]

Building Transactions

When billing usage data, you usually create invoices and invoice line items directly out of objects that hold usage data. The continuous invoice run uses the transaction builder functionality to itemize the consumption data, but does not generate "tangible" transaction records. Specific use cases, however, may require to do so.

There are two ways to invoke the transaction builder to generate "tangible" transaction records:

Building Transactions Before Invoice Run

When executing an invoice run, users are prompted to select a transaction filter. If they choose to do so, JustOn runs the transaction build process before executing the invoice run.

  1. Create a transaction filter with the use case Transaction as necessary.

    For details, see Creating Transaction Filter.

  2. Perform the invoice run.

    When prompted, select the relevant transaction filter.

    For details, see Executing an Invoice Run.

    This generates both transaction records and draft invoices.

Info

You can also define a transaction filter as a parameter when setting up a scheduled parameterized invoice run.

Building Transactions Using a Scheduled Job

You can set up a job in order to have transactions built automatically on a regular basis. This involves the following subtasks:

Creating Transaction Filter

  1. Create a transaction filter with the use case Transaction as necessary.

    Note that the filter name (for example, transaction1) is passed as a parameter to the batch parameters setting.

    For details, see Creating Transaction Filter.

Creating Batch Parameters Setting

To pass the transaction filter to the transaction build process, you create a specific batch parameters setting. This setting combines the batch chain to be executed (TransactionBuilderChain) with the filter as a specific execution argument.

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

  3. Click New.
  4. Specify the details as required.

    • Name: The name for the batch parameters setting, must match the name of the transaction build job, for example buildtransactions
    • Batch Chain: TransactionBuilderChain
    • Parameter 1: A parameter to be passed to the batch chain (pattern parameter = value).

      Assuming the transaction filter name is transaction1, set

      TransactionFilters = transactions1
      
  5. Click Save.

Scheduling Transaction Build Job

To schedule the transaction build process, 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/ONB2__JobsSetup to your org's domain name.

    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 Batch Chain Job.

  3. In the Job Name field, specify the name of the batch parameters setting, for example buildtransactions.
  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 transaction build process 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: The name of the batch parameters setting, for example buildtransactions
    • 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 transaction build process 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.

Transaction and Transaction Details

Usually, each transaction results in an individual invoice line item. Certain business use cases, however, require transactions to be aggregated but still keeping individual records for transaction tables. To this end, JustOn supports transaction details, which are in a master-detail relationship with transactions.

Info

The field ON_Type, which is required on the usage data source object, controls whether to produce a transaction or a transaction detail, setting either Transaction or Detail, respectively.

For aggregating values, JustOn makes use of roll-up summary fields that sum up specific fields over all transactions details that belong to a specific transaction. The field Transaction on the transaction detail shows the parent transaction.

The following transaction fields are relevant for the transaction detail aggregation:

Transaction Field Type Child Field Description
Commission Tier Price (A) Roll-Up Summary (SUM) Commission Tier Price The sum of all single transaction commission tier prices.
Date (A) Roll-Up Summary (MAX) Date The last date of all related transaction details.
Price (A) Roll-Up Summary (SUM) Calculated Price The sum of all transaction detail prices.
Price Tier Quantity (A) Roll-Up Summary (SUM) Price Tier Quantity The sum of all single transaction price tier quantities.
Is Aggregated Formula (Checkbox) Determines that the aggregated fields are to be used if there are transaction details available.
Is Individually Priced Formula (Checkbox) Determines whether this transaction is individually priced. Is true if the transaction has a price or if each transaction detail has a price.
Quantity (A) Formula (Number) The quantity for all single transactions. It is set to 1 if the transaction is individually priced.
Service Period End (A) Roll-Up Summary (MAX) Service Period End The last service period end date of all related transaction details.
Service Period Start (A) Roll-Up Summary (MIN) Service Period Start The first service period start date of all related transaction details.
Single Count Roll-Up Summary (COUNT) The number of related transaction details.
Single Individual Count Roll-Up Summary (COUNT, Price NOT EQUAL TO) The number of all individually priced transaction details, required to determine the aggregated transactions with individual pricing.
Sum of Quantity Roll-Up Summary (SUM) Quantity The raw sum of all transaction detail quantities, used internally by Quantity (A).

Note

If Is Aggregated is true, the roll-up fields (suffixed (A)) are used during the invoice run. The values of the original fields Date, Price, Price Tier Quantity, Quantity, Service Period Start and Service Period End are ignored in this case.

For a complete list of available transaction and transaction detail fields, see Transaction and Transaction Detail.

Periodically Aggregating Transaction Details

When using transactions and transaction details, JustOn by default adds the transaction details to the newest transaction that has not yet been billed. Certain business use cases, however, require transactions to aggregate the transaction details of a specific period. To this end, you can define an aggregation period on a subscription.

  1. Open the subscription for which you want to set an aggregation period.
  2. Click Edit.
  3. Set the aggregation period as necessary.

    The following options are available:

    • Weekly: Aggregation period Monday - Sunday
    • Bi-Weekly: Aggregation periods 1st of month - 15th of month and 16th of month - last of month
    • Monthly: Aggregation period 1st of month - last of month
  4. Click Save.

    This enables the periodical aggregation of transaction details. JustOn creates a transaction for every period in which transaction details have occurred, adds transaction details until the period end, and creates a new transaction after a new period has started.