KB170049674: AE Connect - How to connect to Fortnox via webservices (API)

Description

Basic connection to the online MIS Fortnox. Authentication, GET information, POST information based on the XML API.

Using Automation Engine 12.1 and Fortnox API v3.

Introduction

Information on Fortnox and the API: http://developer.fortnox.se/.

Fortnox is an online MIS system. They provide API connections based on JSON and XML. This article does not cover best practices or how to implement an integration. It does explain the basics to establish communication between Fortnox and Automation Engine.

Configuration

Register as a developper

First, you must register as a developer to receive your API key. http://developer.fortnox.se/getting-started/.

Authorize your server as application

Configure Fortnox as External Web Service in Automation Engine. URL: https://api.fortnox.se/.

In Fortnox, you have to connect your integration to your Fortnox account. There is part of the Fortnox web interface. You can add Automation Engine as a "integration" via "manage users. More info on the Fortnox documentation.

Now, you need to retrieve your access token.

There is more info on the Fortnox documentation how to do this. But if you don't like scripting, you can also use the Automation Engine task, Interact with Web Service.

The result will be similar to this Access-Token.xml file. We will not use this XML file, you only need the value of the token oo00ps715-5ef7-412c-a635-shhhhhte2.

Communication from Fortnox to Esko Automation Engine

It is not possible for Fortnox to initiate communication. To receive information from Fortnox, a question needs to be asked first. This is done with the URL encoded REST command "GET". Use the Automation Engine task Interact with Web Service with these settings:

• Service: "Fortnox" (as you've configured it).
• Methode: GET
• Path: 3/your-question
• These headers (case sensitive): 
  
  • Access-Token | the value of the token as received after authorization.
  • Client-Secret | your client secret ID.
  • Content-Type | application/xml.
  • Accept | application/xml.

The path is depending on the question you ask. See the Fortnox documentation for a full list. In this example, we ask to list the customers using the path 3/customers.
 
The result is an XML file: Customers.xml

With the same settings, but using the path 3/customers/1 we ask more details about the customer with ID=1.
The result is again an XML file: Customers_1.xml

Practical implementation:

This screenshot is from an actual implementation:

This workflow is launched by a Folder Access Point. The workflow is selves will drop a file to trigger the hotfolder every 10 minutes.

• We GET a list of jobs using the path 3/orders. This single XML file is split in one file per order.
• For each relevant file, we check if a job with this order ID exists on Automation Engine already. If not, we proceed with the next step.
• For each new order (typically only one) we GET more details on this order using the path 3/orders/ordernumber. The output XML file is the input for Create Job task, using XPath SmartNames for Job name, Job description, customer ID and several categories. As reference, the XML used to create the job is moved into the job folder root. A template job is defined for creating a default subfolder structure. A Wait For Action task is launched to notify prepress operators about this new order. 
• The workflow created many temporary XML files, these are removed when all jobs are created.

Communication from Esko Automation Engine to Fortnox

To send information to Fortnox, we need to save it in a file first. This file is then uploaded with the URL encoded REST command POST. So, a single task is not enough, a small workflow is required:

1. 1. Create XML file with the information you want to upload to Fortnox. 
   2. Use interact with Web Service task to upload this file using POST.

1. The content of the XML file is depending on the information you want to upload. In this example we add a new customer:
   
   The XML file can be very small, with only a customer name. Or include more details. The customer ID is defined by auto numbering in Fortnox.
2. Use the Automation Engine task Interact with Web Service with these settings:
   1. Service: Fortnox (as you've configured it).
3. 1. Method: POST (not PUT, in contradiction with the Fortnox documentation).
   2. Path: 3/your-question (in this example: 3/customers).
   3. These headers (case sensitive): 
      
      1. Access-Token | the value of the token as received after authorization.
      2. Client-Secret | your client secret ID.
      3. Content-Type | application/xml.
      4. Accept | application/xml.
      5. SOAPAction | 1 (this is required for Automation Esko. This is not documented by Fortnox).
   4. In Options, activate Attach input files.