General REST API Practices

Integration to Severa

When you start creating an integration to Severa, it is important to consider not only the functionality of the integration but also the technical aspect: where and how the integration will be run, how it can be tested, and how to get information about what occurs when the integration is in progress. The integration can be built with the technology of your choice, and Severa does not provide support for the technology you choose.

Integration schedule

The integration to Severa must be built in such a way that it does not constantly query Severa's REST API to check if new information is available. The integration should be run on a scheduled basis, and when defining the schedule, the following points should be considered:

1. What information does the integration transfer?
2. Does each type of information need to be transferred on the same schedule, or can some be transferred more frequently than others?
3. Are there dependencies in the data that affect the information being transferred?
4. What is the business need for the integration, what business requirements are there for the transfer? It is important that the integration serves its purpose in the schedule required by the company. For example: Absence transfers to the payroll system can be done once a week, but invoices to be sent should be transferred once a day.
5. If the integration transfers need to be done multiple times a day, the integration should not be in progress more than once an hour.
6. Do not build an integration whose main logic is a loop that repeats immediately after completion without any scheduling.

Integration testing

When developing the integration, it must be tested against Severa's secure-test environment. Once the integration has been proven to work without issues, it can be switched to operate against production. More information: How to get started with REST API?

When changes are made to an existing integration, they must be tested against the secure-test environment. The integration should never be published directly to production. This ensures that the customer's data is not damaged if there are issues with the integration. Include the following in the integration testing:

1. Running the integration with test data against the secure-test environment.
2. Making manual changes to the data both in Severa and other integrated software and ensuring that the transfer is correct.
3. A sufficient number of test cases to cover the entire functionality of the integration. Additionally, there should be differences in the test data to cover scenarios comprehensively.
4. Regression testing of the entire functionality of the integration whenever changes are significant enough to require a complete regression.
5. Consider also adding previous issues to the test plan to ensure they do not recur.

Integration configuration

Generally, integrations require various parameters to function without issues. Common parameters include:

• Severa API URL: Indicates where the API is located. The integration may need to run against secure-test.severa.com or secure.severa.com Severa environment.
• Client credentials: What client credentials and passwords are used in the integration.
• Various parameters needed to obtain the correct information from the API. For example, "use this invoice status name to get invoices from Severa".
• Various default values needed for the integration to work in all scenarios. For example, "use this product code when the product code is not available", or "use this person as the default supervisor if no other user is available".
• Timestamps for the latest data retrieval used for the next run of the integration. For example, when using the "GetCasesChangedSince" method, the time of the previous run must be stored somewhere, and the configuration should be modifiable automatically by the integration and manually by the user.
• API version and entity schema version dates so that the integration can compare stored versions and API versions on each run and see if there are changes.
• Configurations needed for logging, such as log locations, email addresses to which messages are sent, and so on.

When the integration handles data from multiple clients, each client should have separate configurations to prevent reading the wrong configuration and causing issues in the integration.

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

Error handling

Error handling in the integration is crucial because integrations touch the client's data, and that data cannot be easily restored if the integration has corrupted it. When doing error handling, the following high-level questions should be considered and resolved:

1. What kind of errors in the integration should stop the integration run?
2. What kind of errors can occur so that the integration continues normal operation?
3. Where are errors logged?
4. Who is responsible for monitoring error logs?
5. What is done when an error occurs in the integration and who does it?

The integration software itself must be able to handle various errors that occur in the software. All errors should be caught, and there should be no room for unhandled exceptions. This means that in addition to regular error handling, the software must also be able to handle all kinds of errors that may come from Severa's REST API.

Logging

Logging is one of the most important aspects of the integration because in error situations, the log must be able to show what the integration was doing at the time of the error. Logging can be done, for example:

• To the event log of the server running the integration
• To the application's database
• Logging to email. Note that if logging is done to email, the sent information is not secure, as email is like a postcard traveling on the internet. The integration can also produce a lot of log data, making email unusable.

Logging should be done at least at these levels:

• The progress of the integration must be logged
• Errors must be logged

Logging must have timestamps for all important actions. It is best if the timestamp has second-level accuracy, as minute-level accuracy is often too large, as transfers occur quickly.

Did you find it helpful? Yes No