This article explains how you create and manage the connector enabling you to convert PDF invoices into UBL files, which are integrated in the Tradeshift platform.

Overview

A connector behaves like a predefined integration template, which you fill in with relevant information, to support your integration scenario. Consider it a simplified UI layer, over one or a series of channels.

The Generic PDF/Canonical to UBL connector is built on the same principle, in the sense that it is a predefined integration template, available for use when you want to integrate your invoices in the Tradeshift platform.

Note that the Babelway app reads and processes computer-generated PDF documents. Make sure that your PDF template is not printed, scanned, faxed or a photo of the document.

Invoice conversion steps 

The steps below describe the process to convert PDF invoices to UBL files, using the Generic PDF/Canonical to UBL connector.

1. Open the Babelway app and go to the Manage and build section. Details about the Babelway app and how to use it are available here.
2. Select the Connectors tab. When you select this tab for the first time, there is no activity displayed on the page. To find and set up the PDF-to-UBL connector, select the View catalogue button.
3. Use the predictive search field to find the connector template, and then select Generic PDF/Canonical to UBL. The connector setup page opens, displaying the following connector steps: General, Configure email, PDF configuration, and Tradeshift account credentials.
4. Go to the General step. Add the name and description of the connector, in the corresponding fields, and then select Save button at the bottom of the page. Note that, if you do not save your changes, before you proceed to the next step, your changes will be lost.
5. Select the Configure email step. Add the email address to which you want to send the invoices, and then select the Save button at the bottom of the page.
6. Go to the PDF Configuration step. To add a PDF invoice template to the platform, click Select in the Select file field. Browse for the invoice, add it, and then select the Save button at the bottom of the page. The invoice is imported, and the invoice template editor opens.
7. Edit the PDF fixed elements, as described here.
8. Edit the matching settings on your invoice, and then select Save template, at the bottom of the page. Details on how you map invoice fields are available here.
9. Select Exit template editor, and then go to the Tradeshift account credentials step, where you define the Tradeshift account where the invoices are uploaded and displayed. To fill in the fields at this step, use the API Access To Own Account app.
10. To finish the connector creation process, select the Save button at the button, and then use the Active/Inactive toggle at the top right, to activate it. The platform displays a confirmation message and your connector is activated.

Editing PDF fixed elements

1. To open the section, select the cogwheel at the top right of the template editor.
2. To select the fixed elements on the PDF template, hover the cursor over the invoice template, and then click the element.
3. Drop down the Text equals to menu to choose the option applicable to the element. Avoid the Text equals to option, and use any of the other options instead (Text contains, Text starts with or Text matches regex). The extraction of the line items information will trigger the creation of a table, for which you will need to define the start and end positions of the table. If the table will stretch over multiple pages, you will also need to define limits for the start of the table on the second page and for the end of the table on the first page.









4. To add another element, select the Add more button in the PDF Template Settings section.
5. To finish the process, select Save settings.

Mapping invoice fields

When you go to the PDF Configuration step and upload the PDF invoice, it is displayed in an invoice template editor, as follows:

• PDF invoice on the left;
• UBL fields on the right.

As you can see in the Extracted fields table, the app has extracted the invoice fields, which are now available for edit, as follows:

1. In the Extracted fields table, click the field name you want to edit, and then select the field on the PDF invoice.
2. Select one of the following two options, on the pop-up window displayed:

• Fixed – for a field value that always starts at the same position within the PDF template (exact same coordinates, each time). The Fixed option is very sensitive and implies that the object you select as the anchor will always be in the same position in all of the PDF documents.
• Relative to a label/image – The position of this value varies, but it is always close to a label (field name). A good example is the date value. The Relative to a Label/Image option is more reliable because it allows you to identify the data point in correlation to another label or field.

3. When you select one of the options above, the Extraction rules panel is displayed. Use it to set up the mapping rules for the edited field.
4. (optional) On the Extraction rules panel, you can also add functions to optimize the fields extracted from the invoice, by selecting the Add function button on this panel. Adding functions is a two-step process: choose the function you want to add, and then add the corresponding parameters. This gives you access to four data manipulation functions:

• replaceText
• replace Regex
• substring
• changeDateTimeFormat

5. Once you have finished editing a field, select Confirm at the bottom right of the Extraction rules panel.

Repeat steps 1-5 for all the fields that require mapping.

It is highly recommended to test the PDF template on multiple sample documents so that all the possible differences between invoicing scenarios are tested and accounted for. Additional PDF samples can be added from the Add Sample button at the top left of the PDF template editor.

Useful tips

• When you hover the cursor over a field name, a tooltip displays additional information about each field name and how to use it.
• If you are not satisfied with the edited field, select the edit icon next to it, to modify it, or the x icon, to delete the current setup.
• If a value is not displayed in the PDF file or if you want to hardcode a specific value in the template, click the Field value cell next to required field name, and then enter the data manually.
• Avoid using images or logos, since any changes to these will result in errors when applying the template to documents.