Esko Logo Back to Esko Support
Choose your language for a machine translation:
Skip to end of metadata
Go to start of metadata

 

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.

Retrieve your Access Token only once

Fortnox uses a modified version of OAuth2 for authentication to offer a secure way for you to interact. They use an Access Token that does not expire. It is only allowed to request this token once! If you request it a second time, your API key will be blocked. And you will not be able to continue the integration.

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

Response with empty values

Note how the XML contains empty nodes. In the example above, there is no second address line provided in Fortnox. Still, the XML contains the full node <Address2></Address2>. This is important, as XPath SmartNames looking for this field will return an empty value. Where as this node would be missing or short formatted as <Address2/>, the XPath SmartName would not resolve.

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. 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).
    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.

API keys are personal

For obvious reasons, the screenshots in this article contain dummy authorization codes, access tokens and client secrets.

Article information
Applies to

AE Connect

Esko Product

Automation Engine

3rd party software

Fortnox

UsecaseAPI integration
Created21-May-15
Last revised 
AuthorPEMY
Contents