Setting Up Invoice Distribution With Basware

When operating certain markets, your business may require to distribute electronic invoices – structured invoice data that is exchanged electronically between trading partners in order to automate accounts payable processing.

Be aware that there are various e-invoice formats, distribution channels, and operators (see Creating E-Invoices). To help getting a wider reach, JustOn Billing & Invoice Management integrates with the Basware Network. This global e-invoicing network supports many protocols and document formats, and interoperates with a large number of partner networks.

Once set up,

JustOn sends the invoice data as well as relevant file attachments, like the invoice PDF, to the Basware Network, and
Basware generates legally valid electronic invoices and transfers them to the recipients – either directly or via partner networks.

basware
Distributing invoices through Basware

Basware Integration Concepts

JustOn sends the electronic invoice data as well as relevant file attachments, like the invoice PDF, to Basware. Based on the transferred data, Basware generates legally valid electronic invoices and distributes them to the recipients.

Info

Prior to using Basware, your organization must become part of the Basware Network, which is subject to a (chargeable) contract.

The following concepts are important for understanding the Basware integration:

The recipient endpoint is the recipient's electronic delivery address (see Recipient endpoints in the Basware API Reference).
The Basware Status is a "helper" object in JustOn used to track the data transfer status, which is linked to the invoice.

This is how the data transfer from JustOn to Basware takes place:

When a user finalizes an invoice that has a recipient endpoint set, JustOn creates a Basware Status record. Only invoices that have a Basware Status record are considered for distribution.
If configured accordingly, the user can review the data to be sent to Basware.
The user clicks Send to Basware on a single invoice or the invoice list view (see Sending E-Invoices).

When (re)sending an invoice to Basware, JustOn creates a new Basware Status record. For the most recent record, the checkbox Is Latest is selected. You can use this information for reporting purposes, for example.
JustOn transfers the invoice attachments (all attached files except for HTML files) using the batch process BatchBaswareFileUpload.
JustOn transfers the invoice data (invoice line items, invoice amount, etc.) using the batch process BatchBaswareInvoiceUpload.

JustOn updates the Basware status of the invoice.

The following Basware statuses are available:

Status	Description
Unsent	The initial status upon creation.
File Error	States that some attachment uploads have failed.
Files Sent	States that the batch process BatchBaswareFileUpload has completed successfully and the attachments are uploaded to Basware.
Invoice Error	States that the batch process BatchBaswareInvoiceUpload has completed with errors and that the invoice data upload has failed.
Finished	States that the invoice transfer (both the file and data upload) to Basware has completed successfully. Invoices with the Basware status `Finished` are not considered for further transfer processes.

For technical details about the Basware status object and information about the data sent to Basware, see Basware Implementation Details.

Setting Up Basware Integration

Setting up the invoice distribution with Basware involves these configuration tasks:

Configuring the access to Basware
Adding Basware-specific fields to the Invoice object
Adding Basware-specific fields to the Business Entity custom setting
Optionally, configuring additional information to be sent to Basware
Adding the Send to Basware action to the invoices list view or the invoice layout
Optionally, enabling the data review
Enabling the notification retrieval from Basware

Note

Be aware that when using the Basware integration, you must set up a business entity to be assigned to the invoices. Make sure to specify the complete address information for the business entity.

The following instructions include the minimum required fields. Depending on your business context (type of products or services sold, target markets, etc.), Basware may, however, require additional fields to be set, and produces errors if they are missing. For generally acknowledged and project-approved recommendations for setting up the Basware-specific fields, see Best Practice: Basware Setup.

Configuring Basware Access

The Basware integration uses a Named Credential to access Basware. To add a named credential for your Basware access:

Click to enter Setup, then open Named Credentials.

In Salesforce Lightning, navigate to Security > Named Credentials.

In Salesforce Classic, navigate to Security Controls > Named Credentials.
Click New Named Credential.

Specify the following information, then click Save.

Field	Value	Notes
Label	`BaswareEndpoint`
Name	`BaswareEndpoint`	Must be exactly as specified here.
URL	`https://api.basware.com`	Production: `https://api.basware.com` Sandbox: `https://test-api.basware.com`
Identity Type	`Named Principal`
Authentication Protocol	`Password Authentication`
Username		Your Basware REST API user name. This is not your Basware account name.
Password		Your Basware REST API password.

Adding Basware Fields to Invoice

For the delivery of an invoice and its documents, you must specify the recipient endpoint on the invoice. To this end, you must add two new fields to the Invoice object.

Navigate to the fields list of the Invoice object.

Create the following new fields as required.

Label	API Name	Type	Description
Recipient ID	BaswareRecipientId	Text	The identifier of the recipient, typically a string or a number derived from a registry number. Can be, for example, a VAT number, an IBAN or an email address.
Scheme ID	BaswareSchemeId	Picklist	The type of the identifier, for example, `VAT` or `IBAN`. Create picklist values for all eligible endpoint scheme IDs. If the scheme ID is not known, the identifier must be a globally unique value.
Payment Identifier ID	BaswarePaymentIdentifierId	Text	A unique identifier of the (requested) payment, like the KID number in Norway or the Finnish Reference Number. Required for some countries.

For details about valid values of the two fields, see Recipient endpoints in the Basware API Reference.

Info

Recipient ID and Scheme ID are account-specific. Ask your customers to provide their individual IDs.

Depending on your project implementation, you can store these values on the account, a subscription or another object. Then use the ON field mechanism, Salesforce flows or other automation tools to transfer the values to the invoice.

If the recipient ID is stored, for example, in the field ON_BaswareRecipientId__c of an account, JustOn copies the ID to the corresponding Invoice field when creating the invoice.

Note

Be aware that some countries use specific payment references to identify vendors, buyers or invoices, like the KID number in Norway or the Finnish Reference Number. When required, this information must be propagated to the custom Invoice field BaswarePaymentIdentifierId__c. Basware includes this information in the field paymentIdentifier.id of its paymentMeans object, and produces an error if it is missing.

In addition, you can create optional fields on the Invoice object:

Label	API Name	Type	Basware Description
Action	BaswareAction	Text	Defines what action will be performed. If `startDelivery` is specified, the business document will be delivered immediately. If `startTransmission` is specified, the business document will be delivered immediately without any processing. Possible values are `store` (default), `startDelivery` or `startTransmission`.

Note

You may have contracted Basware to print invoices (and, consequently, have set a printing preference) and to post them locally in the corresponding destination countries. In this case, you may need to provide customized invoice templates that comply with the destination country's postal regulations. If you have contracted international postal deliveries, one generic template may be sufficient.

Adding Basware Fields to Business Entity

In order to handle the supplier information when distributing invoices via Basware, you specify an endpoint for the supplying party on the relevant business entity. To this end, you must add two new fields to the Business Entity custom setting, which can then hold the corresponding data.

Info

If you do not want or need to set the endpoint for a given business entity, you can leave the fields empty.

Navigate to the fields list of the Business Entity custom setting.

Create the following new fields.

Label	API Name	Type	Description
Recipient ID	BaswareRecipientId	Text	The identifier of the supplier, typically a string or a number derived from a registry number. Can be, for example, a VAT number, an IBAN or an email address.
Scheme ID	BaswareSchemeId	Text	An eligible endpoint scheme ID, representing the type of the identifier, for example, `VAT` or `IBAN`. If the scheme ID is not known, the identifier must be a globally unique value.

For details about valid values of the two fields, see Recipient endpoints in the Basware API Reference.

Sending Additional Information to Basware

Generally, JustOn supports many additional Basware fields to be copied to the Basware invoice data structure. For a complete list of supported Basware fields, see Data Transferred to Basware. Lastly, the fields to be used depend on your business requirements, in particular the supplier and customer addresses.

The Basware invoice data structure holds a number of fields that are not mapped by JustOn in the default configuration. This is because not all Basware users need all data. For a complete overview of all possible data points, refer to the Request schema reference of the POST invoices method in the Basware API Documentation.

JustOn allows for appending additional data to the invoice request to be sent to Basware. The additional data is defined in JSON notation and can

either be stored in a Salesforce document to be referred to on the business entity, invoice or invoice line items,
or directly be specified in a corresponding field on the invoice or invoice line items.

Objects	API Name	Data Type	Description
Business Entity Invoice Invoice Line Item	BaswareMappingId	Text(18)	Holds the ID of a Salesforce file (ContentDocument) that contains the additional data definition as a valid JSON configuration.
Invoice Invoice Line Item	BaswareMapping	Long Text Formula	Specifies the additional data definition as a valid JSON configuration.

The JSON contains a list of payloads, which hold the additional data. Payloads specify a path and a fragment. The basic structure looks as follows:

[
    {
        "path":["data","foo","[0]","bar"],
        "fragment":"the value"
    },
    ...
]

With respect to payloads, be aware of the following characteristics:

The path contains all keys or list elements that need to be accessed in order to put the fragment to the correct position.
If a path part contains a number in brackets, it is interpreted as a list position.
If the payload is defined on the business entity or invoice, the JSON is anchored at the root of the resulting request.
If the payload is defined on the invoice line item, the JSON is anchored at the invoice lines > items data structure.

Write additional IBAN and BIC to paymentMeans at array position 1

[
    {
        "path":["data", "paymentMeans", "financialAccounts", "[1]", "financialInstitutionName"],
        "fragment":"BARCGB22"
    },
    {
        "path":["data", "paymentMeans", "financialAccounts", "[1]", "ids", "[0]", "id"],
        "fragment":"GB54BARC20992012345678"
    },
    {
        "path":["data", "paymentMeans", "financialAccounts", "[1]", "ids", "[0]", "schemeId"],
        "fragment":"IBAN"
    }
]

This JSON can be placed in a file referred to by the field BaswareMappingId on the business entity.

Write delivery date to delivery.actualDeliveryDate for each invoice line item

[
    {
        "path":["delivery", "actualDeliveryDate"],
        "fragment":"2019-12-31"
    }
]

This JSON can be placed in a field BaswareMapping on the invoice line item. The field can either be a formula that creates the JSON above, or can be filled using another process, like the ON field mechanism or the process builder.

Write discount to allowanceCharges

To transfer, for example, discount information – on the condition that it exists – from the invoice line item to Basware, you can use the following formula in BaswareMapping on the invoice line item:

'[' +
IF(ONB2__DiscountAmount__c != 0,
'{"path":["allowanceCharges","[0]","chargeIndicator"],"fragment":false},' +
'{"path":["allowanceCharges","[0]","amount"],"fragment":' & TEXT (ABS(ROUND(ONB2__DiscountAmount__c,2))) & '},' +
'{"path":["allowanceCharges","[0]","multiplierFactorNumeric"],"fragment":0' & TEXT (ONB2__Discount__c) & '}'
,''
) +
']'

Now if there is a discount amount, this formula produces a JSON mapping that sets the relevant fields in the allowanceCharges data structure, which Basware uses to hold discount information:

chargeIndicator = false marks a discount
amount holds the absolute value of the discount amount (rounded to two decimal places)
multiplierFactorNumeric specifies the discount rate

Handle credit invoice line item (w/ negative amount)

To transfer an invoice line item with a negative amount to Basware, you can use the following formula in BaswareMapping on the invoice line item:

'[' +
IF(ONB2__Invoice__r.ONB2__Class__c = 'Invoice' && ONB2__UnitPrice__c < 0,
'{"path":["quantity","amount"],"fragment":' & TEXT (ONB2__CalculatedQuantity__c * ONB2__CalculatedBillingFactor__c *-1) & '},' +
'{"path":["price","amount"],"fragment":' & TEXT (ABS(ONB2__UnitPrice__c)) & '}'
,''
) +
']'

Now if there is a credit line item (or another invoice line item with a negative amount), this formula produces a JSON mapping that converts the quantity into a negative value and uses the absolute amount. This prevents Basware validation errors but achieves the same result.

Handle tax delta

Your business may require to use Tax Delta invoice line items in order to adjust for tax rounding differences. These invoice line items always have a quantity of 0, but Basware does not accept zero quantities.

So to transfer an invoice line item of the type Tax Delta to Basware, you can use the following formula in BaswareMapping on the invoice line item:

'[' +
IF(ONB2__Title__c = 'Tax Delta' && ISPICKVAL(ONB2__Type__c, 'Tax Delta') && ONB2__Quantity__c = 0,
'{"path":["quantity","amount"],"fragment":' & TEXT (1) & '},'
+
'{"path":["price","amount"],"fragment":' & TEXT(0) & TEXT (Absolute_Amount__c) & '}',
''
) +
']'

Now if there is a tax delta invoice line item, this formula produces a JSON mapping that converts the quantity into 1.

Adding Basware Button to Invoice List

To enable the option for sending invoices to Basware from the invoices list view, add the Send to Basware button to the invoices list view.

Navigate to the object management settings of the Invoice object.
Click List View Button Layout.
Click Edit in the row of the Invoices List View.
In the Custom Buttons section, move Send to Basware to the Selected Buttons column.
Click Save to save the modified page layout.

For help about modifying page layouts, see Managing Pages.

Adding Basware Action to Invoice Layout

To enable the option for sending an individual invoice to Basware from the invoice detail view, add the Send to Basware action to the invoice record page.

Info

Using dynamic actions, you can generally show or hide actions depending on specific record conditions. With respect to the Send to Basware action on invoices, you must explicitly allow the invoice statuses Open, Paid and Settled only.

Open the Invoice record detail page in the Lightning App Builder.
1. Navigate to an invoice.
2. Click to open the Setup menu, then select Edit Page.
Select the top panel ("Highlights").
Click Add Action and select the action Send to Basware.
Click Add Filter and set the action visibility.
- Record > Status Equal Open
- Record > Status Equal Paid
- Record > Status Equal Settled
Under Show components when, select Any filters are true.
Click Done on the action window, then Save in the Lightning App Builder.

For more details, see Create Dynamic Actions in Lightning App Builder in the Salesforce Help.

Enabling Data Review

Configuring the Basware data transfer may become complex. You can, however, set up JustOn's Basware integration to allow for reviewing the data that will be or has been transferred.

To this end, you

Add the Request Body field to the Basware status, and
Add the button Update Document Request Body to the Basware status layout.

Info

The Basware data review is available as of JustOn 2.51.

Adding Request Body to Basware Status

The Request Body field is an optional field on the Basware Status object that is used to record the data that is sent to Basware. When the Basware status is created, the field contains the data that is to be transferred to Basware. This allows for reviewing the data. Transferring the invoice to Basware updates the field contents – now it contains the complete request body that has actually been sent to Basware.

To create this field:

Navigate to the fields list of the Basware Status object.
Create the new field as shown below.

Field Label API Name Data Type

Request Body PostDocumentRequestBody Long Text Area (32768)

For help about creating fields, see Managing Object Fields.

Info

The Request Body field is just an "output field" that shows which data will be or has been sent to Basware. The contents are not used by JustOn, thus manually modifying the field has no effect.

Adding Update Request Body Button

After modifying the Basware configuration, the data to be transferred may have changed. To review the changes, you must update Request Body field. To this end, you can add the Update Document Request Body button to the Basware status layout. Using this button, you can update the contents of the Request Body field as long as the data has not been transferred to Basware (status is Unsent).

To add the button to the Basware status layout:

Navigate to the object management settings of the Basware Status object.
Click Page Layouts.
Click Edit in the row of the Basware Status Layout.
Add the Update Document Request Body 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.
Click Save to save the modified page layout.

For help about modifying page layouts, see Managing Pages.

Enabling Notification Retrieval

To retrieve Basware notifications for the invoices and, consequently, to enable resubmitting failed transfers, schedule the Basware notifications job. This job updates the Basware Status records, filling the following fields:

Field Name	Description
Notification Response Code	The delivery status of a business document.
Notification Action Code	Detailed information about a business document's processing status.
Notification Description	A text description of the delivery status.
Notification Delivery Means Code	The delivery channel of a business document, for example, `EmailDelivery`.
Get Notification Request Body	Optional field: Contains the JSON response body for the last notification.

Info

All processed notifications will be acknowledged and removed in Basware.

The Basware notifications job does not require additional parameters. That is, you can set up the job directly for the corresponding Apex class ScheduledBaswareNotifications. For details, see Scheduling Concepts.

To schedule the Basware notifications job, 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/ONB2__JobsSetup to your org's domain name.

You can access the Scheduled Jobs page via the JustOn configuration app ( > JustOn Configuration > Jobs Setup).
From the Apex Job drop-down list, select Basware Notifications Job.

The Job Name field is automatically set to ScheduledBaswareNotifications.
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 Basware notification retrieval to be executed at the specified time.

Info

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

Via Salesforce's Schedule Apex functionality:

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.
Click Schedule Apex on top of the list.
Specify the details as required.
- Job Name
- Apex Class: ScheduledBaswareNotifications
- Frequency: Weekly or Monthly (with an according weekday or day of month setting)
- Start
- End
- Preferred Start Time
Click Save.

This sets up the Basware notification retrieval 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.