My ABC

Integration: FileMaker Add-on

To integrate ABCinvoice.eu with FileMaker, the simplest way is to use the ABCinvoice add-on.

Part 1 – Add-on Setup

Notes on this documentation:

  • It is assumed that you already have an Invoices table (referred to below as “Invoices”) linked to an Invoice Lines table (referred to below as “Lines”).
  • If you manage multiple due dates in a separate table, this table will be referred to below as “Due Dates”.
  • Make sure you are running FileMaker Pro version 21 (2024) or later. You can always download the latest version here: for macOS, for Windows.
  • Download the Add-on. Place a free order on the 1-more-thing website, then click the link received by email to install the Add-on.
  • Quit and restart FileMaker Pro.
  • Duplicate your solution to keep a backup (just in case).
  • In your solution, open an invoice layout (the form where you edit invoices, not a print layout).
  • Switch to Layout mode.
  • Install the Add-on (click “+” in the Add-ons panel on the left). Select the Add-on you just downloaded (“ABCinvoice”).
  • Still in Layout mode, drag the Add-on onto your invoice layout.
  • Known potential issue: with older files, when dragging the Add-on, you may see a message saying that no primary key could be detected.
    Primary key error
    Solution: temporarily add a field (type: Text) to your Invoices table defined as an auto-enter serial number with a “unique” validation criteria. Validate and drag the Add-on again. In the next step (relationship graph), replace the temporary field with your real primary key, then delete the temporary one.
  • Check in the relationship graph that links have been created between your Invoices table and the tables ABCinvoice_Attachment and ABCinvoice_LegalLiteral. If not, create them manually (link your Invoices table’s primary key to ABCinvoice_Attachment::idInvoice and ABCinvoice_LegalLiteral::idInvoice).
  • Potential known issue: FileMaker automatically detects what looks like a primary key, but it can sometimes get the field wrong! Make sure that the correct field is used in the relationships. Furthermore, if the recognised primary key in your invoice table is of the Number type, FileMaker will take the initiative to change the type of the fields ABCinvoice_Attachment::idInvoice and ABCinvoice_LegalLiteral::idInvoice to Number. Please reset them to Text.
  • In the relationship options, disable the creation of related records from your Invoices table (you can keep the delete option, which makes sense).
  • Field configuration
    • Copy all fields from the table ABCinvoice_invoiceExample into your Invoices table.
    • Recommended: change the storage options of container fields to external storage.
    • Do the same for the container field in the ABCinvoice_Attachment table (the “file” field).
    • Copy the field from ABCinvoice_invoiceLineExample into your Lines table.
    • Due Dates: if you manage multiple due dates, copy the field from ABCinvoice_InvoiceDueDateExample into your Due Dates table.
    • Edit the fields ABCinvoice_JSONrepresentation_{table} in the Invoices, Lines, and (if applicable) Due Dates tables.
      • Dates must be passed as numbers to ensure compatibility across all systems (client/server). For example:
        GetAsNumber ( Invoices::InvoiceDate )
      • Related data arrays must be passed like this:
        ; [ "invoiceLinesAttributes" ; JSONMakeArray ( List ( Lines::ΩABCinvoiceJSONrepresentation_invoiceLine ) ; ¶ ; JSONObject ) ; JSONArray ]
    • For the due date(s):
      • If you do not manage multiple due dates, use the parameter dueDateAsNumber.
      • If you manage them in a separate table, use the parameter shown in the example.
    • Regarding customer identification, a list of tax identification codes (TIN schemes) is available here.
  • Configure the ABCinvoice_Config script:
    • Define the $config variable, specifying your Invoices table’s primary key and pointing to the fields you just added.
    • Set a working layout (in the “Go to Layout” script step). This layout must represent the table occurrence of your Invoices table corresponding to the fields defined in $config. It is recommended to use a blank layout, in Form view, with no script triggers.
  • Settings
    • Create an account on ABCinvoice.eu and obtain an API key.
    • From the interface (the Add-on you placed on the layout), enter the API key and select your country (the country from which invoices will be issued). Update the legal literals library by clicking Update Legal Literals.
  • Cleanup
    • Delete unused elements that were only provided to assist with configuration: the tables containing the word “Example” and their table occurrences (ABCinvoice_InvoiceExample, ABCinvoice_InvoiceLineExample, ABCinvoice_DueDateExample).

Legal Literals

From the settings, you have just downloaded a library of legal literals corresponding to your country, stored in the ABCinvoice_LegalLiteralLibrary table.

The legal literals appear on invoices (at the bottom of the readable version).

From the Legal Literals popover, you can access and edit the library. For example, in some applications, certain literals may be unnecessary and can safely be deleted.

In Belgium, two sets of literals are downloaded: one in French and one in Dutch. If you are in Wallonia, you may delete the Dutch literals; if you are in Flanders, you may delete the French ones. In Brussels, you might need both.

Literals can be marked as mandatory — for example, the literal referring to discount conditions (even when no discount applies).

Others can be marked as default, meaning they will automatically be added to each invoice when opening the Legal Literals popover.

Finally, some literals contain the placeholder {}, which can be replaced with a custom value.

To do so, you can either modify the default text of the legal literal (for example, if you never grant discounts, you can simply replace the text with “No discount”), or edit the auto-enter calculation of the field ABCinvoice_LegalLiteral::text, as described in the comment of that calculation.

This allows you to replace the {} tag with the information of your choice, depending on the literal’s code.

Part 2 – Adapting your scripts

Attachments: all documents stored in the ABCinvoice_Attachment table will be uploaded along with your invoice.

Note: once uploaded, an attachment cannot be deleted! However, you can still add new attachments as long as the invoice has not been sent.

  • Adding attachments
    • A sample script named ABCinvoice_sample_AddAttachment is provided as an example. However, keep in mind that all you need to do is add the documents related to your invoice in the ABCinvoice_Attachment table. For instance, if your solution already stores invoice PDFs, simply update your original script so it saves the PDF into this related table.
    • Important: in this Attachment table, the field isInvoice determines whether the attachment represents the invoice itself (the invoice PDF). If it does, set the field value to 1 (True). If it does not—such as when adding general terms or a customer statement—set it to 0 (False). The interface provided by the Add-on also lets you check the corresponding box.
  • Several sample scripts are included in the “ABCinvoice – integration example” folder, such as ABCinvoice_sample_CreateInvoice, which creates an electronic invoice. These scripts display dialog boxes when an error occurs; you should adapt them to match your own error-handling workflow. Important: before modifying and using these scripts, it is recommended to duplicate this folder to make future Add-on updates easier.
  • Do not modify the scripts located in the “ABCinvoice (private)” folder.
  • The Add-on comes with a set of value lists to assist you. All these lists are prefixed with ABCinvoice.

Part 3 – Receiving invoices

If you already have an incoming invoices table:

  • Duplicate and adapt the following scripts:
    • ABCinvoice_GetReceivedInvoices – Scheduled script
    • ABCinvoice_GetReceivedInvoicesDetails
    • ABCinvoice_Create_RINL (invoice)
    • ABCinvoice_Create_RDUEDATES (invoice)
    • ABCinvoice_Create_RTAX (invoice)
    • ABCinvoice_Create_RECEIVED_ATTACHMENTS (invoice)
  • The layouts for the list of incoming invoices and their detail view are located in the ReceivedInvoicesLayouts folder of the Add-on.
  • The scripts used to retrieve incoming invoices are also included and do not require any modification on your part if you don’t have an incoming invoices table. To receive supplier invoices regularly, refer to Part 4 – Server scripts.

Part 4 – Server scripts

If your FileMaker file is hosted on FileMaker Server or FileMaker Cloud, open your server’s Admin Console and configure a schedule to run the following scripts:

  • ABCinvoice_GetReceivedInvoices – Scheduled script used to regularly retrieve supplier invoices into your solution.
  • ABCinvoice_GetInvoicesState – Scheduled script that updates the status of invoices.

A daily frequency is recommended.

More information? Explore the links below:

Support portal
Forum
Notify me when the add-on is updated