Controlling Usage Data Billing Options

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.

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

• Defining fields on custom objects

• Aggregating additional fields

• Displaying itemized usage data records on invoices

• Generating CSV attachments for itemized usage data records

• Enabling transaction table rebuild

• Distributing usage data records along a criterion

• Distributing items to multiple invoices

• Assigning itemized data to specific subscriptions

• Enabling usage data billing to multiple parties

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

• Using transaction and transaction details

• Periodically aggregating transaction details

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:

• Controlling fields (hold meta data for assignments or process control)

• Data fields (hold actual usage data)

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.

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.

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.

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.

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.

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.

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:

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.

Enabling Transaction Display

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

• including a transaction table in the invoice PDF, or

• attaching a transaction CSV file to the invoice.

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.

[{
    "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"
}]

[{
    "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'" ]
}]

[{
    "active" : true,
    "title" : "Billed Transaction Details",
    "order" : "Date__c",
    "name" : "TransactionDetail__c",
    "fields" : [ "Date__c", "Quantity__c", "Price__c" ],
    "invoiceFieldName" : "Invoice__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"]}
}]

[{
    "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.

[{
"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.

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.

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.

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.

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

• Creating Recipient-Specific Controlling Fields, and

• Creating Recipient-Specific Filters.

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

• Creating individual subscriptions for multiple recipients

• Configuring transaction record display for multiple recipients

• Optionally, configuring multiple currency billing

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:

• Selecting a transaction filter when executing an invoice run

• Using a transaction build job

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 a transaction filter

• Creating a batch parameters custom setting to include the transaction filter

• Scheduling the transaction build job

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

     CODE

     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:

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.