Finance workflows often deal with companies’ VAT numbers, which are a common source of errors when entered incorrectly. To help prevent this the European Commission provides an online service for VAT number validation. This blog post shows you how to use this service for automatic VAT number validation using Signavio Workflow Accelerator.

VAT number validation sub-process action

When you implement an integration, make it a minimal standalone process that does just one thing, so you can re-use it from other processes via a sub-process task. For example, this is how you would configure a ‘Validate EU VAT number’ sub-process, given customer country code and VAT number fields:

VAT number validation inputs

The sub-process output would be a ‘VAT number valid?’ (Yes/No type) field that indicates whether the VAT number is valid:

VAT number validation - Sub-process action configuration - outputs

To build this, we need to create the ‘Validate EU VAT number’ process that will perform the VAT number validation.

Validation sub-process configuration

The ‘Validate EU VAT number’ process’ goal is to indicate that a European VAT number is valid. To do this, add a single JavaScript action to call the online validation service.

Add a trigger form with two fields:

  1. ‘Country code’ (Text) – a two-letter ISO 3166-1 alpha-2 country code
  2. ‘VAT number’ (Text) – the portion of the VAT identification number after the country code: 8-10 digits for most EU countries’ VAT numbers

The JavaScript action will then use these two fields as input data to query the validation service.

Validation web service

The European Commission’s VAT number validation service is a SOAP-based web service. Its service-oriented API uses XML messages, sent over HTTP.

To call a SOAP service, you send an XML request to the service ‘endpoint’ URL in an HTTP POST request. The XML request will contain the country code and VAT number parameters. The HTTP response is an XML message that will include ‘true’ or ‘false’ to indicate whether the number is ‘valid’.

Calling the SOAP web service from a JavaScript action

The ‘Validate VAT number’ JavaScript action will perform several steps.

  1. Validate the country code
  2. Construct the SOAP request XML message, using the input variables
  3. Send the request
  4. Parse the received response XML
  5. Update the output variable according to the result in the XML

Configure the JavaScript action to have access to both trigger form fields (above), and one new field for the result:

  • ‘Valid?’ (Yes/No) – the VAT number validation result

Now add the following JavaScript code, which is based on the validate-vat library (https://github.com/viruschidai/validate-vat/).

const convert = require('xml-js')

if (!(countryCode && vATNumber)) {
    console.log('Error: country code or VAT number not specified')
    return
}

const countries = ['AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'EL', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'GB']

if (!_.includes(countries, countryCode.toUpperCase())) {
    console.log('Error: invalid country code')
    return
}

const soapRequest = `<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:tns1="urn:ec.europa.eu:taxud:vies:services:checkVat:types"
  xmlns:impl="urn:ec.europa.eu:taxud:vies:services:checkVat">
  <soap:Header>
  </soap:Header>
  <soap:Body>
    <tns1:checkVat xmlns:tns1="urn:ec.europa.eu:taxud:vies:services:checkVat:types"
     xmlns="urn:ec.europa.eu:taxud:vies:services:checkVat:types">
     <tns1:countryCode>${countryCode}</tns1:countryCode>
     <tns1:vatNumber>${vATNumber}</tns1:vatNumber>
    </tns1:checkVat>
  </soap:Body>
</soap:Envelope>`

const url = 'http://ec.europa.eu/taxation_customs/vies/services/checkVatService'
const options = { url:url, body:soapRequest }
request.post(options, function(error, response, body) {
    if (response.statusCode != 200) {
        console.log(body)
        return
    }
    const fault = result['soap:Envelope']['soap:Body']['soap:Fault']
    if (fault) {
        console.log(fault.faultstring._text)
        return
    }
    const result = convert.xml2js(body, {compact: true})
    const checkVatResponse = result['soap:Envelope']['soap:Body'].checkVatResponse
    valid = (checkVatResponse.valid._text == 'true')

})

Use the test runner to test the script, using a valid VAT number, such as DE 265675123. The test runner’s variable updates table should show that the update value of the ‘valid’ variable is ‘true’.

You can now use a sub-process action in another process to perform VAT number validation, as shown above.

Reduced-cost agile application integration

Open standards, public web services, and JavaScript-based integration all reduce the cost of integrating your workflows with external systems, compared to traditional enterprise application integration. As well as using public web services, you can develop your own, so you can integrate your workflows with your organisation’s own systems.

You can get started with Signavio Workflow Accelerator without this kind of integration, focusing on coordinating human tasks. However, once you have a streamlined but manual process, you can then use the built-in JavaScript integration to incrementally automate parts of the workflow and integrate its data with external systems. This is how modern agile application integration works.

To use Signavio Workflow Accelerator to automate your workflows, validate your VAT numbers and integrate with everything else, register for a free 30-day trial today.

Published on: April 19th 2018 - Last modified: April 19th, 2018