Skip to content

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 a parent-child relationship: 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.

See Setting Up Parent-Child Objects

There may be, however, data in addition to the configured fields for objects in a parent-child relationship (your orders and order products), or from customized source objects whose records hold all information. If you need to create invoices based on this data, which is not accessible otherwise, you set up specific data mappings to retrieve it.

See Setting Up Data Mapping

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.

Info

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

Setting Up Parent-Child Objects

You can generate invoices based on 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 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) The record will be invoiced when the date is null or within the service period of the invoice run.
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.
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.

Another optional field is:

Field Label API Name Data Type Description
Invoice Criterion ON_InvoiceCriterion Text (255) Allows for grouping invoice line items: Only invoice line items with the same criterion are included in an invoice.
The scope of the criterion is limited to draft invoices, the current invoice run, and the service period of the current invoice run.
If empty or not set, it is considered an empty criterion, which, consequently, does not distribute the invoice line items to multiple invoices.

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

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

ir_mapping
Creating invoices based on a mapping

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 (parent) 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 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 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
    Orders Order OrderItems Cstm Generic
    Cases Case Generic

    For help about creating filters, see Filters.

Info

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

Note

The use case for filters must always be Generic.

Enabling Invoices Generation

You must create an invoice run filter.

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

Adding Invoice Build Button Component (Salesforce Lightning)

To add a new button for manual invoice generation to the record detail page in Salesforce Lightning:

  1. Open a record detail page of the target object.

    Navigate to an opportunity, order, etc. as required.

  2. Click to open the Setup menu, then select Edit Page.

  3. Drag the custom Lightning component NewInvoiceFromSObject to the intended region of the record page.
  4. Click Save, then Activate.

    This allows you to manually trigger the invoice build process from the detail page of the configured target object (opportunity, order, etc.) by clicking the New Invoice button.

    For details about editing Lightning pages, see Create and Configure Lightning Experience Record Pages in the Salesforce Help.

Creating Invoice Build Button (Salesforce Classic)

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

  • Creating the button
  • Adding the button to the record detail page

To create the button:

  1. Navigate to the Buttons, Links, and Actions page of the target object.
  2. Create the following button.

    Detail Value
    Label New Invoice
    Display Type Detail Page Button
    Behavior Execute JavaScript
    Content Source OnClick JavaScript
    Content window.location.href = '/apex/ONB2__NewInvoiceFromSObject?id={!ObjectAPIName.Id}';
    You must replace ObjectAPIName with the API name of your target object.

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

To add the button to the page layout:

  1. Navigate to the page layout definition of the target object.
  2. Add the new button to the page layout.

    This allows you to manually trigger the invoice build process from the detail page of the configured target object (opportunity, order, etc.).

    For help about modifying page layouts, see Managing Page Layouts.

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.

    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.