Embeddable User Interface

By using EUI you have the possibility to skip part(s) of the API integration towards us and still provide your customers everything directly from your product. Your end customers can also get a possibility to have a quick access to our new features and services without them having to wait for developement and changes on the ERP side thus reducing the time to market of our new cool features. Embedding the EUI to be part of your product is really easy and does not require lot of time or development resources.

Even though almost everything can be done via the EUI there is still some functions that we highly recommend that the ERP does through the normal Maventa API integration:

• Providing a easy on-boarding of customers - register to Maventa “by touch of a button”
• Sending and receiving invoices (and other documents)
• Different invoice handling workflows like approving invoices
• Adding new users to Maventa company account

Basically all the rest can be done via the EUI:

• Listing of invoices and documents and viewing their details
• Resending and rerouting invoices
• Toggle Maventa settings
• Register to receive through different networks
• Search for receiver’s e-invoice addresses
• Listing of consumer agreements (Norway)
• Enable (and use) functionalities like: Consumer invoicing handling (currently only for Norway), Receivables Management Service for Finnish companies, Detect, Visma Scanner

How does the EUI look

How to take the EUI into use

Decide what to show to your customers and how

First you should think a bit what do you want your end customers to see. What parts of the EUI they need? And then decide how to show those views. Should you add one button to open up the whole EUI and let customers navigate themselves to the page they need or should you show different views in different parts of the ERP depending on the context (Settings view embedded into the part which shows ERP’s settings, and invoices lists where there are invoices listed on the ERP)?

Read more about the customisation of the EUI. Our team is happy to assist you in deciding what would be the best fit for your ERP. If you want help in deciding or if you have made some decisions youself contact Maventa support and ask for an EUI ERP profile. We will then set up you profile based on your preferences.

Decide how to embed

It is really easy to embed. We offer two different solutions for embedders, one where you can include a script tag on your HTML page within your product, and another one where you can use an iframe (or similar solution) to embed the EUI. First one we recommend to those products that are running in the user’s browser because with the iframe solutions there might (and most likely will) be problems loading cross-domain content. Both of these embedding methods, script embedding and Iframe embedding, explained in details.

What is common in both ways to embed are the domains listed below and that you will need to get an access token for the company.

We currently host the EUI under 3 different domains:

Production environment:

• autointerface-embeddable.maventa.com
• autointerface-embeddable.autoinvoice.visma.com
• autointerface-embeddable.visma.net (Visma internal use)

Testing environment:

• autointerface-embeddable-stage.maventa.com
• autointerface-embeddable-stage.autoinvoice.visma.com
• autointerface-embeddable-stage.visma.net (Visma internal use)

Fetch an access token for the company

Authentication and access to the EUI is done using token based login (based on company_uuid, user_api_key and vendor_api_key).

The token to open EUI is fetched using the AX Oauth2 endpoint using the following parameters

Endpoint for getting the token: Testing: https://ax-stage.maventa.com/oauth2/token Production: https://ax.maventa.com/oauth2/token

curl -X POST "https://ax-stage.maventa.com/oauth2/token" 
-H "accept: application/json" 
-H "Content-Type: multipart/form-data" 
-F "grant_type=client_credentials" 
-F "client_id=company_uuid" 
-F "client_secret=user_api_key" 
-F "scope=eui" 
-F "vendor_api_key=erp_vendor_api_key"

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudG......",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "eui"
}

When you have an access token you can then use it in the emdedding solution you have chosen, script embedding or Iframe embedding. Both are explained below:

Method 1 - Script embedding

Add script tag <script> in your browser page with the following content:

<body>
    <div style="height: 1024px" id="eui-container"></div>
    <script src="http://autointerface.visma.net/embed"
            data-token="eyJ0eXAiOiJKV1QiLCJraWQiOiJjODJhZTdiZTU...."
            data-container-id="eui-container"
            data-default-path="/invoices"
            data-profile="my_erp_profile_name"
            data-locale="en"
            data-setup-top_menu="false"
    ></script>
</body>

In the above example the EUI is opened directly to the invoices page, language is set to be english and the whole top menu is hidden.

With this embedding method there is no way to renew the token. This means if the user has the EUI open for over one hour the session will be unusable and needs to be restarted with a new authentication. So remember that the token will expire in one hour and user will be kicked out. When that happens customers should be able to refresh the page and gain access again.

Method 2 - Iframe embedding

The endpoints for the process are the following:

Start monitoring the token expire time for automatic session renewal

While the user’s EUI session is active you need to act when the token is about to expire. The expires_in attribute in the token response tells how long the access token is valid. To be sure deduct a few minutes from the time to not run into issues. It’s important to stop the renewal process if the user closes the EUI session or the user have logged out in some other way.

The provided token in the initial request will be valid for one hour and if the token is not renewed the users session will end when the token expires. This means if the user has the EUI open for over one hour the session will be unusable and needs to be restarted with a new authentication. To prevent this the token can be updated for the user in the background without the user noticing anything (Step 4). To be able to renew the token the first thing to do is to pass a unique ID as the session id for each authentication that is initiated, this to be able to associate to the session on renewal. The unique ID is given in the session_id parameter on the initial authentication request (see the step 3).

Open the EUI session in a browser component

When you have a token you are ready to open EUI in a browser window.

Depending on the browser component capabilities it varies a little how the EUI session can be initiated. The token can be put in either the POST body or in the Authorization header as a Bearer token.

curl -X POST "https://autointerface-embeddable-stage.maventa.com/authentication/token" 
-H "Content-Type: multipart/form-data" 
-F "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9......" 
-F "profile=my_erp_profile_name" 
-F "locale=no" 
-F "redirect_to=/invoices" 
-F "session_id=erp_users_session_id"

<!DOCTYPE html>
<html>
<head></head>
<body>
  <form action="https://autointerface-embeddable-stage.maventa.com/authentication/token" method="POST" target="_blank">
    <fieldset>
      <legend>Authentication using token</legend>
      <br/>
      <label>token:</label>
      <input type="text" name="token" size="100" />
      <br/>
      <label>session_id:</label>
      <input type="text" name="session_id" size="70" />
      <br/>
      <label>redirect_to:</label>
      <input type="text" name="redirect_to" size="70" />
      <br/>
      <label>profile:</label>
      <input type="text" name="profile" size="40" />
      <br/>
      <br/>
      <input type="submit" value="Log in"/>
    </fieldset>
  </form>
</body>

Renew the token for an existing session

When the token is about to expire a new token needs to be obtained exactly the same way as in (Step 1).

The token then needs to be passed to the renew endpoint in EUI, combined with the session_id generated in the initial request. If you are able to extract/use the session cookie from the browser component it’s possible to use that when renewing the token, then there is no need to pass and use the session_id.

curl -X POST "https://autointerface-embeddable-stage.maventa.com/authentication/renew" 
-H "Content-Type: multipart/form-data" 
-F "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6InVzZXIiLCJ1c......" 
-F "session_id=erp_users_session_id"

Customise your own view of the EUI

EUI is highly customisable and every ERP can create their own look and feel of it. You can decide what to show to your end customers through the EUI and what should be hidden from them. For example if there is no invoice receiving capabilities in the ERP, received invoices list can be hidden and as well all the invoice receiving related settings. Customised view will greatly improve the user experience by always provide only useful information to the end customers. Customisation of the EUI is a really cool feature.

Customisation can be done using the ERP profiles and optional setup parameters:

ERP Profiles

ERP profiles are the main way to customise the views and are created for each ERP using the EUI. Using profile in a call toward EUI will load the ERP specific view. ERP profiles are created and modified by Maventa team based on the ERP’s needs and requirements. So before you start to build the integration towards the EUI, please contact Maventa support and ask for an EUI profile. One ERP can have multiple profiles. For example one for each version of the system or if you have different customer groups and would like to show them different content based on what functionalities they have in use.

...&profile=name_of_the_profile

When we add something big to the EUI for example a new service or functionality we will always contact all the EUI ERPs if they wish to have that new service visible also to their customers. Using EUI comes really handy by reducing the time to market of new services. Of course it is good to keep in mind that some of the new services might also require some changes from the ERP side or to the API integration but some services work just fine only through the EUI.

Setup parameters

Profiles are great way of setting up the EUI look and feel, but if you want to have further control use the EUI setup parameters. EUI setup parameters have the same structure as the profiles and those can be used in combination with a profile. EUI setup params will override any setting from the profile so if you want to have a bit different views for one specific customer you can do it by using setup parameters. Empty values for any EUI setup parameter, equals false.

Let’s say that you have few customers that do not receive invoices through your ERP at all and you want to provide them a different view than for the rest of your customer by hiding all that is related to the invoices receiving:

• To hide received invoices list
• To hide settings for invoice receiving

EUI setup parameters will look like:

...&setup[sections][invoices][inbound]=false
&setup[sections][settings][invoice][receiving]=false

Direct URLs

With direct URLs customers can be redirected straight to the page you want. In the part of the ERP where invoices are handled could be a direct link to the invoices list of the EUI. And in the part where there are all the setting there could be a link to open up a settings page of the EUI. You can also have direct link for only showing details of an one invoice if you for example want to integrate the EUI invoice details as being part of the invoice details shown in the ERP.

Supported browsers and their versions

• Chrome
• Firefox
• Safari
• Edge