TRACES System-To-System Specifications - CIRCABC
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
The European Commission
Directorate General
SANCO
TRAde Control and Expert System
(TRACES)
TRACES System-To-System Specifications
Subject TRACES System-To-System Specifications
Version / Status 3.04
Release Date 18/03/2019
Filename TRACES-STS-001 System-To-System Specifications v3.04.doc
Document Reference TRACES-STS-001
Document Owner European Commission: DG SANCOTRACES TRACES REF: TRACES-STS-001
DOCUMENT HISTORY
Ver. Release Date Description Author (Function,
Party)
1.00 21/11/2003 Initial Draft B. Dupont
1.01 3/3/2004 Updated XML message schema. N. Carl
Added a chapter to describe client I. Hellemans
implementation details.
1.02 16/3/2004 Updated XML Schema, Means of Transport, N. Carl
Intratrade Corrective Action Identification
added, Intratrade Identification of Animals
modified.
1.03 9/4/2004 Updates on multiple elements to reflect N. Carl
evolution of the TRACES system.
1.04 27/04/2004 Updated business types and streets and postal N. Carl
codes in addresses are not mandatory fields
anymore (required due to "old" imported
businesses).
1.05 19/05/2004 Country Of Destination in Search Criteria is N. Carl
implemented and now marked as such in this
document.
1.06 14/07/2004 Added CN Code Complement information N. Carl
(Species classification and names). “Veterinary
Document” element not mandatory anymore.
1.07 04/08/2004 Intratrade Decision, Official Veterinarian, N. Carl
Competent Authority became optional.
2.00 14/09/2004 Updated document to describe the new N. Carl
“request/poll-for-result” communication
fashion.
Removed message description, since the
information is described in a better way in the
XML schema files.
2.01 07/07/2005 Small corrections, removal of empty XSD annex. N. Carl
3.00 13/06/2008 Modifications introduced in TRACES V3. N. Carl
3.01 24/09/2008 New error code 18, correction code 17. N. Carl
3.02 19/10/2008 Error 18, added default value in description, N. Carl
added explanation in section 2.3.
3.03 25/11/2008 Updated description of error code 14. N. Carl
3.04 18/03/2019 New error code 19 M. Bedmar
TRACES-STS-001 System-To-System Page 2 of 12 Version: Error! Unknown
Specifications v3.04.doc document property name.TRACES TRACES REF: TRACES-STS-001
TABLE OF CONTENTS
Table of Contents ........................................................................................3
List of Tables .............................................................................................4
1 Introduction ........................................................................................5
1.1 Reference and Applicable Documents ....................................................5
1.2 Abbreviations and Acronyms ...............................................................5
1.3 Purpose and Scope ...........................................................................5
1.4 Structure of the Document .................................................................6
2 Architecture ........................................................................................7
2.1 Overview ......................................................................................7
2.2 Implementation ..............................................................................8
2.3 Security and Limitations .................................................................. 12
TRACES-STS-001 System-To-System Page 3 of 12 Version: Error! Unknown
Specifications v3.04.doc document property name.TRACES TRACES REF: TRACES-STS-001
LIST OF TABLES
Table 1-1: Applicable Documents .....................................................................5
Table 1-2: Reference Documents......................................................................5
Table 1-3: Abbreviations and Acronyms ..............................................................5
Table 2-1: Technical Specification of searchCertificate web service ............................9
Table 2-2: Technical Specification of pollSearchCertificateResult web service ................9
Table 2-3: Return codes of the TRACES web service ............................................. 12
TRACES-STS-001 System-To-System Page 4 of 12 Version: Error! Unknown
Specifications v3.04.doc document property name.TRACES TRACES REF: TRACES-STS-001
1 Introduction
1.1 Reference and Applicable Documents
1.1.1 APPLICABLE DOCUMENTS
Ref. Title Reference Version Date
N/A
Table 1-1: Applicable Documents
1.1.2 REFERENCE DOCUMENTS
RF2 TEMPO Pre-study reference manual TMP-REF-PRE 1.20-EN 12/06/2001
Table 1-2: Reference Documents
1.2 Abbreviations and Acronyms
ANIMO ANImal MOvement system
BIP Border Inspection Post
CCA Central Competent Authority
EEA European Economic Area
EU European Union
LVU Local Veterinary Unit
MS Member State (EU/EEA)
SANCO Directorate General SANté Consommateurs (Directorate General Health and Consumer
Protection of the European Commission)
SOAP Simple Object Access Protocol
Table 1-3: Abbreviations and Acronyms
1.3 Purpose and Scope
This document defines an interface to exchange Certificates related information called
TRACES System To Systems, TRACES.S2S.
The objective of this document is to describe the protocol to exchange information
between the central European TRACES system and the Member States systems.
TRACES-STS-001 System-To-System Version: Error! Unknown Page 5 of 12
Specifications v3.04.doc document property name.TRACES TRACES REF: TRACES-STS-001 1.4 Structure of the Document This document introduces the architecture that is in place to support the System-to-System data exchange between TRACES and the Member State systems. The detailed message description, including field comments, can be obtained by examining the XML schema files which has to be downloaded online from server, as described beneath. TRACES-STS-001 System-To-System Version: Error! Unknown Page 6 of 12 Specifications v3.04.doc document property name.
TRACES TRACES REF: TRACES-STS-001
2 Architecture
2.1 Overview
Figure 1: System-to-Sytem Architecture
The System-to-System architecture is based on the SOAP protocol.
The Simple Object Access Protocol (SOAP) is a protocol for exchanging information in a
decentralised, distributed environment. It is an XML based protocol that consists of three
parts: an envelope that defines a framework for describing what is in a message and how
to process it, a set of encoding rules for expressing instances of application-defined data
types, and a convention for representing remote procedure calls and responses.
For performance reasons, an asynchronous communication has been implemented between
the Member State systems and the DG SANCO TRACES system, described in the following
scenario:
TRACES-STS-001 System-To-System Version: Error! Unknown Page 7 of 12
Specifications v3.04.doc document property name.TRACES TRACES REF: TRACES-STS-001
o Step 1: The Member State system sends a request to the TRACES system using the
SOAP protocol over HTTPS (web-services call).
o Step 2: TRACES receives the message:
o Step 2.1: TRACES immediately sends back a request receipt message saying
that the request has been successfully received and will be treated as soon
as possible. The asynchronous approach has been chosen because the
processing time of such requests might take a long time depending on the
load of the system, the complexity of the request and the resulting number
of certificates. For this, the reply also contains a request identifier (token,
ticket) that must be presented to the server when the result is fetched
later.
o Step 2.2: TRACES internally submits the request to its System-to-System
module for treatment.
o Step 3: The System-to-System module processes the request and produces a report
holding the results. This report may contain a list of certificates and an operation
status code. The report is internally stored, associated to the request identifier
previously returned to the applicant, waiting to be downloaded on request.
o Step 4: The Member State system sends a polling request to the server, presenting
the request identifier.
o Step 4: TRACES handles the request by executing one of the following steps:
o Step 4.1: TRACES sends back the resulting report when it has been produced
in the meantime.
o Step 4.2: TRACES sends back an answer that the report has not been
produced yet and a new poll request should be made later.
o Step 4.3: TRACES sends back an error message when the report could not
have been produced. The error code indicates the reason.
2.2 Implementation
As described in the previous section, the request/answer dialogue has been developed in
an asynchronous fashion. Hence the party requesting the information has to create:
A client to access to TRACES web services in order to send a search request.
A client to access to TRACES web services in order to poll for the request result.
The client implementation can use different approaches (static, dynamic), as long as the
generated SOAP message conforms to the TRACES XML message schema. This schema is
provided as an XSD-file, and it is part of the WSDL specifications publicised by the server.
The WSDL-file, which describes the web service interface in a detailed manner, can be
obtained online from server by invoking the service URL with the word WSDL as parameter.
Example: "https://[server_address]/traces_ws/searchCertificate?WSDL".
The table below specifies the technical parameters to be used by the client when
performing web service call against the TRACES application (please check the WSDL-
specification for information about field-types and lengths). Depending on the way the
service is invoked, some of these parameters are not required.
TRACES-STS-001 System-To-System Version: Error! Unknown Page 8 of 12
Specifications v3.04.doc document property name.TRACES TRACES REF: TRACES-STS-001
Service URL https://[traces_server_adr]/traces_ws/searchCertificate
Target Namespace traceswsns
Service Name CertificateSearchWebService
Service Port CertificateSearchWebServicePort
Operation Name searchCertificate
Input parameter XML Type: CertificateRequest
(Custom type that potentially has to be registered to the Java XML
RPC layer before usage.)
Output parameter XML Type: CertificateRequestResult
(Custom type that potentially has to be registered to the Java XML
RPC layer before usage.)
Traces 2.0
“XMLSchemaVersion”
This value must be passed in the “XMLSchemaVersion” field of
each message sent to the server.
Table 2-1: Technical Specification of searchCertificate web service
Service URL https://[traces_server_adr]/traces_ws/pollSearchCertificateResult
Target Namespace traceswsns
Service Name CertificateSearchResultPollWebService
Service Port CertificateSearchResultPollWebServicePort
Operation Name searchCertificate
Input parameter XML Type: CertificatePoll
(Custom type that potentially has to be registered to the Java XML
RPC layer before usage.)
Output parameter XML Type: CertificatePollResult
(Custom type that potentially has to be registered to the Java XML
RPC layer before usage.)
Traces 2.0
“XMLSchemaVersion”
This value must be passed in the “XMLSchemaVersion” field of each
message sent to the server.
Table 2-2: Technical Specification of pollSearchCertificateResult web service
The server receives the searchCertificate request, the data is stored internally for
processing and a SOAP message containing a status code is returned immediately. All
values other than 0 indicate an issue. The code represent the result of the analysis of the
received search request message, not the result of the search operation it self. In addition,
the returned message contains a request identifier that must be stored locally by the
applicant and that must be passed to the server each time a web service call concerning
the present request is made against the server. No request identifier is returned when the
server detects a problem with the received search request message.
TRACES-STS-001 System-To-System Version: Error! Unknown Page 9 of 12
Specifications v3.04.doc document property name.TRACES TRACES REF: TRACES-STS-001
After internal treatment of the request, the produced report is stored on the server,
waiting to be fetched by the applicant. For this, the applicant must call the
pollSearchCertificateResult in a regularly (but reasonably) manner, passing the request
identifier, in order to see if the result is ready.
The returned message always contains a status code and potentially the produced report,
holding the list of complete certificates. When the result is not fetched within a
configurable amount of time, it expires and is deleted from server.
NB. The default message time out is 60 minutes, but this value can be modified by the
TRACES system administrator.
Status codes returned by the web services, “OperationCode” field:
NO_PROBLEM 0 Request result returned.
NO_AUTHENTICATION_CREDENTIALS 3 No user/password information specified.
AUTHENTICATION_ACCOUNT_EXPIRED 4 The specified account is expired. Please
log into the TRACES web interface to
reset your password, or contact the help
desk.
AUTHENTICATION_PASSWORD_EXPIRED 5 The specified password is expired. Please
log into the TRACES web interface to
reset your password.
AUTHENTICATION_ACCESS_DENIED 6 Authentication not successful. Error on
user name or password.
ILLEGAL_PARAMETER_VALUE_FOUND 8 Format error on search criteria.
UNSUPPORTED_SEARCH_CRITERA_FOUND 7 One of the search criteria that are not
yet supported by the TRACES server has
been specified.
INTERNAL_SYSTEM_FAILURE 9 Internal error at server side. Please send
a message to the help desk specifying
exact error code, date and time of the
error.
RESULT_NOT_READY 10 The report has not been produced yet.
Come back later.
INVALID_REQUESTID_OR_RESULT_EXPIRED 11 The passed request identifier is unknown.
This message occurs as well when the
result is expired and removed from
server, or the result is fetched twice.
FETCHING_USER_NOT_REQUESTING_USER 12 The user account, passed for fetching the
search result doesn’t match the one that
requested the search operation. The user
password must not be the same, but the
user must be authenticated correctly
against the system.
MESSAGES_PERIOD_RATIO_EXCEEDED 14 TRACES.S2S users are allowed to send a
limited number of requests over a
defined time period. Once this quota
TRACES-STS-001 System-To-System Version: Error! Unknown Page 10 of 12
Specifications v3.04.doc document property name.TRACES TRACES REF: TRACES-STS-001
exceeded, the server rejects incoming
requests with error code 14.
Different values apply during day time (6-
20h) and night time.
The current configuration is around 100
requests per 5 minutes during day time
and 200 per 5 minutes during night time.
These settings can be modified at any
time by the TRACES administrators. In
order to get the exact applied settings,
please contact the help desk. If the
default value doesn't match the needs of
your client application, please contact
the help desk for adjustment.
FAILED_TOO_MANY_RESULTS 15 The requested search operation returned
too many certificates.
The TRACES server limits the number of
certificates that can be downloaded in
one operation (default value: 110).
An additional protection is applied on the
retrieval execution time. When the time
exceeds the maximum transaction time,
the retrieval is aborted and this error
code is returned.
In both cases, the search criteria have to
be modified in order to target less of
certificates.
OPERATION_ACCESS_DENIED 16 The user account was not able to re-login
into TRACES in order to execute the
search operation. This error shouldn’t
occur unless the user account expires
between search request submission and
execution.
SERVICE_ACCESS_DENIED 17 The user account employed for a search
operation has been rejected by the
server because marked as black listed.
Please consult the TRACES help desk to
know the reason for this decision. Note
that all activities against the TRACES
server employing black listed user
accounts have to be ceased
immediately.
TOO_MANY_ACTIVE_REQUESTS 18 The user has too many active requests on
the TRACES server waiting for treatment
or retrieval.
Fetch waiting query results or wait for
storage time expiration before sending
new requests.
TRACES-STS-001 System-To-System Version: Error! Unknown Page 11 of 12
Specifications v3.04.doc document property name.TRACES TRACES REF: TRACES-STS-001
Current limitation is 100.
COUNTRY_NOT_ALLOWED 19 This country is not allowed to use TRACES
System to System.
Table 2-3: Return codes of the TRACES web service
2.3 Security and Limitations
The amount of certificate that can be retrieved in one operation is limited (by default
110). An additional protection is applied on the maximum time that a retrieval operation
can take on the server. Once exceeded, the operation is aborted with an error condition.
See error code FAILED_TOO_MANY_RESULTS.
Users employed in a web-service call must have the right to see the requested certificate
type. This can be verified by logging into the TRACES web interface. See error code
SERVICE_ACCESS_DENIED.
Ever user has a limited quota of requests that he can submit during a defined time period.
Once this quota is exceeded, the server rejects all incoming requests. See error code
MESSAGES_PERIOD_RATIO_EXCEEDED. Different quotas are allocated during the day time
and the night time. The TRACES help desk can adjust these quotas for a specific user if
required.
The same user account must be used to send the search request and to fetch the result.
See error code FETCHING_USER_NOT_REQUESTING_USER.
The result of search operations is stored a limited time on the server (default 60 minutes).
After this period, the result is discarded. Once the result is retrieved, it cannot be
retrieved again. See error code INVALID_REQUESTID_OR_RESULT_EXPIRED.
The amount of search results waiting for retrieval on the TRACES server is limit per user
account. Once this limit is exceeded, the user must either fetch waiting results or wait for
timeout before new search requests can be submitted. The default value is 100 waiting
result sets (each can hold 110 certificates).
TRACES-STS-001 System-To-System Version: Error! Unknown Page 12 of 12
Specifications v3.04.doc document property name.You can also read
