Skip to content

Transaction Builder Setup Options

This document summarizes the setup options for the transaction builder, JustOn's mechanism to convert usage data to billable items.

The options to control the transaction builder's behavior include:

Info

For an introduction to the transaction builder and details about how to set up usage data billing, see Usage Data Billing.

For further help with setting up usage data billing in general or the transaction builder in particular, contact the JustOn support team.

Fields on Custom Objects

The transaction builder requires a number of ON fields on objects that are to be converted to transactions. There are two types of required fields:

Depending on your business use case, you can also add (multiple) 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.
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 if this field is set.
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 transaction on the invoice, deselected by default.
Required when using the continuous invoice run.
ON_AddToCsv () Checkbox Determines whether to export the transaction 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)
or
Date		 Displays the date on which the transaction is considered for invoicing.
ON_Quantity Formula (Number)
or
Number		 Specifies the quantity or volume information as accumulated for the transaction.
ON_Price Currency (13,5) Specifies the net sales price of the 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 does create "tangible" transaction records, it still uses 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.

Example: Pass 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":"LAST"})
  • add the field ON_SKU 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 transactions. 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. If there are no field names defined on the item, the transaction builder falls back to the standard ON_Quantity and ON_Price fields on the source object.

The following subscription item fields are available to specify individual price or quantity information for usage data:

Item Field Target Field on Transaction Description Example Value
Transaction Price Field Price Defines a source field for the price that is to be used during the transaction building. ON_ShippingAmount__c
Transaction Quantity Field Quantity Defines a source field for the quantity that is to be used during the transaction building. ON_Impressions__c
Transaction Price Tier Quantity Field Price Tier Quantity Defines a source field for the price tier quantity that is to be used during the transaction building. ON_CombinedRequests__c
Transaction Commission Tier Price Field Commission Tier Price Defines a source field for the commission tier price that is to be used during the transaction building. ON_RevenueA__c

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

For information about object relationships in Salesforce, refer to Object Relationships Overview in the Salesforce Help.

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.

Aggregating Transactions by Criterion

Certain business use cases require transactions to be aggregated by a common criterion (see Invoice Criterion Usage Examples).

To this end, add the field ON_Criterion to 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. Later, 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 Criterion.

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

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.

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

Displaying Transaction Records on Invoices

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

  1. Open the template to be edited.

  2. In the Additional Content section, double-click the Transaction Records field and specify the transaction table configuration as required.

    Alternatively, you can click Edit in the detail view to edit the field.

  3. Click Save.

Note

Make sure that the checkbox fields

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

are selected.

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 ID. 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 Force.com 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"]}
}]

Attaching Transaction CSV to Invoices

You can configure JustOn to generate CSV files for 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.

  1. Open the template to be edited.

  2. In the Additional Content section, double-click the Transaction CSV field and specify the transaction CSV file configuration as required.

    Alternatively, you can click Edit in the detail view to edit the field.

  3. Click Save.

Note

Make sure that the checkbox field ON_AddToCsv on the source object (see Controlling Fields) is selected.

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 CV file name, which is generated as follows InvoiceNo_ObjectName_Title_No.csv.
invoiceFieldName string Specifies the field that holds the invoice ID. 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 Force.com 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 rows 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" : [ "recordRow" ],
             "options" : {
                           "timeFormat" : "hh:mm a",
                           "language" : "en",
                           "groupingSeparator" : "",
                           "decimalSeparator" : ".",
                           "dateFormat" : "yyyy/MM/dd"
                         },
             "decimalPlaces" : { },
             "columnSeparator" : ","
           }
}]

Enabling Transaction Table Rebuild

Under certain circumstances, a user may need to rebuild the transaction tables 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.

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

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.

    For details, see Adding Items.

Note

Make sure that 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).

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

In addition to the continuous invoice run, which creates invoices and invoice line items directly out of objects that hold usage data, there are two ways to invoke the transaction builder. The two approaches generate "tangible" transaction records:

Building Transactions Before Invoice Run

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

  1. Create a transaction filter as necessary.

    For details, see Creating Transaction Filter.

  2. Perform the invoice run.

    When prompted, select the intended 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 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. 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 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

      transactionfilter = 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/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 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. 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: 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.

Return to JustOn Administration.