action.skip

Invoice Import and Fix

JustOn Billing & Invoice Management allows for creating invoices without using JustOn's business processes (like invoice run). This is necessary, for example, when migrating data from previous systems to JustOn. In some cases, imported invoices may not be valid in some parts (for example, balance, due dates, texts, addresses) and therefore need to be fixed after the import.

Info

The invoice fixing feature is available as of JustOn Billing & Invoice Management 2.42.

This article

Info

The invoice import is project-specific and therefore not covered with this documentation. Generally, you can use any Salesforce API to insert invoice records:

Preparing Data Sources

Generally, the invoice import is project-specific as it depends on your business requirements and your system environment.

A common approach, however, is preparing CSV files (preferably UTF-8 encoded), which are to be inserted using the Data Loader, Workbench or Data Import Wizard. Following this approach, JustOn recommends to separate the import process in five steps:

  • Preparing data source for invoices, that is, a CSV file that provides the invoice records without invoice line items
  • Creating empty invoices
  • Setting account data on the invoices
  • Preparing data source for invoice line items, that is, a second CSV file that provides the invoice line item records
  • Creating the invoice line items

For a detailed description of how to import invoices and invoice line items using the Data Loader, see How to import invoices using the Data Loader?

Info

Before starting, you may want to watch the Salesforce video series How to import data into Salesforce.

Invoice Record Data

JustOn Billing & Invoice Management requires the following fields to insert an invoice record:

Field Possible Values Notes
Status Pre-Draft
Pre-Open
The status must be prefixed with Pre- in order to allow the import.
Pre-Draft invoices will have the status Draft after fixing.
Pre-Open invoices will have the status Open after fixing.
Name existing invoice number The invoice number of Pre-Open invoices will not be replaced.
Make sure that the invoice number is correct and unique.
Account Salesforce account ID or
External ID of the Salesforce account
An invoice must be associated with an existing account in Salesforce. If the account ID is is not available, you can use external IDs instead.
Template JustOn template ID or
External ID of the JustOn template
An invoice must be associated with an existing template. You can associate the template by its ID or by using external IDs.
Date empty | existing date
Format: YYYY-MM-DD
If the date is empty, JustOn will use the current date when finalizing the invoice.
Currency ISO Code one of the active currencies, like EUR, USD This is only applicable in multi-currency organizations. If no currency is set, the system will copy the currency from the account.

All other invoice fields are optional. Commonly used information include, for example, service period start/end date, related subscription, related invoice run, business entity, related balance, payment due as well as bank information or address data.

For information about additional fields that can be set during the invoice fixing process, see Imported Invoices Fix.

Invoice Line Item Record Data

JustOn Billing & Invoice Management requires the following fields to insert invoice line item records:

Field Possible Values Notes
Invoice JustOn invoice ID or
External ID of the invoice (preferably the existing unique invoice number)
Invoice line items must be associated with an invoice record. This can be done by using the Salesforce ID of the invoice record or by using external IDs instead.
Pre- type invoice line items can only be associated with Draft/Pre-Draft/Pre-Open invoices.
Type Pre-Product
Pre-Shipping Fees
The type must be prefixed with Pre- in order to allow the import.
Pre-Product invoice line items will have the type Product after fixing.
Pre-Shipping Fees invoice line items will have the type Shipping Fees after fixing.
Title the title of the invoice line item The title is displayed on the invoice PDF and names the sold product or service.
Unit Price the price for one unit of the sold product or service The unit price is interpreted as a net value unless the invoice is marked as a gross invoice.
Quantity the sold quantity
Tax Rate the tax rate of the invoice line item If there is a tax rule applicable to the invoice line item, the fixing process will modify the tax rate accordingly.
Currency ISO Code one of the active currencies, like EUR, USD This is only applicable in multi-currency organizations. If no currency is set, the system will copy the currency from the invoice.

All other invoice line item fields are optional. Commonly used information include, for example, product group or service period start/end date.

For information about additional fields that can be set during the invoice fixing process, see Imported Invoices Fix.

Imported Invoices Fix

Imported invoices in status Pre-Draft/Pre-Open and invoice line items with a Pre- type are ignored by JustOn Billing & Invoice Management. They need to be fixed in order to be available. With the fixing process, Pre-Draft invoices get the status Draft, Pre-Open invoices get the status Open.

Note

Imported Pre-Draft invoices are subject to the usual operations for draft invoices after fixing.

Imported Pre-Open invoices are unalterable (and immediately effective) after fixing, like all finalized invoices.

JustOn Billing & Invoice Management executes the following business processes upon invoice fixing on all empty invoice fields:

Pre-Draft/Pre-Open

  • set contacts from contact roles
  • set contacts from ON fields
  • copy addresses
  • set account name
  • set business entity
  • set ISO currency code
  • set payment due
  • set payment fields (bank info)
  • copy ON fields from account
  • calculate service period
  • set balance and payment status

Pre-Open

  • set date
  • set conversion rate
  • copy and render template fields
  • render invoice line item fields

JustOn Billing & Invoice Management executes the following business processes upon invoice fixing on all empty invoice line item fields:

  • set ISO currency code
  • set gross invoice
  • set sequence
  • set factor (from the unit)
  • set discount amount
  • set order discount amount
  • set accounting fields

If there is a tax rule applicable to the invoice line item, the fixing process will also modify the tax rate accordingly.

Calling the Invoice Fixing Process

JustOn Billing & Invoice Management provides several options for invoking the invoice fixing process after the import.

Batch Process From JustOn Invoices List View

  1. Add the button Fix Invoices to the invoices list view.

    For details, see Managing Page Layouts.

  2. Create a list filter to show only Pre-Draft/Pre-Open invoices.

  3. Use the button to fix all or the selected invoices.

    This executes the batch process BatchFixInvoices.

Info

Use this for one-time migrations during the initial setup of JustOn.

Batch Process From APEX Code

If you use APEX to create invoices, you may consider executing the batch process for a list of invoices. Please note that this cannot be called from a trigger context, because the batch is running asynchronously and cannot operate on a single invoice.

Use the following code snippet to create and execute the batch:

Set<Id> invoiceIds = new Set<Id>{'id1' ,'id2'}; //provide the IDs of all Draft/Pre-Draft/Pre-Open invoices that need to be fixed

new ONB2.ChainRunner().execute(
    new ONB2.ChainFactory().getForBatchNames(
        new List<String>{'BatchFixInvoices'}
    )
    .setParameters(
        new Map<String, Object>{
            'invoiceIds' => invoiceIds
        }
    )
);

Synchronous Execution From APEX Code

If the number of invoices is small (< 10) and your APEX code is guaranteed to run sequentially (no triggers, no queueables, no batch processes, no external parallelization), you may call the global API directly:

List<Id> invoiceIds = new List<Id>{'id1' ,'id2'}; //provide the IDs of all Draft/Pre-Draft/Pre-Open invoices that need to be fixed

ONB2.FixInvoicesApi.fromProcess(invoiceIds);

REST Endpoint Call

If you create invoices via REST, JustOn Billing & Invoice Management allows you to fix these invoices via REST as well. Please note that the number of invoices that can be fixed in one call should not exceed 10. You should also not call the API in parallel.

JustOn Billing & Invoice Management accepts an HTTP POST request at the following endpoint:

https://INSTANCE.salesforce.com/services/apexrest/ONB2/FixInvoicesApi

The body of the request must be in JSON format and contain a list of invoice IDs to be fixed:

{"invoiceIds":["id1","id2"]}

Flow Configuration

You can trigger the invoice fix using a flow on invoices that calls the appropriate Apex class provided by JustOn. This is useful, for example, if you create invoices from a flow or do not want to call the REST endpoint. When using a flow, the number of invoices per transaction should not exceed 10.

Note

Depending on your use cases, the criteria for executing the flow will vary.

  1. Click to enter Setup, then navigate to Process Automation > Flows.
  2. Click New Flow.
  3. Select Record-Triggered Flow and click Create.
  4. Configure the Start element.

    Option Description
    Object The object whose record modifications are to update a source record, must be Invoice
    Trigger The type of record change that triggers the flow, must be A record is created or updated
    Conditions The use case-specific trigger conditions, one or more filter criteria for evaluating certain field values or a formula for evaluating records
    Optimize for Actions and Related Records
  5. Click and add the following Action element.

    Option Description
    Action The Apex class to call, must be Fix Invoices and Line Items
    Input Values Invocable variables for the Apex class
    invoiceIds: specifies the reference to the ID field of the relevant invoices, like {!$Record.Id}

    Specify a label and an API name as required.

  6. Click Save.

    Specify a label and an API name as required.

  7. Click Activate.

    When the defined conditions are met, JustOn will trigger the invoice fix.

    For help about creating flows, see Flows in the Salesforce Help.