X
PUBLIC
MEMORANDUM /
Error Handling in COSMIC Services
FROM / Nicolai Buch-Andersen
1. Introduction
There are six different web services for PAS: ReferralService, BookingService, ContactService,
JournalNoteService, CodesService and BirthService.
This document describes a common error handling strategy for all of these services.
References
Integrationsspecifikation (in Danish): A410.59
Løsningsbeskrivelse (in Danish): S111.2191
Web service documentation: A410.242
2. Error handling mechanism
The basic error handling mechanism in the PAS web services are exceptions.
When a web service encounters an error, it raises an exception, which is then translated into a
web service Fault element and returned as XML to the web service client.
All the web services specify two different exception types:
-
ServiceUnavailableException
XXXServiceErrorException
The first type of exception is a generalised exception type used to signal a problem with the execution environment, for example a missing database connection. The second exception type indicates one of two error conditions: Either there was a problem with the request parameters, or an
internal error occurred while processing the request. The later type is specific to the different
web services provided by PAS. That is, the ContactService will throw ContactServiceErrorExceptions, while the CodesService will throw CodesServiceErrorExceptions and so on.
In addition to the above, a client may receive authentication errors if it cannot supply a proper
user name and password for the service.
The next sections contain further details on these error types and their causes.
3. Authentication errors
A client must authenticate itself using a valid COSMIC user name and password. If it fails to do
so, it will not be serviced. Instead, it will receive and authentication error in the form of a HTTP
401 response, or “Authentication failed.”
4. Service unavailable errors
When a client receives this type of exception, it means that the web service is temporarily unable
to service the request. This may, for example, be due to a network problem. The client may have
better luck at a later time. A standard message will be returned to the client. The content of the
message will be along the following lines:
“Servicen fejlede på grund af problemer med at kontakte COSMIC.
Se serverloggen for yderligere detaljer.”
22.12.2010 A410.275.1
Page 1 of 2
MEMORANDUM / Error Handling in COSMIC Services
5. Internal Errors
When a client receives a XXXServiceErrorException it means that there is an error in either the
request parameters, in the calling system or in COSMIC itself.
A problem with the request parameters is discovered during input validation, which is typically
the very first thing done in any web service. When such an error is discovered, no further processing is done and an error message is immediately returned to the client. The message will be
highly specific to the particular service and to the parameter being validated. An example might
be:
“Kunne ikke oprette epikrisenotat. Ugyldig kontakt id: 12345”
Most of the time, a validation error can be corrected simply by modifying the data in the calling
system and then re-sending the request. If the error is recurring often, however, it can be a sign
of a more serious problem in either the calling system or COSMIC.
If the input parameters are all validated without errors then the web service can execute the
request. At this point, only an internal COSMIC error may halt the process. Such an error may be
caused by data inconsistencies in the COSMIC database, or by errors in the code. The error will
result in a standard message, worded something like the example below:
“Servicen fejlede på grund af en intern COSMIC fejl.
Se serverloggen for yderligere detaljer.”
22.12.2010 A410.275.1
Page 2 of 2