Integration to Visma Severa
Visma Severa API usage
Problems in integration

Integration to Visma Severa

When starting to create an integration to Visma Severa, it is not only important to consider the functionality of the integration, but also to consider the technical side: where will the integration be running and how, how it can be tested and how to get knowledge on what happens when the integration is running.

Integration can be built with chosen technology, and Visma Severa will not give support regarding the selected technology.

Integration run schedule

Integration to Visma Severa must be built so that the integration doesn't constantly poll Visma Severa's API to find out if there is new data. Integration should be run on a schedule, which should be defined by thinking about the following:

What data the integration is transferring?
Is it needed that each data type is transferred on the same schedule, or can some be transferred more often than others?
Are there dependencies on the data, which affect on what should be transferred?
What is the business need of the integration, what kind of business requirements are there for the transfer? It is important that the integration serves it's purpose on the schedule the company needs the information.
As an example: Transferring out of office activities to salary system can be done once a week, but invoices to be sent should be transferred once a day. When transferring invoices it is needed to transfer accounts and cases before invoice transfer.

If the integration is such that transfers need to be done many times a day, integration should not be running more than once in an hour.

Do not make an integration where the main integration logic is a loop which is repeated immediately after it has ended, without any schedule.

Testing integration

When integration is developed, it must be tested against a Visma Severa secure-test environment. When the integration has been proved to work without issues, it can be changed to run against production. See details of environments from Getting started with Severa API integration article.

When changes are done to an existing integration, those must be tested against a secure-test environment. Integration shall never be released to run directly against production. This is to ensure that customer's data doesn't get corrupted if there is some problem with the integration.

Testing of an integration shall include:

Running the integration with test data against secure-test environment.
Making changes manually to data both in Visma Severa and in other integrated software, and seeing that the transfer is correct.
Enough test cases to cover the whole integration functionality. In addition, there should be differences in the test data so that the scenarios are covered in many ways.
Regression testing of the whole integration functionality always when changes are big enough to require full regression.
Consider also adding previous issues to the test plan, so that those would not occur again.

Configuring integration

Usually integrations need different kinds of parameters, so that they are able to run without problems. Common parameters are for example:

Severa API URI: tells where the API is located. Integration might need to run against secure-test.severa.com or secure.severa.com Visma Severa environment.
API key(s): Which API key is used in the integration.
Different kinds of parameters that are needed to get correct data from API. For example "use this invoice status name to get invoices from Visma Severa".
Different kinds of default values that are needed for the integration to work in all scenarios. For example "use this product code when product code is not available", or "use this person as default supervisor, if no other user is available".
Timestamps of last fetch of data, which are used when integration is run the next time. For example when using "GetCasesChangedSince" method, last run time needs to be saved somewhere, and configuration should be possible to change automatically by the integration and manually by the user.
Dates of API version and entity schema version, so that on each run the integration can compare stored versions and versions from API, and see if there are changes.
Configurations needed for logging, such as locations of logs, email addresses where messages are sent to and so on.

When integration handles data of many customers, each customer should have separate configurations, so that it is not possible to read the wrong configuration and get problems in the integration.

Integration configurations should be such that they can be changed manually, because sometimes in error situation stored timestamps need to be changed to the past.

Error handling

Integration error handling is crucial, because integrations are touching customer's data, and that data can't be restored easily if it has been broken by an integration. When doing error handling it is required to think and solve the following high level questions:

What kind of errors in the integration should stop the integration from running?
What kind of errors can happen so that the integration continues to work normally?
Where are the errors logged?
Who is responsible in monitoring the error logs?
What is done when error occurs in the integration and by whom?

The integration software itself has to be able to handle different kinds of errors, that can occur in the software. All errors should be caught, there should not be room for unhandled exceptions. This means that in addition to regular error handling, the software needs to be able to handle also all different kinds of errors than can come from Visma Severa's API.

Logging

Logging is one of the most important things in an integration, because in a situation when there are errors, it has to be possible to read from the logs what the integration has been doing in the time of the error.

Logging can be done for example:

To the Event log of the server where integration is running.
To database of the application.
To email. Notice that if email logging is done, the information which is sent is not secure, since email is like a postcard, when it is traveling in the internet. Integration can also generate a lot of log data, in which case email could become unusable.

Logging should be done at least on these levels:

Progress of the integration needs to be logged.
Errors need to be logged.

Logging must have timestamps of all the important actions. It is best if the timestamp has precision of one second, because precision of a minute is often too big, since transfers happen fast.

Progress of the integration

When logging progress of the integration, it is important to log every important action of the integration. Below is an example of an integration, and the things that would come out in log. Log shall be in a format which is readable, and can be sorted so that exact progress of the integration can be followed.

Case: Integration to get invoices from Visma Severa to another system. Status of the invoices should be "Ready for transfer" when gotten. After transfer, the invoices should be set to "Transferred" status.

Integration log for one transfer:

Invoice transfer started 15.10.2014 14:53:04.
Getting "Ready for transfer" invoices.
3 invoices found, starting to process invoices.
Invoice number 10501 was processed correctly.
Status of invoice number 10501 was updated to "Transferred" status.
Invoice number 10502 was processed correctly.
Status of invoice number 10502 was updated to "Transferred" status.
Invoice number 10503 was processed correctly.
Status of invoice number 10503 was updated to "Transferred" status.
Invoice transfer ended 15.10.2014 14:53:33.

Integration log, when no invoices are found:

Invoice transfer started 15.10.2014 14:53:04.
Getting "Ready for transfer" invoices.
No invoices found.
Invoice transfer ended 15.10.2014 14:53:06.

Integration log, when there was error:

Invoice transfer started 15.10.2014 14:53:04.
Getting "Ready for transfer" invoices.
3 invoices found, starting to process invoices.
Invoice number 10501 was processed correctly.
Status of invoice number 10501 was updated to "Transferred" status.
Invoice number 10502 ERROR 14:53:25 Unable to process invoice. Error message: [error information, which is also written to error log].
Invoice number 10503 was processed correctly.
Status of invoice number 10503 was updated to "Transferred" status.
Invoice transfer ended 15.10.2014 14:53:33.

It is important to do logging so that different scenarios are logged and can be followed, and that logging is easy to read. In the example case it is ok that sometimes no invoices are found, but if it happens for one week, people monitoring the integration should start suspecting that something is wrong.

Errors

When logging errors of the integration, it is important to log as much data as possible. Without detailed logging of errors it is very difficult to find out why integration is not working.

The following things should be logged, when there is an error:

Date an time of the error. Best is to log in UTC and in your time zone, this way conversion to other time zones is easier.
Type of the error.
Exact location of the error in your own code, in the most detailed level you can get (class, method, code line).
Previous call to Visma Severa API, containing parameters of the call. If the error came from API call, this tells what call it was.
Other similar "previous actions", which can help in solving issues.
Details of the API user: organization name, user's name, user's email address.
Error message, including all details that is possible to extract from the exception.

Always, when an error happens in the integration, there should be someone who reacts to it and starts to investigate what the error was and why it happened.

First run of integration

Sometimes the first runtime of an integration against customer's production environment can cause issues, because the amount of data in the environment is much bigger than in secure-test environment, and it wasn't considered when integration was built. This needs to be solved by the integration developers, for example so that the first run of integration is done differently than others, or data is exported from Severa as CSV and inserted to the other system with a script, so that amount of data transferred from API remains small enough.

Mass updates in Visma Severa

Customers are able to do mass updates in Visma Severa. They can for example change invoice statuses as a mass, or update account data as a mass. When this is done, a lot of data can have the same update timestamp. When integration starts to run, and data is gotten with "GetChangedSince" method, after a mass update the data coming from Visma Severa can be huge. Test this when building the integration, and make sure that the integration can handle this.

Visma Severa API usage

Follow Visma Severa API release notes to see upcoming changes in API. This way it will be possible to update the integration beforehand, test it in secure-test without hurry, and release changes for customers to production use when new version of Visma Severa API is released.

GetVersion and GetEntitySchemaVersion

Visma Severa's API has two important information available: API version and Entity schema version. These should be followed in the integration so that the integration stores the current versions, and checks on next run time, are they the same with information coming from Visma Severa's API or not. Information about changes are in API release notes.

GetVersion

Visma Severa's API version changes when API has any change. This means for example a new interface, method to an interface, optional parameters to a method and so on. When API changes, it is good to check out what the changes were, because there can be something that can be used to improve the integration. If the software has API service reference, it can be updated.

GetEntitySchemaVersion

Visma Severa's entity schema version changes when API has any change in entities. These changes can break the integration and customer's data, because data is modeled to entities and entities need to be all the time up to date so that data stays correct in inserts, updates and when getting data.

When entity schema version has changed, the integration should stop running, and at minimum the API changes should be looked at and service reference should be updated.

API calls

When making API calls to Visma Severa's API, the following needs to be considered:

Visma Severa might start to limit the amount of API calls that can be done in certain amount of time. Consider this while building the integration, so that you are prepared for it as well as possible.
Visma Severa's API has "GetChangedSince" methods, and they should be used in integrations which are running on a schedule.
- Methods give out data which has been changed after certain timestamp, which means that the data that comes from the API is relevant to the integration.
- Methods have "options", which should be used to limit the data even more: get only the things that are really needed for the integration.
- Using "GetChangedSince" methods correctly will increase the performance of the integration.
- If the methods are not used, the amount of data which comes out will grow during time, and at some point either the integration or Visma Severa's API will be unable to provide requested data anymore.
- If "GetChangedSince" methods are used, but still the data, which is coming, is too big, the integration needs to be able to adjust the time frame given to the method as parameter so that the data comes out. For example if at first the integration tries to get data from full week, and it isn't successful, the integration should start getting data for each day separately, and if that is not possible, for each hour and minute. This way the integration most likely is able to transfer all the needed data without problems.
- When "GetChangedSince" methods are used, the last call time needs to be saved, so that the next time it is possible to search for changed data starting from the end of previous runtime.
Do not use methods or data members which have been marked obsolete in API documentation. If those are used in your integration, change the implmentation to use methods which aren't obsolete.
Go through Code related issues with API article, and see that those issues won't occur in the integration.

Visma Severa API maintenance breaks

Our Hotfix and release process is described in this article. In addition, server maintenance is done frequently. During these times the application is not responding, when integration tries to call it through API. To check out when maintenance is done, follow these areas in Visma Severa's support:

In the case of maintenance break, the following error will occur, when API is called:

ERROR EXAMPLE NEEDED

Integration should be built so that it can continue working after a maintenance break in Visma Severa's API. This can be done for example so that:

Application catches error from Visma Severa's API.
Error is identified to be caused by API downtime.
Application writes the error to log.
Application waits 10 minutes and tries to do the call again.
- If call has failed 15 times, notification of problems is raised (for example email to person responsible of integrations) and running the application will stop.
- If API call goes through, application continues to work normally.

Notice that if the integration is simple and based on a schedule, or is not critical to business, if API call doesn't go through one time, it might be okay to write the issue to a log, continue the integration and try again in the next time.

Notice that if the application is very complex, there might be a need to start the application so that it doesn't start from the first step, but starts from where it stopped the last time. Consider this when doing the implementation. Usually integrations are based on "GetChangedSince" methods, in which case they can be run from the start to end without having problems, because only changed data is transferred.

Problems in integration

If there is a situation that for some reason the integration to Visma Severa doesn't work in some way, and it hasn't been possible to identify the exact cause for the issue, read through Problems with integration article. Visma Severa has gathered there a list of things to check, in order to make the integration functional again.

Did you find it helpful? Yes No

General API policies

Table of contents