“Button” plugin as a tool for downloading external data

10.04.2024

In the Dew-X system, integrations with other systems or data sources are possible through webhooks. Until recently, there was some difficulty in calling up and using external data before closing the form and submitting it further.

With the help of a new plugin called “Button,” the integration possibilities have been greatly expanded

The following rather uncomplicated example demonstrates the use of Button to call a function that, based on data from a form, queries an external database and, based on the results, completes another field of the same form.

Business-wise, the situation was as follows – the client has an invoice workflow where, at the registration step, using the GUS (Government database of business entities in Poland) plugin , it is very easy to obtain the buyer’s data based on the TAX ID. The integration with the accounting system at the last step of the process, where the contractor’s accounting number was required, proved problematic. The script used checks on the basis of the TAX ID whether such a contractor exists in the database of the accounting system and returns its number or a message about the need to establish such a supplier in the database.

In order to perform such an integration, it became necessary to place the Button on the form. This step is quite trivial and, as with other plugins, only requires adding it to the form and configuring it by providing some information.

The most important of these is the address where we put the script, where the logic of the operation is sewn in. In the example presented here it is the check_supplier script that we made using the Laravel framework. Of course, your script can be written in any language.

In order for your script to affect what you have on the form or in the process it must contain three basic properties:

Receive data from a request (it is sent via POST)
Perform the appropriate operation (e.g. fetch data from an external database or another process in Dew-X, perform more complex operations)
Perform data updates in the current instance from which the request was called.

Below is an image illustrating the configuration of the Button for integration.

View of the form (example)

Once the process is started, the Button is part of a larger whole – we see the GUS plugin, the description section, the Button itself and the field that the Button is supposed to complete. There can be any number of fields or tables that the Button completes (e.g. get order values after indicating the order number). In the example given, it is about completing one field.

First, the user fills in the TAX ID (NIP) field and clicks search in GUS. With this plugin, the contractor’s data is downloaded.

Then, the Button we created comes into action, under which a link to the script we wrote and published is hooked up. When it is pressed, a value from the client’s accounting system is downloaded to the ” Contractor Accounting No.” field. Before this happens, two actions take place, which are immanent features of the launch of each Button – saving the data before and refreshing the form after the script is executed.

Script view (example)

Of course, in order for our script to work and affect what is on the form, it is required that it is accessible on the open web, accepts a POST request, and inside there are references that allow you to retrieve and/or edit the instance data using CURL (Call to URL) functions. For the purposes of this exercise, our script was based on the Laravel framework – you can use any language or framework that meets the above criteria.

First, we embedded our script in the routing of the Laravel instance – we used the api.php file located in the routes directory for this purpose

The server and the client installation are locked into an internal network, so no additional authorization methods were necessary. However, if your server where you place your scripts is running on an open network, or you are using a free version of the Dew-X system you should secure routing by at least accepting requests only from our Dew-X server.

Once we had established routing and our script began to be reachable, we built checkSupplier functions within the controller.

The Button action sends two key pieces of information:

token – which allows you to perform API operations terminated with the system phrase (like downloading instance data, or updating data).
instance – telling what unique instance of the process the request comes from.

Note: if you want to use other API methods you need to use a specific user key (usually your own). You will generate it from the Dew-X interface.

In our function, in addition to retrieving data from the request, we have a reference to the private function getSupplierNumber, where we use both the token and the instance. We use them to first retrieve the data of the instance through the Dew-X system API, in which the Button script was called

Note: in most functions it is necessary to specify the organization id to know in which context we want to use the API.

After downloading, we decode the data by turning it into arrays, where we use the foreach function to find the instance data we need – in our case, it’s the TAX ID (NIP) of the indicated company from the “NIP” field of the GUS plugin, which we called “Company data” (“Dane firmy” in this example), and the id of the field with the key “no_account_contractor” (“nr_ksiegowy_kontrahenta” in in this example).

Note: we do not recommend searching by field id as these change with each process version update. It is much safer to search by the name of the field (label) and preferably, where possible, by the key.

Once we have the necessary data we ask the database of our accounting system for the contractor code. We will use it at the end of the process for integration, and now we need it to complete the field ” Contractor Accounting No.”