Skip to content

Setting Up Invoice Distribution With Basware

JustOn can send electronic invoices to the Basware Network Services, through which they are distributed to the recipients.

Info

The Basware integration is available as of JustOn 2.46.

Basware Integration Concepts

JustOn sends the electronic invoice data as well as according 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 E-Invoice on the invoice list view (see Sending E-Invoices).
  • 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:

Note

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

Configuring Basware Access

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

  1. In Setup, open Named Credentials.
    In Salesforce Lightning, navigate to Security > Named Credentials.
    In Salesforce Classic, navigate to Security Controls > Named Credentials.
  2. Click New Named Credential.
  3. 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.

  1. Navigate to the fields list of the Invoice object.
  2. Create the following new fields as required.
    For help about creating fields, see Managing Object Fields.
Label API Name Type Required 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 Text 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.

In addition, you can create optional fields on the Invoice object and the Invoice Line Item object.

Object Label API Name Type Basware Description
Invoice Printing Preference BaswarePrintingPreference Text Indicates the printing preference. This optional field can be specified to allow printing delivery with PrintingAllowed or force the document to be delivered by printing with PrintingAlways. If this field is not specified, delivery will be by eInvoicing.
Invoice 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.
Invoice Line Item Service Indicator BaswareServiceIndicator Checkbox Flag indicating whether the invoice line item represents goods or services (true if services, false if goods).

Info

You can use the ON field mechanism to transfer the values from another object, like Account, Opportunity or Subscription.
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

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 Tenant

Depending on your business setup, you may need to support multiple suppliers, represented as tenants. In order to handle the supplier information when distributing invoices via Basware, you specify an endpoint for the supplying party. To this end, you must add two new fields to the Tenant custom setting, which can then hold the corresponding data.

Info

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

  1. Navigate to the fields list of the Tenant custom setting.
  2. Create the following new fields.
    For help about creating fields, see Managing Object 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 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

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 Basware API Documentation, section API for Invoices V2 > POST > Request schema.

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 tenant, invoice or invoice line items,
  • or directly be specified in a corresponding field on the invoice or invoice line items.
Objects API Name Type Description
Tenant, 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 tenant 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 IBAN and BIC to the paymentMeans data structure
[
    {
        "path":["data", "paymentMeans", "financialAccounts", "[0]", "financialInstitutionName"],
        "fragment":"BARCGB22"
    },
    {
        "path":["data", "paymentMeans", "financialAccounts", "[0]", "ids", "[0]", "id"],
        "fragment":"GB54BARC20992012345678"
    },
    {
        "path":["data", "paymentMeans", "financialAccounts", "[0]", "ids", "[0]", "schemeId"],
        "fragment":"IBAN"
    }
]

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

Write order number to the orderLineReference data structure for each invoice line item
[
    {
        "path":["orderLineReference", "lineId"],
        "fragment":"12345"
    }
]

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.

Adding E-Invoice Button

To enable the option for sending invoices to Basware from the invoices list view, add the Send E-Invoice button to the invoices list view. To do so:

  1. Navigate to the object management settings of the Invoice object.
  2. Click Search Layouts.
  3. Click Edit in the row of the Invoices List View.
  4. In the Custom Buttons section, move Send E-Invoice to the Selected Buttons column.
  5. Click Save to save the modified page layout.
    For help about modifying page layouts, see Managing Pages.

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

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:

  1. Navigate to the fields list of the Basware Status object.
  2. Create the new field as shown below.
    For help about creating fields, see Managing Object Fields.
Field Label API Name Data Type
Request Body PostDocumentRequestBody Long Text Area (32768)

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:

  1. Navigate to the object management settings of the Basware Status object.
  2. Click Page Layouts.
  3. Click Edit in the row of the Basware Status Layout.
  4. Select the Buttons palette.
  5. Drag the Update Document Request Body button to the Custom Buttons area.
  6. 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, 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:

  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/apex/ONB2__JobsSetup to your org's domain name.
    As of JustOn 2.52, you can access the Scheduled Jobs page via the JustOn configuration app (App Launcher > JustOn Configuration > Jobs Setup).
  2. From the Apex Job drop-down list, select Basware Notifications Job.
    The Job Name field is automatically set to ScheduledBaswareNotifications.
  3. From the Start Time drop-down list, select the preferred execution time.
  4. Optionally, edit the displayed cron expression to adjust the execution time.
  5. 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:

  1. In Setup, 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
    • Apex Class: ScheduledBaswareNotifications
    • Frequency: Weekly or Monthly (with an according weekday or day of month setting)
    • Start
    • End
    • Preferred Start Time
  4. 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.

Next Steps:

Sending E-Invoices

Return to JustOn Administration.