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:

Defining fields on custom objects
Using transaction and transaction details
Aggregating transactions by criterion
Periodically aggregating transaction details
Aggregating additional fields
Displaying transaction records on invoices
Generating CSV attachments for transaction records
Enabling transaction table rebuild
Assigning itemized data to specific subscriptions
Enabling usage data billing to multiple parties
Building transactions

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 ON fields: controlling fields and data fields.

Depending on the requirements of 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, `TEXT(AccountId)`.
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 to have them filled and copied to the generated invoices or invoice line items. For details, see ON Field Mechanism.

Data Fields

Data fields hold the actual usage data. 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.

API Name	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 to have them filled and copied to the generated invoices or invoice line items. For details, see ON Field Mechanism.

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.

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.

Open the subscription for which you want to set an aggregation period.
Click Edit.
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
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.

Open the subscription item for which you want to define the additional data aggregation.
Click Edit.
In the field Transaction Aggregation Fields, define the fields to be aggregated and the function to use as necessary.
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.

Open the template to be edited.
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.
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.

Open the template to be edited.
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.
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:

Navigate to the object management settings of the Invoice object.
Click Search Layouts.
Click Edit in the row of the Invoices List View.
In the Custom Buttons section, move Rebuild Transaction Tables to the Selected Buttons column.
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.

Navigate to the fields list of the Subscription object.
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 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.

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

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

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

For details, see Customizing Templates.
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:

Selecting a transaction filter when executing an invoice run
Using a transaction build job

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.

Create a transaction filter as necessary.

For details, see Creating Transaction Filter.
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 a transaction filter
Creating a batch parameters custom setting to include the transaction filter
Scheduling the transaction build job

Creating Transaction Filter

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.

In Setup, open Custom Settings.

In Salesforce Lightning, navigate to Custom Code > Custom Settings.

In Salesforce Classic, navigate to Develop > Custom Settings.
Click Manage in the row of Batch Parameters.
Click New.
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
```
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:

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).
From the Apex Job drop-down list, select Batch Chain Job.
In the Job Name field, specify the name of the batch parameters setting, for example buildtransactions.
From the Start Time drop-down list, select the preferred execution time.
Optionally, edit the displayed cron expression to adjust the execution time.
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:

In Setup, open Apex Classes.

In Salesforce Lightning, navigate to Custom Code > Apex Classes.

In Salesforce Classic, navigate to Develop > Apex Classes.
Click Schedule Apex on top of the list.
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
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.