Billing Arbitrary Objects

JustOn allows creating invoices from virtually any object type during an invoice run. Using the generic invoice run, you can completely bypass subscriptions - if you do not need them to model any contractual relations or conditions.

Info

The generic invoice run is available as of JustOn 2.46.

Assume the following scenario as an example: You have integrated Salesforce with your back-end or marketplace system. In this environment, there are generated orders, typically with multiple order products. These order products now need to be invoiced without any contractual situation.

The way to set up the generic invoice run depends on the representation of your source data in Salesforce.

Following the example, your source data may be stored in objects that are in a parent-child relationship, for example, orders and order products. In this case, you set up these objects to hold the invoicing data using the ON field mechanism. JustOn can then produce the invoices based on the parent object and the invoice line items out of its child objects.

For details, see Setting Up Parent-Child Objects

There may be, however, customized objects that keep all required information in a single record. To support this scenario, you set up this single object to hold all invoicing source data using the ON field mechanism and specifically mark it as the single source. Consequently, JustOn produces both invoices and invoice line items from these records.

For details, see Setting Up Single Object

Furthermore, there may be data in addition to the configured ON fields for source objects in a parent-child relationship or for single source objects. If you need to create invoices based on data that is not accessible otherwise, you set up specific data mappings to retrieve it.

For details, see Setting Up Data Mapping

Irrespective of the source objects and their configuration, you can set up JustOn to allow for starting the generic invoice run from a parent of the actual source object.

For details, see Enabling Invoice Run From Parent

Info

You can combine multiple sources, providing the corresponding setup: You can define which data to use via ON fields, and specify an (optional) data mapping to further refine the invoice creation.

Custom filters finally determine which object records are to be processed in the invoice run.

Once set up, the generic invoice builder is executed as part of the usual invoice run if a corresponding custom filter is selected.

Info

When executing the generic invoice run, JustOn writes information about the billed source object to the generated invoice line items, setting the following fields:

Field Label API Name Data Type Description
Source Id SourceId Text(18)(External Id) The ID of the source object.
Filter Filter Text(255) The name of the invoice run filter.

Setting Up Parent-Child Objects

You can generate invoices based on source objects that are in a parent-child relationship, like orders with order products. If set up accordingly, the invoice run takes the parent object ( order) to produce the invoice, and the child objects ( order products) to produce the invoice line items.

ir_ON_field
Creating invoices based on accordingly configured parent-child objects

The invoicing process requires a number of ON fields on both the parent and the corresponding child object. The configuration steps include:

Info

In case you need multiple billing configurations, for example, if you want to create two invoices for multiple recipients from the same record, JustOn must distinguish between different sets of field configurations. To this end, append specific suffixes to the configuration fields, as explained in Creating Recipient-Specific Controlling Fields.

Configuring Parent Object

  1. Navigate to the fields list of the parent object.
  2. Create the following new fields as required.

    For help about creating fields, see Managing Object Fields.

Mandatory fields on the parent object:

Field Label API Name Data Type Description
Account ON_Account Formula (Text) Specifies the Salesforce account ID or external ID.
The formula uses the API name of the field that links the object to the account, for example, TEXT(AccountId).
Template ON_Template Formula (Text) Specifies the Salesforce ID of the related template.
Service Date ON_ServiceDate Formula (Date)/
Formula (Date/Time)
The record will be invoiced when the date is null or within the service period of the invoice run.
The formula return type depends on the source field.
Invoice ON_Invoice Lookup (Invoice) The invoice that resulted from this record.
Invoice Run ON_LastInvoiceRun Lookup (Invoice Run) Shows the last invoice run that has processed this object.
Last Error ON_InvoiceBuildError Text (255) Shows errors that occurred during the last invoice run.

Optional fields on the parent object:

Field Label API Name Data Type Description
Single Invoice ON_CreateSingleInvoice Checkbox Determines whether to create a single invoice for each parent record, ignoring existing invoices.
Is Line Item ON_IsItem Checkbox Determines whether to add the parent record itself as a line item. Use this if you want to invoice the parent directly without child records.

If ON_CreateSingleInvoice is configured, the following field on the invoice is mandatory:

Object API Name Data Type Description
Invoice ON_InvoiceSeparately Boolean Is set during the invoice run.

Info

Remember that the required ON fields usually reuse (via a formula) data that is already available on the object record.

You can add more fields using the ON field mechanism.

Configuring Child Object

  1. Navigate to the fields list of the child object.
  2. Create the following new fields as required.

    For help about creating fields, see Managing Object Fields.

Mandatory fields on the child object (only when utilized):

Field Label API Name Data Type Description
Title ON_Title Formula (Text) The name or short description of the invoice line item.
Quantity ON_Quantity Formula (Number) The quantity to be billed for this invoice line item.
Using a formula, you can, if required, set the quantity 0 to exclude records from being invoiced if certain conditions are true.
Assume, for example, a checkbox Billable - to exclude records where the checkbox is not selected, you can use a formula like: IF(Billable = 'false', 0 , Quantity)
Unit Price ON_UnitPrice Formula (Currency) Either the net or gross price of one unit of this item.

To address items by a key string, configure the optional field ON_OrderNo:

API Name Data Type Description
ON_OrderNo Text Key to match source data to the invoice line item, must be unique for each detail of the same master record.

Optionally, the following fields that are mandatory on the parent object can be used on the child object, too:

Field Label API Name Data Type Description
Invoice ON_Invoice Lookup (Invoice) The invoice that resulted from this record.
Invoice Run ON_LastInvoiceRun Lookup (Invoice Run) Shows the last invoice run that has processed this object.
Last Error ON_InvoiceBuildError Text (255) Shows errors that occurred during the last invoice run.

Info

Remember that the required ON fields usually reuse data (via a formula) that is already available on the object record.

You can add more fields using the ON field mechanism.

Setting Up Single Object

You can generate based on single source objects that hold all invoicing data using, like, for example, specifically customized contracts. If the object records are marked as the single source, and based on the appropriate configuration, JustOn can produce both invoices and invoice line items from these records.

ir_ON_field_single_o
Creating invoices based on one accordingly configured object

The invoicing process requires a number of ON fields on the source object to hold the information for both the invoices and invoice line items.

  1. Navigate to the fields list of the source object.
  2. Create at least the following new fields.

    Field Label API Name Data Type Description
    Account ON_Account Formula (Text) Specifies the Salesforce account ID or external ID.
    The formula uses the API name of the field that links the object to the account, for example, TEXT(AccountId).
    Template ON_Template Formula (Text) Specifies the Salesforce ID of the related template.
    Service Date ON_ServiceDate Formula (Date)/
    Formula (Date/Time)
    The record will be invoiced when the date is null or within the service period of the invoice run.
    The formula return type depends on the source field.
    Invoice ON_Invoice Lookup (Invoice) The invoice that resulted from this record.
    Invoice Run ON_LastInvoiceRun Lookup (Invoice Run) Shows the last invoice run that has processed this object.
    Last Error ON_InvoiceBuildError Text (255) Shows errors that occurred during the last invoice run.
    Is Line Item ON_IsItem Formula (Checkbox)
    Checkbox
    Forces JustOn to use this object as the source for both the invoice and the invoice line items.
    Title ON_Title Formula (Text) The name or short description of the invoice line item.
    Quantity ON_Quantity Formula (Number) The quantity to be billed for this invoice line item.
    Using a formula, you can, if required, set the quantity 0 to exclude records from being invoiced if certain conditions are true.
    Assume, for example, a checkbox Billable - to exclude records where the checkbox is not selected, you can use a formula like: IF(Billable = 'false', 0 , Quantity)
    Unit Price ON_UnitPrice Formula (Currency) Either the net or gross price of one unit of this item.

    Info

    Remember that the required ON fields usually reuse (via a formula) data that is already available on the object record.

    You can add more fields using the ON field mechanism.

Setting Up Data Mapping

There may be data in addition to the configured fields for source objects in a parent-child relationship or for single source objects. If you need to create invoices based on data that is not accessible otherwise, you set up specific data mappings to retrieve it.

ir_mapping
Creating invoices based on a mapping

A data mapping in JSON notation allows for a more flexible mapping configuration if the ON field mechanism is not sufficient enough. Notably you can

  • define constant values for target fields
  • define a source field for a target field, even from parent to child
  • define a custom invoice line item without dependency to a real source record
  • do without ON fields to transfer data to invoices

Note

It is not possible to use a data mapping to create additional recurring invoice line items.

Generating invoices based on a data mapping requires the following setup tasks:

Configuring Source Object

To use a data mapping, the generic invoice builder requires an ON field for the mapping on the source object.

  1. Navigate to the fields list of the source object.
  2. Create one of the following new fields.

    API Name Data Type Description
    ON_MappingName Text (255)
    or
    Formula (Text)
    Specifies the name of the file that contains the field mapping definition in JSON.
    If configured as a formula field, the mapping name is used for every record.
    Deprecated, accessible via the Documents tab in the Salesforce Classic UI only. Use ON_MappingId instead.
    ON_MappingId Text (255)
    or
    Formula (Text)
    Specifies the 18-digit, case-safe Salesforce record ID of the file that contains the field mapping definition in JSON.
    If configured as a formula field, the mapping ID is used for every record.
    ON_Mapping Text Area (Long) Specifies the field mapping definition in JSON.
    Takes precedence over ON_MappingId and ON_MappingName.

    Info

    You only need one of the above fields, depending on where you want to store the mapping configuration.

    For help about creating fields, see Managing Object Fields.

Creating Mapping Definition

The field mapping is defined in JSON notation and can either be stored as a Salesforce document or directly in a field on the record that is to be invoiced. See also Configuring Source Object.

Info

The data mapping for the generic invoice builder uses the general data mapping structure as described in Using Data Mapping. It considers, however, only the mappings externalIdFields, fields and items, and ignores fieldsToUpdate and tiers.

To save the data mapping directly on the object:

  1. Navigate to the fields list of the source object.
  2. Click Edit in the row of the ON_Mapping field.
  3. Specify the mapping definition in the text area.

    For details about the mapping definition, see Using Data Mapping.

  4. Click Save.

    This makes the mapping definition available for the invoice builder.

To refer to the data mapping saved as a document:

  1. Create the mapping definition and save it as a file.

    For details about the mapping definition, see Using Data Mapping.

  2. Open the Salesforce Files tab.

  3. Click Upload Files.
  4. Select the file using your browser's file selection dialog.
  5. Click Done.

    This makes the mapping definition available for the object configuration and thus for the invoice builder.

    Note

    Be aware that you need the Salesforce record ID as the input parameter for ON_MappingId.

    Find the file record ID in the file URL. To retrieve it, click next to the file record, then select View File Details.

Tip

Use a JSON validator before uploading the mapping to Salesforce.

Creating Invoice Run Filter

To define which records to include in the invoice run, you create custom filters.

Info

At least one filter is required.

  1. In Setup, open Custom Settings.

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

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Filters.

  3. Create filter(s) as required, following the examples below.

    Name Target Child Relation Transactional Suffix Use Case Parent Relationships
    Orders Order OrderItems Cstm Generic
    Cases Case Generic
    Contracts Contract Generic {"AccountId": "Account"}

    For help about creating filters, see Filters.

Info

  • The Target specifies the filter target, that is, the object on which the intended operation is executed. For the generic invoice run, the Target represents the source object based on which the invoice is created.

  • The Child Relation specifies the name of the child object if you create invoice line items based on child records.

    For master-detail relations, use the API name of the detail object. In case of standard Salesforce objects, you can use Workbench to find the correct name. For parent-child relations, use the relationship name of the child object.

  • The Transactional Suffix specifies the control field suffix if you use multiple billing configurations with different sets of field configurations, as explained in Enabling Multiple Party Billing.

  • The Parent Relationships setting is required if you want to invoke the invoice run from a parent of your actual source object - for example, if you want to generate an invoice for an account that has multiple contracts (set up as source objects).

    The value is a JSON string map that specifies the parent relationship. The keys are lookup fields (or formulas to return the ID) that point to the intended parent object, with the parent object type as their values. For example, {"ON_Account__c": "Account"} tells that ON_Account__c is a field on the source object (the filter target) that contains the parent ID of the type Account.

  • The Filter Group specifies a criterion for grouping (invoice run-relevant) filters. If set, users can select a filter group to preselect relevant filters, narrowing down the number of available filters.

Note

The use case for filters must always be Generic.

Enabling Invoice Run From Parent

You can set up JustOn to allow for starting the generic invoice run from a parent of the actual source object. Think, for example, of an account that has multiple contracts (or orders with order products) set up as source objects - now you want to generate an invoice for this account that covers all related contract (or orders).

ir_ON_field_single_o_parent
Invoking invoice creation from a parent object

Generating invoices from a parent of the source object requires the following additional setup tasks:

For details about configuring the source objects, see Setting Up Parent-Child Objects, Setting Up Single Object or Setting Up Data Mapping, respectively.

Creating Parent Invoice Run Filter

To allow for invoking the invoice run from a parent of the actual source object, you need a specifically configured invoice run filter that specifies the parent relationship. To this end, you use the Parent Relationships field of the filter. The value is a JSON string map that specifies the parent relationship. The keys are lookup fields (or formulas to return the ID) that point to the intended parent object, with the parent object type as their values. For example, {"ON_Account__c": "Account"} tells that ON_Account__c is a field on the source object (the filter target) that contains the parent ID of the type Account.

Invoice run from parent - examples

The following examples illustrate possible use cases and the required parent configuration.

Order (as the source object) with two parents

GIR_parent_example_1
Invoking the invoice run from from two parent objects

Assume you want to enable the invoice creation from the account that owns the order as well as from the contract to which the order relates. To this end, you use the known relationships to these parents. Accordingly, your JSON mapping in the Parent Relationships field of the filter may look like

{"ON_Account__c":"Account","ContractId__c":"Contract"}

Order (as the source object) with a parent and a higher-level parent

GIR_parent_example_2
Invoking the invoice run from a higher-level parent

Now assume you want to enable the invoice creation from the parent account of the account that owns the order. This requires

  • Creating a custom field on the order that specifies the relation to the higher-level parent account, like a formula field ON_ParentAccount__c, where the formula may be Account.ParentId.
  • Defining the parent relationship in the filter using the custom field created before, like

    {"ON_ParentAccount__c":"Account"}
    
  1. In Setup, open Custom Settings.

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

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Filters.

  3. Create the filter as required.

    The following fields are mandatory:

    Field Description
    Name Specifies the filter name, will be available as an option value when triggering the invoice run. Must be unique.
    Target Specifies the API name of the filter target. Represents the source object based on which the invoice is created.
    Use Case Specifies the specific filter use case. Must be Generic for the generic invoice run.
    Parent Relationships Specifies a parent relationship of the target object. Is a JSON string map where keys are lookup fields (or ID formulas) to the intended parent object, with the parent object type as their values, like {"ON_Account__c": "Account"}.

    Child Relation is required if you create invoices based on source objects that are in a parent-child relationship. Transactional Suffix is required if you use multiple billing configurations with different sets of field configurations.

Configuring Fields to Display on Parent

If you use the invoice build button on a parent object, JustOn displays a table of available source (child) records. You can configure the columns of this table using a field set defined on the source (child) object:

  1. Navigate to field sets of the source object.

    In Salesforce Lightning, click to open the Setup menu and select Setup, then open Objects and Fields > Object Manager > Object > Field Sets.

    In Salesforce Classic, open Setup > Build > Customize > Object > Field Sets for standard Salesforce objects. For JustOn or custom objects, open Setup > Build > Create > Objects > Object, then scroll to the Field Sets section.

  2. Click New.

  3. Specify the name genericinvoicerun.

    Specify the label and description as required.

  4. Click Save.

    This creates the new (empty) field set and opens it in the edit view.

  5. Move the fields you want to be displayed to the In the Field Set container.

  6. Click Save.

    This applies the field set configuration, making the table setup available on the Create New Invoice page.

Adding Invoice Build Button

Once set up, there are two ways to invoke the invoice creation process:

Adding a new button for manual invoice generation involves two steps:

Completing these steps allows you to manually trigger the invoice build process from the detail page of the configured source or parent object (opportunity, order, etc.) by clicking the New Invoice button.

Creating Invoice Build Button

To create the button:

  1. Navigate to the buttons list of the source or parent object.

    In Salesforce Lightning, click to open the Setup menu and select Setup, then open Objects and Fields > Object Manager > Object > Buttons, Links, and Actions.

    In Salesforce Classic, open Setup > Build > Customize > Object > Buttons, Links, and Actions for standard Salesforce objects. For JustOn or custom objects, open Setup > Build > Create > Objects > Object, then scroll to the Buttons, Links, and Actions section.

  2. Click New Button or Link.

  3. Specify the following button details.

    Detail Value
    Label New Invoice
    Display Type Detail Page Button
    Behavior Display in existing window with sidebar
    Content Source URL
    Content /apex/ONB2__NewInvoiceFromSObject?id={!ObjectAPIName.Id}
    You must replace ObjectAPIName with the API name of the object where the button is placed.
  4. Click Save.

    For help about creating buttons, see Managing Buttons or Links.

Adding Invoice Build Button to Page

To add the button to the page layout:

  1. Navigate to the page layout definition of the source or parent object.

    In Salesforce Lightning, click to open the Setup menu and select Setup, then open Objects and Fields > Object Manager > Object > Page Layouts.

    In Salesforce Classic, open Setup > Build > Customize > Object > Page Layouts for standard Salesforce objects. For JustOn or custom objects, open Setup > Build > Create > Objects > Object, then scroll to the Page Layouts section.

  2. Click Edit in the row of the layout you intend to modify.

  3. Add the New Invoice button to the page layout.

    In Salesforce Lightning, drag the button from the Mobile & Lightning Actions palette to the Salesforce Mobile and Lightning Experience Actions section.

    In Salesforce Classic, drag the button from the Buttons palette to the Custom Buttons area.

  4. Click Save.

    For help about modifying page layouts, see Managing Pages.

Configuring Recurring Items

Your business may require to set up arbitrary objects to be billed repeatedly. That is, you must reproduce the behavior of recurring subscription items in the context of the generic invoice run - without subscription.

To enable recurring billing with the generic invoice run, you add the fields that hold the specific billing information to the source object from which the invoice line items are generated. For details, see the general billing settings in Item Pricing.

  1. Navigate to the fields list of the source object.
  2. Create at least the following new fields.

    Field Label API Name Data Type Description
    Billing Type ON_BillingType Picklist
    Formula (Text)
    Specifies the billing behavior. Supported values for recurring items include Recurring or Recurring Prorated.
    If the field does not exist or is empty, it defaults to the billing type One-Time.
    Next Service Period Start ON_NextInvoice Date Specifies the next billing date. If no value is defined, it will be substituted by the maximum of the invoice run start date, subscription start date or item start date. When the invoice is set Open, it is incremented to the current invoice line item's
    service period end date + 1 day
    Start Date ON_StartDate Date
    Formula (Date)
    The start date from which this item is active (may be empty)
    End Date ON_EndDate Date
    Formula (Date)
    The date until which this item is active (may be empty)
  3. Depending on your business requirements, create the following optional fields in addition.

    Field Label API Name Data Type Description
    Billing Period ON_BillingPeriod Number(2, 0) Defines the time interval (in days, months or years) after which the item is considered in the invoice run.
    Billing Unit ON_BillingUnit Picklist
    Formula (Text)
    Defines the time unit for the billing period to be displayed on the invoice and which is used for the price calculation of the billing period. Supported values are Day, Month and Year.
    Sync With ON_SyncWith Picklist
    Formula (Text)
    Specifies a time with which the next invoice date of a recurring item is to be synchronized. Possible values include Start of next year, Start of next fiscal year, Start of next month, Start of next quarter, Start of next fiscal quarter, Start of next half year, Start of next fiscal half year.
    Billing Practice ON_BillingPractice Picklist
    Formula (Text)
    Defines the billing practice for recurring items. Possible values include Advance (to be billed as soon as possible) or Arrears (to be billed at the end of its service period).
    Be aware that the source object records will not be considered upon generating subscription bookkeeping data.

Applying Invoice Criterion

Your business may require to group and separate invoice line items along a specific criterion - only invoice line items with the same criterion are to be included in one invoice, others are invoiced separately. To support this, JustOn makes use of invoice criteria, which are a means for controlling the distribution of invoice line items.

To enable the invoice criterion, add the corresponding field to the source object from which the invoice line items are generated.

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

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

    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

In one generic invoice run, the following custom object records

Account Title Invoice Criterion
My Company Product 1 A
My Company Product 2 A
My Company Product 3 B

produce two invoices with one service period for "My Company" with the following invoice line items:

(1) invoice for criterion A

Invoice Line Item
Product 1
Product 2

(2) invoice for criterion B

Invoice Line Item
Product 3

Propagating Associated Documents

During the generic invoice run, JustOn can link documents that are associated to (parent or child) source records with the resulting invoice. The linked documents are then attached to the invoice upon distribution (emailing, etc.) and sent to the corresponding recipient.

Info

The support for linking associated documents is available as of JustOn 2.61.

To allow a fine-grained control over which (of possibly multiple) documents are shared with the invoice recipients, the setting is made on document basis. To this end, you create a new custom checkbox field on the Content Version object.

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

    Field Label API Name Data Type
    Link to Invoice ON_LinkDocument Checkbox
    Formula (Checkbox)

    Your business may require to automatically select the checkbox depending on certain conditions. In this case, create a formula field with the return type Checkbox, where the formula represents the intended logic. Otherwise, create a simple checkbox and let users select it manually.

    For help about creating fields, see Managing Object Fields.

Once the checkbox is selected for a content version record, the corresponding document will be linked with the invoice produced during the generic invoice run.

Enabling Arbitrary Object Billing to Multiple Parties

Generally, JustOn is set up to issue invoices to one recipient, usually via the account associated to the corresponding source record. 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:

  1. Create multiple (recipient-specific) sets of ON fields as listed in Setting Up Parent-Child Objects or Setting Up Single Object.

    For details, see Creating Recipient-Specific Controlling Fields.

  2. Create multiple (recipient-specific) invoice run filters as described in Creating Invoice Run Filter.

    For details, see Creating Recipient-Specific Filters.

  3. Optionally, configure the multiple currency billing as required.

    For details, see Configuring Multiple Currency Billing.

Return to JustOn Administration.