DIRECTORATE-GENERAL
INFORMATICS
Information systems Directorate
European Commission
XTB Manual
Version: / 1.2
Authors: / DE SOUSA Miriam, AMELIO Francesco
Revised by:
Approved by:
Public:
Reference Number:
TABLE OF CONTENTS
1. Background 3
1.1. Definitions and Acronyms 3
2. Introduction 4
2.1. Overview 4
2.2. General Information 4
2.3. Managing establishments 5
2.4. Using the web service 5
2.5. Maintaining the establishments 6
2.6. Business approvals and EU Approved Establishments (LMS) 7
2.6.1. Maintaining the activity types 7
2.6.2. Approval numbers and approval date 7
2.7. Transport authorizations and means of transport 9
ANNEX I: References 10
ANNEX II: Document History 11
ANNEX III: Applicable Legislation & Useful Links 12
I. Legislation 12
II. Useful Links 12
1. Background
In TRACES, each certificate is associated with a number of different establishments, or business organizations, as for instance transporter, slaughterhouse, and aquaculture holding. When creating a certificate in TRACES possibility is given to create an establishment that does not exist yet in the system with a Pre-Valid status. This allows the certificate workflow to continue and do not be blocked only because the establishment was not yet created into the TRACES information system.
The competent authority responsible for the establishment later on validates the Pre-Valid establishment, changing its status to Valid, either through the Organisations menu after receipt of a notification in its mailbox or directly while validating a certificate if in charge of the establishment. Therefore, the next time someone (within the origin country or other MS countries) needs to create a certificate, in which this establishment is involved it's not necessary to create a new one – just use the existing one.
However, in practice, the same establishment is being created numerous times (as Pre-Valid) with only slight differences.
As a result, some MS authorities have objected to the creation of establishments in their country or region that they cannot always identify in an unambiguous way. In addition, it is also seen as an important principle that only competent authorities should create establishments belonging to their countries.
Therefore, a new method is made available to allow MS competent authorities to take control of their listed establishments used in the TRACES information system.
1.1. Definitions and Acronyms
Name / DescriptionTRACES / Trade Control and Expert System
MS / Member State, in the context of this document means the countries which enjoy access to the TRACES system as EU Member States, meaning the 27 Member States, Norway, Iceland, Lichtenstein and Switzerland
XMLGate / The DG SANCO single entry point for MS submissions of structured data in XML format via web services.
CCA / Competent Concerned Authority
RCA / Regional Concerned Authority
LMS / List of approved establishments
XTB / XMLGate TRACES Business
SOAP / Simple Object Access Protocol
DB / Database
Web service / AWeb serviceis a method of communication between two electronic devices over a network. It is a software system designed to supportinteroperable machine-to-machineinteraction.
SANCAS / SANCO Authorisation System
2. Introduction
2.1. Overview
XMLGate TRACES Businesses (XTB) is a web service based on Soap protocol, made available in V.5.31 of the TRACES information system.
XTB allows the MS to update the TRACES database with the listed establishments in their databases.
It does not provide a Graphic User Interface (GUI), since XTB web services (as all web services) share businesses logic, data and processes through a programmatic interface across a network. Therefore, the MS that wishes to make use of the service typically needs to create a web service client to provide this specific functionality.
The SANCO common entry point for web services XMLGateV2, as illustrated in the following image.
Figure 1 XTB web service workflow
The necessary information in order to connect to the web service and start the development of a user using the web service is provided in a set of user documents, including a technical HOW TO document, a WSDL file and a sample SOAPUI test project.
It is available on CIRCA, here.
2.2. General Information
This web service is available to the Member States' Country or Regional Competent Authorities (CCA, RCA) allowing them to consult, create, delete, and modify the establishments in their own countries / regions.
XTB will act as an exchange system between the national databases and the TRACES system database. In addition, the CCA/RCA can decide when to update the information in the TRACES database.
By default, one user per country is granted (CCA profile). As users are linked to countries, they can only manage their national businesses. Nevertheless, additional user authorities may be created upon request to the SANCO-APP SUPPORT team.
Authentication is managed through the SANCO Authorisation Service (SANCAS). The login profile is created at the same time as the CCA/RCA profile.
The CCA/RCA user can choose which activity type to manage at a given moment. Nevertheless, the user is able to manage all activity types in its country.
Note: For more information on the different activity types and according to legislation, please refer to I. Legislation.
Other CCA/RCA users from other countries will not be able to create an establishment, even with the Pre-Valid status.
Indeed, the establishments created by the concerned CCA/RCA user will be Valid.
2.3. Managing establishments
Through the web service, CCA/RCA users are able to create and modify establishments according to the same fields as are used in the TRACES online system.
It is important that the users insert all required details regarding the establishment as possible, so that the information is complete. For instance, it is mandatory to provide the Approval Number. The Data Dictionary provides more details on this.
Note: For more information on the uniqueness of these Approval Numbers, please refer to 2.4
They can also delete establishments in their own database. Then, the concerned establishment is not visible anymore in the TRACES database.
Note: Please bear in mind that is not yet possible to delete establishments that have users linked to it.
If the information inserted or modified is not correct or is incomplete, the XTB web service returns an error message.
2.4. Using the web service
The following are some best practice steps to ensure a correct use of the web service when a CCA/RCA establishes web service control over an organisation category for the first time.
(1) The national authority synchronizes the national organisation database with TRACES organisations using one or both of the followings:
- In TRACES, from the System Management menu, select Export XML. See the following image, Figure 2 Export XML.
- Using the Web Service method SearchBusinessRequest, searches for the organisations in the national database and retrieve the TRACES business ID.
Figure 2 Export XML
(2) The user maps and / or completes the information from TRACES based on its local MS database information for the concerned establishment group (e.g. Cutting Plant).
(3) Through the TRACES business ID, the user is able to manage (modify or delete) the establishments to reflect the state of the local database. Through the web service, establishments not yet available in TRACES can be created and in this case, the TRACES system will provide the TRACES business ID.
(4) Before submitting the modifications to TRACES, the user needs to be sure that is having the up-to-dates version of the organisation. Another user may have changed it in the meanwhile.
Therefore, the user needs to call the "Read" procedure in XTB to make sure it is submitting the changes on the latest list.
(5) The day after successful submission to TRACES, the updated list containing all new or modified establishments will be available in the Establishment List Publications section on the TRACES system, as in the Commission's official page accessible here.
2.5. Maintaining the establishments
Once a MS is in charge of an establishment category, it is expected to frequently and regularly maintain the TRACES database to correctly reflect the state of the national database. Failing to do so may impede trade, since a MS establishment that is not yet available in TRACES cannot be created by any actor other than the CCA/RCA. The following options exist for this maintenance:
(1) Automatic maintenance: via the XTB web service described earlier.
(2) Manual maintenance: via the TRACES online application
The recommended approach is to always do automatic, web service based maintenance and to only resort to manual maintenance if needed, e.g. to urgently unblock a certificate.
It should also be noted that once the MS has taken control of an establishment category, the correctness of the TRACES database for this category becomes the responsibility of the MS in question. (Just as the quality of the national DB is the responsibility of the CCA/RCA, the quality of the corresponding TRACES DB entries also becomes the responsibility of the same CCA/RCA.)
2.6. Business approvals and EU Approved Establishments (LMS)
The description of an organization includes also the type of activities. A typical example of approved establishment is a Holding. An organization can have multiple types; in example, a Bovine Holding, a Porcine Holding and an Importer at the same time.
Some special activity types are regulated by the EU legislation and the list of approved establishments is published on official website of the European Commission. To retrieve the description of non-approved establishments types use the WS method ListBusinessApprovalTypes, to get the list and description of the approved establishments use ListLMSCategories, and ListLMSChapters
2.6.1. Maintaining the activity types
The methods Add/DeleteBusinessApproval, Add/DeleteLMSCategory, Add/DeleteLMSRemark shall be used to handle the operations on the activities of an organization. More technical information can be found in the Data Dictionary document.
2.6.2. Approval numbers and approval date
Approval number for LMS activities is mandatory when creating a new listed establishment, whilst the approval date is mandatory only for veterinary establishments.
EU establishments may have one or more approval numbers by country, as long as they remain unique within a combination of country + postal code + chapter. The chapter can be divided in:
- Food
- Animal-by-product
- Veterinary, Semen and Embryo
Figure 3 Approval numbers
That is, the same region within a given country may have the same approval number for different chapters (Veterinary, ABP, Food, as in the example), but they must be unique, and therefore different, within each chapter.
Please refer to the following examples to have a better understanding.
Example 1:
Figure 4 Approval numbers country example
In this given example, within the same country (Poland) the uniqueness of the approval number is ensure by changing postal code numbers (86-300 or 86-306), even if the chapter number is the same (Nr 1, for instance).
In that case, for an establishment in Poland, postal code number 86-300 which activity is in chapter Animal-by-product the approval number could be POL T 86-300 1. For another establishment in the same postal code, and same chapter, the approval number should change. It would become POL T 86-300 2.
2.7. Transport authorizations and means of transport
Certain kind of organizations, as the Private Transporter, requires information concerning the transport authorisations (element TRANSPORT_AUTHORIZATION) and the optional means of transport (element BUSINESS_MEAN_OF_TRANSPORT).
While the transport authorization can be modified via the UpdateBusiness method, the Means of Transport must be amended via the Add/DeleteMeanOfTransport).
ANNEX I: References
Ref. / Title / Reference / Version / DateTRACES Release notes / http://circa.europa.eu/Public/irc/sanco/tracesinfo/library?l=/version/version_530&vm=detailed&sb=Title / 5.30
TRACES Metadata WS Vision / http://circa.europa.eu/Public/irc/sanco/tracesinfo/library?l=/manuals/manual_on_xtb / 1.1 / 22/09/2010
TRACES Metadata Webservices Administrators' Guide / http://circa.europa.eu/Public/irc/sanco/tracesinfo/library?l=/manuals/manual_on_xtb
XTB Webservice Data Dictionary / http://circa.europa.eu/Public/irc/sanco/tracesinfo/library?l=/manuals/manual_on_xtb / 1.0 / 15/02/2012
Table 1: Referenced Documents
ANNEX II: Document History
Version / Date / Comment / Modified Pages1.0 / 17/02/2012 / Creation / All
1.1 / 24/02/2012 / Review comments implementation / All
1.2 / 28/02/2012 / Final version / All
ANNEX III: Applicable Legislation & Useful Links
I. Legislation
(1) EU Food establishments, where the approval number is mandatory: http://ec.europa.eu/food/food/biosafety/establishments/techspecs_en.pdf
(2) Veterinary establishments:
http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2009:247:0013:0025:EN:PDF
- aquaculture
http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2006:328:0014:0056:EN:PDF
- bovine holding:
Council Directive 64/432/EEC;
http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=CELEX:31964L0432:EN:NOT
- oven/caprine
Council Directive 91/68/EEC:
http://eurlex.europa.eu/smartapi/cgi/sga_doc?smartapi!celexapi!prod!CELEXnumdoc&lg=EN&numdoc=31991L0068&model=guichett
- porcine:
Council Directive 64/432/EEC
http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=CELEX:31964L0432:EN:NOT
- control posts
Article 3 Council Regulation (EC) 1255/97
http://ec.europa.eu/food/animal/welfare/transport/docs/council_regulation_1255_97.pdf
(3) ABP establishments:
http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2011:054:0001:0254:EN:PDF.
(4) Technical specification for listings:
http://ec.europa.eu/food/food/biosafety/establishments/docs/technical_specifications_d7177%202010_rev1_01%203%202011.pdf
II. Useful Links
(1) User documentation available on circa: http://circa.europa.eu/Public/irc/sanco/tracesinfo/library?l=/manuals/manual_on_xtc&vm=detailed&sb=Title
(2) Establishments official list: http://ec.europa.eu/food/food/biosafety/establishments/index_en.htm
XTB Manual Page 2 / 12
Document Version 1.2 dated 26/07/2013