INTERFACE SPECIFICATION NEXT VISUAL TAG ENQUIRY VERSION 1.3 JUNE 2015

Transcription

1 INTERFACE SPECIFICATION NEXT VISUAL TAG ENQUIRY VERSION 1.3 JUNE 2015

2

3 CONTENTS VERSION CONTROL... 1 INTRODUCTION... 2 Interface Method... 2 Support... 2 INTERFACE RULES AND PROCESSES... 3 Business Rules... 3 Enquiries Process Rules... 3 DATA STANDARDS... 5 Data formats... 5 Common System Interface Response... 5 Validation Rules & Responses... 5 Schema Validations... 5 Database Validations... 6 XML SCHEMA... 7 Soap Header... 7 Authentication and Authorisation... 7 Schemas... 8 Common.xsl... 8 Types.xsl... 9 Sample Request Sample Response... 10

4 VERSION CONTROL Version Date Comment /03/2014 Published version /05/2013 Updated to block reservation of Birth ID tags with participant code without year /12/2014 Added a new column MinimumContiguousSequenceL and updated the rule for the Year column /06/2015 Formatted to new template. 25 June 2015 Page 1

5 INTRODUCTION The purpose of this document is to provide information to users on how they can interact with the NAIT System in order to submit bulk enquiries for next available NAIT Visual Tag ID. The information is provided for stakeholders wishing to transact with the NAIT system via a common system interface (web service) and will require technical expertise to ensure that a robust solution is developed. INTERFACE METHOD The method available for this enquiry will be SOAP/XML message via a web service - CSI (Common System Interface). NAIT response messages to uploads will be via SOAP/XML. SUPPORT NAIT will provide technical support if required when implementing interfaces defined in this document. The following assistance can be provided: Support prior to testing, e.g. providing test data (where necessary), reviewing test data Test user accounts Access to test environments 25 June 2015 Page 2

6 INTERFACE RULES AND PROCESSES This section details the business rules and processes that apply to enquiries through the common system interface. Some of the business rules include references to Rules and Responses. These are covered in a later section and outlines validations and error handling. BUSINESS RULES This request is intended to provide the next available birth ID visual tag number in a sequence, prior to reserving a NAIT Visual Tag ID. It is intended for use by tag manufacturers and users of tag manufacturers systems. BR1 BR2 BR3 BR4 BR5 BR6 The login credentials used must be Tag Manufacturer. User accounts must be active. Users must enter a valid industry code. The tag number returned will contain this industry code in the NAIT Visual Tag ID. Only one industry code may be submitted per record. Users may enter a valid year code. The tag number returned will contain this year code. If no year code is required, the tag number returned will not include a year code. If a NAIT number is supplied, it must have a status of active or initial. BR7 The upload can include multiple queries. The maximum number of queries is set to 100. BR8 BR9 Next Visual Tag Enquiry is designed only for use with birth ID formats. Traka tags or other NAIT tags with the RFID as a component of the NAIT Visual Tag ID are not included. The returned message will contain the next available NAIT Visual Tag ID. This is the tag with the lowest available sequence number, once all reserved or uploaded tag numbers with the specified industry code (and year code, if applicable) have been discounted. The tag returned will be one of the following birth tag formats, depending on which criteria have been provided in the enquiry: Participant code with year: pppp-yy-nnnnnn AHB herd number with sequence only: aaaaaaa-nnnnnn AHB herd number with year: aaaaaaa-yy-nnnnnn NAIT number with sequence only: AAAAAAAA-nnnnnn NAIT number with year: AAAAAAAA-yy-nnnnnn Values: a = AHB herd number (7 digits) A = NAIT number (2 6 or 8 digits) p = Participant code (1-4 alpha characters) n = sequence number (1-6 digits) y = year (2 digits) NAIT Visual Tag ID components should be separated by a hyphen (-). BR10 MinimumContiguousSequenceLength must be between 1 and 10,000 inclusive. ENQUIRIES PROCESS RULES 1. The intention is that messages can be submitted at any time of the day or night and will be processed upon receipt; however, any system sending data to NAIT through the CSI should be configurable so that transactions can be sent at specified times to allow for load balancing and ensure timely system response. 2. Where NAIT is unable to process a message due to the NAIT system or interface being unavailable NAIT will endeavour to notify external parties of the issue and advise when the system will be available for re-submitting. Those sending information should keep a record of each message they have submitted for the purpose of re-submitting. 25 June 2015 Page 3

7 3. The schema is a published message contract that describes the XML elements along with the expected types. Messages should be validated against the schema by the sender before transmitting to NAIT. Where a message is sent that does not pass schema validation then the whole message is rejected at the first error encountered. 4. For audit purposes NAIT will log details of each interface transaction received and processed, including: o Transaction ID (identifies the transaction; generated by NAIT) o Date/Time received o Sender ID o Transaction Type/Name o Transaction status (successful/file contained records that were rejected/failed) o Record status (success/failed) o A copy of each record that was rejected o A copy of each record that a warning was generated for 5. NAIT will send a response for each message processed. Each record will be identified as either being successfully processed or failed. Where a record has failed then the response is returned with details of why it was rejected. The response will typically include: o A status for each record sent success/failed o Failed records will include details of why a record was rejected o Details of any records that generated a warning message o External Record Reference o The sequence number of each row as it was submitted in the request 6. NAIT will retain a copy of each batch uploaded through the CSI for audit purposes. 25 June 2015 Page 4

8 DATA STANDARDS DATA FORMATS Field Name Mandatory / Optional / Conditional Format Comments External Record Reference O 50 char Optional reference number (not saved in the NAIT system but bounced back as part of the response). AHB Herd ID C Numeric 7 If AHB Herd ID is provided then Participant Code and NAIT Number cannot be. Visual tag number returned will contain AHB Herd ID as industry code component. Participant Code C Char 1-4 If Participant Code is provided then AHB Herd ID and NAIT Number cannot be. Visual tag number returned will contain Participant Code as industry code component. NAIT Number C Numeric 2-6 or 8 If NAIT Number is provided then Participant Code and AHB Herd ID cannot be. Visual tag number returned will contain NAIT Number as industry code component. Year C Numeric 2 If a year code is provided, NAIT Visual Tag ID will include specified year code. If not included, NAIT Visual Tag ID will consist of industry code and sequence number components only. Year is mandatory when Participant Code is provided MinimumContiguousS equencelength O Numeric If a value is provided NAIT will return the next available visual ID that allows for this number of sequential tags. If Null, NAIT will default this value to 300. Common System Interface Response The CSI response fields define the data returned to the sending system after receiving and processing a data package. Note: "Date/Time received" is returned in HTTP response header Field Mandatory / Optional / Conditional Comment External Record Reference Submitted Record Sequence Number For each failed record: Error Code Error Description For each successful record: NAIT Visual Tag ID C M C C The record number provided by the sender The sequence number of the submitted record order See next section, SOAP message validations Rules and Responses The format for the NAIT Visual Tag ID is specified in BR9 VALIDATION RULES & RESPONSES Please Note: that these responses are at the database level and are not returned where the schema fails validation. The sender should validate against the published schema before transmitting to NAIT. The whole message will be rejected at the first error encountered if a message does not pass schema validation. Schema Validations 25 June 2015 Page 5

9 Rule Schema Action Message/Comment Message must match the approved NAIT Schema Message rejected Incorrect schema format Users uploading a message via common system interface must pass authentication - valid username and password Message rejected Access is denied A user account uploading a message must be active Message rejected Access is denied Users uploading a message via common system interface must have the correct system permission to undertake the transaction. Message rejected Access is denied Database Validations Rule Database Action Message/Comment Only one industry code must be provided Record rejected One industry code must be specified If a Participant code is included, it must be in a valid format Record rejected Participant code is not a valid format If an AHB herd number is included, it must be a valid format Record rejected AHB herd number is invalid format If a NAIT number is included, it must exist in the system Record rejected Invalid submitting NAIT Number - does not exist in system If a NAIT number is included, it must be valid and active Record rejected NAIT number must be active If a year is included, it must be in the correct format Record rejected Year must be in the correct format - YY Tags with a participant code require a year Record rejected Year is required when participant code is provided 25 June 2015 Page 6

10 XML SCHEMA This section describes the NAIT SOAP transactions, both request and response. Schema version is identifiable by date from the target namespace field of the schema body. The namespace for all UAT and Production schemas will be: Note: The common and type.xsd contains schema for the known transactions acceptable to NAIT. These are examples and may have been updated. For the latest versions of the Common and Type xsd files go to the following link: NAIT reserves the right to edit or update the schema as required. NAIT will consult on any significant changes that will affect external users use of the NAIT system. SOAP HEADER The request headers should look similar to the following. The action element of the request header determines which CSI function is being performed. Once the authentication and authorisation steps have been performed the NAIT system will route the XML message body to the appropriate component for processing. POST HTTP/1.1 Content-Type: text/xml; Host: animaltracecsi-uat.nait.co.nz Content-Length: 1477 SOAPAction: A valid action e.g. NextVisualTagEnquiry All SOAP messages submitted to the NAIT Common Systems Interface (CSI) shall follow the same general format: <s:envelope xmlns:s=" <s:header xmlns:nait=" <nait:username>a valid user name</nait:username> <nait:password>a valid password</nait:password> </s:header> <s:body> Message Body </s:body> </s:envelope> AUTHENTICATION AND AUTHORISATION All CSI requests will be authenticated using the same user names and passwords that are used by users accessing the web site. The SOAP request wraps the XML message body with the external party s authentication information. The supplied username and password will be authenticated, authorization checks will be performed, and the XML message body will be passed on to the appropriate component for processing. If the username and/or password are invalid a SOAP fault is returned to the calling party as follows: <s:fault> 25 June 2015 Page 7

11 <faultcode xmlns:a=" xmlns=""> a:failedauthentication </faultcode> <faultstring xml:lang="en-nz" xmlns=""> Access is denied. </faultstring> </s:fault> If the username / password is valid but the username is not permitted to submit the specified Common Systems Interface function then a SOAP fault is returned to the calling party as follows: <s:fault> <faultcode xmlns:a=" xmlns=""> a:failedauthentication </faultcode> <faultstring xml:lang="en-nz" xmlns=""> Access is denied. </faultstring> </s:fault> SCHEMAS The message body will be validated against the appropriate XSD schema based on the specified Action. The schemas below are examples and may have been updated. For the latest versions of the Common and Type xsd files go to the following link Common.xsl <complextype name="listofnextvisualtagenquiry"> <element name="nextvisualtagenquiry" type="tns:nextvisualtagenquiry" minoccurs="0" maxoccurs="unbounded"/> <complextype name="nextvisualtagenquiry"> <element name="externalrecordreference" type="tns:string200" minoccurs="0"/> <element name="ahbherdid" type="tns:string20" minoccurs="0"/> <element name="participantcode" type="tns:string20" minoccurs="0"/> <element name="naitnumber" type="int" minoccurs="0" nillable="true"/> <element name="year" type="int" minoccurs="0" nillable="true"/> 25 June 2015 Page 8

12 Types.xsl <element name="nextvisualtagenquiryrequest"> <complextype> <element name="listofnextvisualtagenquiry" type="common:listofnextvisualtagenquiry" minoccurs="0" maxoccurs="1" /> </element> <element name="nextvisualtagenquiryresponse"> <complextype> <element name="successnextvisualtagenquiry" minoccurs="0" maxoccurs="1"> <complextype> <element name="successnextvisualtagenquiry" type="tns:successnextvisualtagenquiry" minoccurs="0" maxoccurs="unbounded"/> </element> <element name="errornextvisualtagenquiry" minoccurs="0" maxoccurs="1"> <complextype> <element name="errornextvisualtagenquiry" type="tns:errornextvisualtagenquiry" minoccurs="0" maxoccurs="unbounded"/> </element> </element> <complextype name="successnextvisualtagenquiry"> <element name="externalrecordreference" type="common:string50" minoccurs="0"/> <element name="submittedrecordsequencenumber" type="int"/> <element name="visualtagid" type="string"/> <complextype name="errornextvisualtagenquiry"> <element name="externalrecordreference" type="common:string50" minoccurs="0"/> <element name="submittedrecordsequencenumber" type="int"/> <element name="errorcode" type="int"/> 25 June 2015 Page 9

13 <element name="errordesc" type="string"/> SAMPLE REQUEST <NextVisualTagEnquiryRequest xmlns:i=" xmlns=" <ListOfNextVisualTagEnquiry xmlns:d2p1=" <d2p1:nextvisualtagenquiry> <d2p1:externalrecordreference>enquiry.1</d2p1:externalrecordreference> <d2p1:naitnumber>123456</d2p1:naitnumber> <d2p1:year>14</d2p1:year> </d2p1:nextvisualtagenquiry> </ListOfNextVisualTagEnquiry> </NextVisualTagEnquiryRequest> SAMPLE RESPONSE <NextVisualTagEnquiryResponse xmlns=" xmlns:i=" <SuccessNextVisualTagEnquiry> <SuccessNextVisualTagEnquiry> <ExternalRecordReference>ENQUIRY.1</ExternalRecordReference> <SubmittedRecordSequenceNumber>1</SubmittedRecordSequenceNumber> <VisualTagID> </VisualTagID> </SuccessNextVisualTagEnquiry> </SuccessNextVisualTagEnquiry> <ErrorNextVisualTagEnquiry/> </NextVisualTagEnquiryResponse> 25 June 2015 Page 10