Billing Arbitrary Objects

← Setting Up Billing Automation

JustOn Billing & Invoice Management 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.

Note

The generic invoice run does not work with Line Item Schedule (OpportunityLineItemSchedule) records as source. This Salesforce object does not allow accessing other objects (in particular, Opportunity Product) via formula fields, making it impossible to retrieve invoice run-relevant data.

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.

Enabling the generic invoice run involves at least the following steps:

• Preparing the source objects to hold the billing-relevant data
• Creating an invoice run filter to determine which records to process
• Enabling the invoice creation

In addition, the generic invoice run supports a number of options to cover specific use cases.

Preparing Source Objects

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

• Parent-child objects

  ---

  Billing data in parent-child records
  Parent → invoice
  Child → invoice line item

• Single objects

  ---

  Billing data in single records
  Marked as single source
  Record → invoice + invoice line item

• Data mapping

  ---

  Flexible data mapping
  Specific relations or values

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.

Info

When executing the generic invoice run, JustOn

• Creates a lookup relation from the billed source record to the produced invoice

  To this end, you must properly set up the ON_Invoice field (see Configuring Parent Object or Setting Up Single Object). Setting this field marks a record as invoiced, preventing it from being invoiced again.

  If the produced invoice is canceled, the object records become subject to the invoice run again.

• Writes information about the billed source record 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.

Optionally, you can, in addition, have JustOn create lookup relations from the invoices to the original source records (see Enabling Lookup to Sources).

Setting Up Parent-Child Objects

You can generate invoices based on source objects that are in a parent-child relationship, like, for example

• orders with order products
• opportunities with opportunity products
• quotes with quote lines

or other parent-child objects. 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.

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 to hold the billing-relevant data. Consequently, preparing parent-child objects involves:

• Configuring the parent object
• Configuring the child object

In case you need multiple billing configurations, for example, if you want to create two invoices for multiple recipients from the same record, JustOn Billing & Invoice Management 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.

Info

JustOn provides dedicated JustOn Configurator packages to prepare Order and Order Products or Opportunity and Opportunity Products as sources for the generic invoice run.

Configuring Parent Object

1. Navigate to the fields list of the parent object.

2. Create the following new fields as required.

   Mandatory fields on the parent object:

   API Name	Data Type	Description
   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, AccountId.
   ON_Template	Formula (Text)	Specifies the Salesforce ID or name of the related template. The formula can return a dedicated template according to specific criteria – target region, business entity, product group, etc.
   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.
   ON_Invoice	Lookup (Invoice)	The invoice that resulted from this record. If the produced invoice is canceled, the object records become subject to the invoice run again.
   ON_LastInvoiceRun	Lookup (Invoice Run)	Shows the last invoice run that has processed this object.
   ON_InvoiceBuildError	Text (255)	Shows errors that occurred during the last invoice run.

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

   Optional fields on the parent object:

   API Name	Data Type	Description
   ON_CreateSingleInvoice	Formula (Checkbox) Checkbox	Determines whether to create a single invoice for each parent record, ignoring existing invoices.
   ON_IsItem	Formula (Checkbox) 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

   Depending on your use case and its requirements, you may have to copy additional information to the produced invoice. To this end, you add ON fields for the corresponding data to the source object and have the ON field mechanism copy it on invoice creation.

   Examples may include:

   API Name	Data Type	Description
   ON_Tenant	Text(255) Formula(Text)	Specifies the associated business entity if different from the account's business entity.
   ON_EmailContact	Lookup (Contact)	Shows the related contact.

Note

With the generic invoice run, be careful when setting the type for the invoice and the invoice line items using optional ON fields:

• Use ON_Type on the parent object to set the type of the invoice, for example, when generating deposit invoices or pro forma invoices.
• Use ON_LineItemType to set the type of the invoice line item, for example, to distinguish Product from Shipping Fees.

Configuring Child Object

1. Navigate to the fields list of the child object.

2. Create the following new fields as required.

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

   API Name	Data Type	Description
   ON_Title	Formula (Text)	The name or short description of the invoice line item.
   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)
   ON_UnitPrice	Formula (Currency)	Either the net or gross price of one unit of this item.

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

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

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

   Info

   Depending on your use case and its requirements, you may have to copy additional information to the produced invoice line items. To this end, you add ON fields for the corresponding data to the source object and have the ON field mechanism copy it on invoice creation.

Note

With the generic invoice run, be careful when setting the type for the invoice and the invoice line items using optional ON fields:

• Use ON_Type on the parent object to set the type of the invoice, for example, when generating deposit invoices or pro forma invoices.
• Use ON_LineItemType to set the type of the invoice line item, for example, to distinguish Product from Shipping Fees.

Setting Up Single Object

You can generate invoices 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 (ON_IsItem = true), and based on the appropriate configuration, JustOn Billing & Invoice Management produces both invoices and invoice line items from these records.

Creating invoices based on a single object ("IsItem" configuration)

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, most notably the ON_IsItem checkbox (which is why this approach is sometimes called "is item" configuration).

1. Navigate to the fields list of the source object.

2. Create at least the following new fields.

   API Name	Data Type	Description
   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, AccountId.
   ON_Template	Formula (Text)	Specifies the Salesforce ID or name of the related template. The formula can return a dedicated template according to specific criteria – target region, business entity, product group, etc.
   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.
   ON_Invoice	Lookup (Invoice)	The invoice that resulted from this record. If the produced invoice is canceled, the object records become subject to the invoice run again.
   ON_LastInvoiceRun	Lookup (Invoice Run)	Shows the last invoice run that has processed this object.
   ON_InvoiceBuildError	Text (255)	Shows errors that occurred during the last invoice run.
   ON_IsItem	Formula (Checkbox)	If the formula yields true, forces JustOn to use this object as the source for both the invoice and the invoice line items.
   ON_Title	Formula (Text)	The name or short description of the invoice line item.
   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)
   ON_UnitPrice	Formula (Currency)	Either the net or gross price of one unit of this item.

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

   Info

   Depending on your use case and its requirements, you may have to copy additional information to the produced invoice. To this end, you add ON fields for the corresponding data to the source object and have the ON field mechanism copy it on invoice creation.

   Examples may include:

   API Name	Data Type	Description
   ON_Tenant	Text(255) Formula(Text)	Specifies the associated business entity if different from the account's business entity.
   ON_EmailContact	Lookup (Contact)	Shows the related contact.

Note

With the generic invoice run, be careful when setting the type for the invoice and the invoice line items using optional ON fields:

• Use ON_Type on the parent object to set the type of the invoice, for example, when generating deposit invoices or pro forma invoices.
• Use ON_LineItemType to set the type of the invoice line item, for example, to distinguish Product from Shipping Fees.

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.

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 the source object
• Creating the mapping definition

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. Make sure to write all JSON code in a single line without spaces. 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.

   Make sure to write all JSON code in a single line without spaces.

   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. Click to enter Setup, then open Custom Settings.

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

   In Salesforce Classic, navigate to Develop > Custom Settings.

2. Click Manage in the row of Filters.

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

   Filter Field	1	2	3	4
   Name	Orders	Cases	Contracts	Custom Object
   Target	Order	Case	Contract	CustomObject__c
   Child Relation Plural form	OrderItems			CustomObject_Items__r
   Transactional Suffix	Cstm
   Use Case	Generic	Generic	Generic	Generic
   Parent Relationships			{"ON_Account__c": "Account"}

   The filter name must not exceed 38 ASCII characters. Special characters like brackets will be URL encoded, which makes them count three, like ( makes %28.

   For help about creating filters, see Filters.

Info

• The Name must be unique. It will be used as a parameter value when scheduling the invoice run and will be available as an option value when manually triggering the invoice run.
• 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 (in plural form) if you create invoice line items based on child records.

  For standard relations (provided by default between standard Salesforce objects), use the API name of the child object.

  For custom relations (to custom objects or those specifically created in your org), use the relationship name (suffixed __r) of the child object. Be aware that the UI name may not represent the required API name or relationship name. You can use Workbench (or other data tools) to find the correct name.

  If you create invoices based on a single source object (ON_IsItem = true), the field Child Relation must be empty.

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

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

• Automatically using a scheduled job
• Manually executing the invoice run (which does not require further configuration)
• Manually using a custom button

Scheduling Generic Invoice Run

To automatically execute the generic invoice run, you schedule a parameterized invoice run with the corresponding generic filter added as a parameter.

Setting up a parameterized invoice run involves two steps:

• Defining parameters for the batch chain
• Scheduling the batch chain

Configuring Batch Chain Parameters

1. Click to enter Setup, then open Custom Settings.

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

   In Salesforce Classic, navigate to Develop > Custom Settings.

2. Click Manage in the row of Batch Parameters.

3. Click New.

4. Specify the details as required.

   • Name: Must match the Job Name to be set when scheduling the job
   • Batch Chain: InvoiceRunChain

   • Parameter 1: InvoiceRunFilter = <name>

     Make sure to set the invoice run filter name as defined in Creating Invoice Run Filter.

     You can set additional parameters as required.

5. Click Save.

Scheduling Batch Chain

To schedule the batch chain, you can use either JustOn's Scheduled Jobs page or Salesforce's Schedule Apex functionality. For details, see Scheduling a Job.

Via JustOn's Scheduled Jobs page:

1. Open the Scheduled Jobs page.

   Use the following URL https://login.salesforce.com/apex/ONB2__JobsSetup, or, if you are already logged in, append apex/ONB2__JobsSetup to your org's domain name.

   You can access the Scheduled Jobs page via the JustOn configuration app ( > JustOn Configuration > Jobs Setup).

2. From the Apex Job drop-down list, select Batch Chain Job.

3. In the Job Name field, specify the name of the batch parameters setting created before.

4. From the Start Time drop-down list, select the preferred execution time.

   Your business may require to schedule multiple invoice runs. In order to prevent concurrent access to records or batch job limitations, they should, however, not run in parallel. Therefore, JustOn recommends to involve a certain time delay between the scheduled invoice runs – for example, one at 00:00, the next at 01:00, and so on. The interval may vary depending on the amount of records to be processed.

5. Click Schedule.

   This sets up the invoice run to be executed on a regular basis at the specified time with the additional parameters set.

Info

From the Scheduled Jobs page, you can also run the batch chain immediately.

Via Salesforce's Schedule Apex functionality:

1. Click to enter Setup, then open Apex Classes.

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

   In Salesforce Classic, navigate to Develop > Apex Classes.

2. Click Schedule Apex on top of the list.

3. Specify the details as required.

   • Job Name: The name of the batch parameters setting created before
   • Apex Class: ScheduledBatchChain
   • Frequency
   • Start
   • End
   • Preferred Start Time

   Your business may require to schedule multiple invoice runs. In order to prevent concurrent access to records or batch job limitations, they should, however, not run in parallel. Therefore, JustOn recommends to involve a certain time delay between the scheduled invoice runs – for example, one at 00:00, the next at 01:00, and so on. The interval may vary depending on the amount of records to be processed.

4. Click Save.

   This sets up the invoice run to be executed on a regular basis at the specified time with the additional parameters set.

For more details about job scheduling, see Scheduling a Job in the JustOn documentation and Schedule Apex in the Salesforce Help.

Adding Invoice Build Button

Your business may want to allow users to manually trigger the invoice build process from the detail page of the configured source or parent object (opportunity, order, etc.). To this end, you create the invoice build button and add it to the relevant record detail page:

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.

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

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

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

8. Click Save.

   This allows users to manually trigger the invoice build process from the detail page of the configured source or parent object by clicking the New Invoice button.