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.
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
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:
In your HansaWorld application, go to "System >> Settings >> Access Group".
- Double-click on the code for the access group of the HansaWorld user that you will use for Rest API import.
- In the list of permissions, make sure that you have "Full" level access to "Rest API" action.
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.
|Error Message||Meaning||Possible Reasons|
|There is no validation for your request|
|The REST API request is incorrect.|
|Access type must be 'offline' and response type must be 'code'||Cannot login to mystandard.hansaworld.com when redirected from flex.bi|
|the resource is not allowed||The user's access group is not allowed to use the Rest API|
|Received HTTP 405 error when requesting||The user's access group is not allowed to use the Rest API|
initialize: name or service not known
Wrong Source Data URL
connection reset by peer
"http" instead of "https" in Source Data URL
|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|
|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.|
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 -
|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.|