HansaWorld REST API import

Things you should know about REST API data upload :

REST API is only available to users who:

Have HansaWorld version STDERP_8.4 - 2017-11-22 or above

During the setup you will need to:

Get a working URL to Standard ERP over HTTPS
Enable REST API with correct access rights in HansaWorld

Setup HansaWorld for Rest API

You need to know the HTTPS port of your HansaWorld server (Note: It is not the same as you normal port used for HansaWorld client!). SSL can be issued by Certification authorities and it can also be a self-signed certificate if the level of security is acceptable by customer. To set up self-signed certificate you can follow the documentation page on How to set up Standard ERP HTTPS with self-signed certificate for HansaWorld imports.
You need to know the URL or IP address of your HansaWorld server that can be used for web requests from the Internet.
Go to System >> Settings >> Optional Features and check the Allow Basic HTTP Authentication checkbox.

For security reasons we advise to remove this checkbox when the Rest API configuration is done.
In the same screen ("System >> Settings >> Optional Features") check the "Web Rest API" checkbox.
If you are using Standard ERP 8.5 2020-08-13 or newer version, go to Webshop >> Settings >> Access to functions from Web and do the following configurations:

If you are using Standard ERP 8.5 2021-07-30 or newer version the setting is also available in Technics >> Settings >> Access to functions from Web
To verify if you are using the correct REST API address and if the SSL certificate has been set up correctly please try to receive data manually. To do it, open web browser, enter URL https://example.com:port/api/1/OTVc, where "example.com" is your URL or IP address, "port" is your port, "1" is your company number and "OTVc" is a register that you can access in HansaWorld, and log in with your standard ID. If you can receive data successfully then you can proceed.
Go to https://mystandard.hansaworld.com page and choose More >> Developer Credentials. If you do not have access to this section, please contact you system administrator or flex.bi support.

To find out more about the OAuth authenticate mechanism please read How does HansaWorld OAuth authentication work?
Press "Add New" button.
Enter a name of your choice in the "Application Name" box and redirect URL in the "Allowed Redirects" box and click on "Submit".

If you are a flex.bi Cloud user, enter the following value in the "Allowed Redirects" box:
CODE
```
https://flex.bi/bi/source_applications/auth/rest_api/callback
```
If you are a flex.bi Enterprise user, you need to replace https://flex.bi/bi with your server's URL. Or you can use the "Redirect URL" shown on the flex.bi import configuration page (see step 13 below).

This URL has to be reachable from the internet, so make sure that it contians an external IP address or host name and that your firewall settings allow this URL to be opened outside of your local network.
Find the newly created "Application Name" in the list and copy the corresponding "Client ID/Client Secret" values. You will need those later in the step 13 of this setup.
Go to your flex.bi account.
Setup HansaWorld source application, by going to the "Source Data > Source Applications" section and selecting "Add new source application" button.
Select "HansaWorld".
Select the "Rest API and Source Files" radio button and enter your HansaWorld's URL followed by the port number and /api. For example: https://sample.url.com:1234/api/
Enter the Client ID and Client Secret that you got in step 8 above. Here you can also find the correct "Redirect URL" that can be used in step 8 above.
Agree to Terms and Conditions, by marking the appropriate check-box, and then press "Continue".
Log in with a Standard ID that has full access rights to the "Rest API" action and the necessary modules and registers on your HansaWorld server.
To check if you have the necessary access rights:
1. In your HansaWorld application, go to "System >> Settings >> Access Group".
2. Double-click on the code for the access group of the HansaWorld user that you will use for Rest API import.
3. In the list of permissions, make sure that you have "Full" level access to "Rest API" action.
4. Also make sure that you have at least "Read" level access to all of the registers that you want to import.
  (In the following example "Read" level access for "Purchase Orders" register is granted.)
  
  The HansaWorld server has denied access to the register for your user
  
  In case you are getting the "The HansaWorld server has denied access to the register for your user." error message:
  - make sure that your MyStandard user is authorized to get the particular register's data from your HansaWorld server
  - or disable this register in your HansaWorld source application import setup page.
Select your data
In the "Company" drop-down menu you can select which company data you wish to import. If you are using flex.bi BUSINESS plan, you can enable Finance Consolidation to import finance data for several companies.
In the "Start import from" you have to enter the date in the following format (yyyy-mm-dd). The date describes the point in time from which the data will be imported, that is to say if you enter 2016-01-01 then all data that has been created from January 1, 2016 and up to today will be imported, data created before January 1, 2016 will not be imported. If you do not enter a date, data from 365 days ago will be imported by default.
The "Future days" field allows you to specify how many days into the future you want REST API to take data from.
The "Refresh period" field allows you to specify from how many days into the past you want your already imported data to be refreshed (required when an old data entry has changed).
The "Regular import frequency" allows you to specify how often you want your data to be refreshed.

Once you are done with selecting everything you wish to import press the "Import" button and the import will begin. Importing with REST API does not upload any source files into the "Source files" section of flex.bi.
If you want to also analyse your data by Objects or classification follow the steps in this documentation page about Extra dimensions.
If you want to import Extra dimensions (Object types, Customer classes, Item classes, Location classes, Item Varieties), click on section Extra Dimensions and select, which Extra Dimensions you need.
If your file is not recognized as a HansaWorld file then:
- make sure the file contains any data at all,
- try to re-export the data from HansaWorld again and allow some time for the new file to be populated with data, because exporting big files (several megabytes) can cause the files to appear as empty while they are being populated with data.
Go back to Source Application tab and press Import.

Application Errors - Rest api 2

If you receive application errors after Standard ID Entry you first should check steps above again - if you haven't forgotten to to install some certificate or give correct rights to user. Some application Errors are provided by flex.bi, but some by you Hansaworld server.

Common Error Messages

Error Message	Meaning	Possible Reasons
"Source application did not authorize your request"	There is no validation for your request	Wrong Developer Credentials - They must be unique for each customer. Make sure you have entered them correctly. Wrong Standard ID login or Password - Please check if you have entered correct user and Password. The Standard ID login does not have access to the first company on the server list. Use parameter to change default company.
"Source application did not authorise your request" invalid_request: {"error":"invalid_request"}	The REST API request is incorrect.	Trailing space in the Client ID or Client Secret field. Please check the values. Wrong or missing host and/or protocol settings under [default_url_options] in the eazybi.toml file. Please make sure that the settings correspond to your flex.bi instance URL.
Access type must be 'offline' and response type must be 'code'	Cannot login to mystandard.hansaworld.com when redirected from flex.bi	Incorrect username or password when logging in with standardID.
the resource is not allowed	The user's access group is not allowed to use the Rest API	The user's access group doesn't have full access for Type:Action Item:Rest API in your HansaWorld server.
Received HTTP 405 error when requesting https://.../BaseCurBlock	The user's access group is not allowed to use the Rest API	The user's access group doesn't have full access for Type:Action Item:Rest API in your HansaWorld server.
initialize: name or service not known	Wrong Source Data URL	Check the URL, by copying it into tour browsers search bar.
connection reset by peer	"http" instead of "https" in Source Data URL	Check if the URL starts with "https".
flex.bi: File not found Standard ERP (hansa.log): path not allowed: api/1/IVVc	Can't access the register on the Standard ERP server	Configure Access to functions from Web setting according to the step 5 above.
Received HTTP 404 error when requesting ...	During consolidated data import, the next request after token refresh can result in 401 “Unauthorized“ or 404 “File not found“ error.	Use token_refresh_sleep_secs account parameter to set a sleep time after receiving refresh token

HansaWorld versions with know REST API import issues

This version issue list is incomplete and is based on flex.bi users feedback. We do not have information on when exactly the issues have started and when or if they were fixed.

HanaWorld version	Issue type	Issue	Comment
8.5 2022-04-16	Minor	REST API format has changed	HansaWorld application has an automatic fix for this but this might cause issues when importing HansaWorld data with other data sources
8.5 2022-08-01 build 339	Minor	During consolidated data import, the next request after token refresh can result in 401 “Unauthorized“ or 404 “File not found“ error.	To fix this parameter token_refresh_sleep_secs can be used to set a sleep timer after receiving the refresh token.
8.5.42.xx	Major	Incremental import is not working	There is a fix for HansaWorld application where for these versions incremental import is automatically disabled and Refresh period is used instead
???	Critical	Authorisation is working only for first company on a HansaWorld server	If the company is not the first one on a HansaWorld server then REST API import will not be possible as flex.bi will not be able to authorise. If the company for the import is the first one then import will work as usual.
8.5 2022-05-24 - 2022-08-01	Critical	REST API import it getting stuck and not working	Format for REST API request result has changed. From <data><IVVc></IVVc></data> to <data><IVVc><IVVc></IVVc></IVVc>.
8.5 2022-06-16 - 2022-08-01	Critical	REST API import is getting stuck and HansaWorld import options page is not loading.	Format for REST API request result that returns an empty page has changed.