NATIONAL STUDENT INDEX The Guide To Integrating With the National Student Index Specifications for integrating with the Ministry of Education’s National Student Index System Version 6.5 March 2016 National Student Index c/- Ministry of Education Service Desk Ministry of Education P O Box 1666 Wellington Guide to National Student Index - GINS 6.5-final.docx Page 1 of 148 Table of Contents Table of Contents ....................................................................................................... 2 1 Introduction ......................................................................................................... 5 1.1 Document Purpose ...................................................................................... 5 1.2 Document Audience ..................................................................................... 5 1.3 Interface Support ......................................................................................... 5 1.4 Contacts ....................................................................................................... 5 1.5 Document Revision History .......................................................................... 6 2 Getting Started .................................................................................................... 8 2.1 What is the National Student Index? ............................................................ 8 2.2 National Student Index queries .................................................................... 8 2.3 What can the NSI system be used to do? .................................................... 8 2.4 What is an NSI record? ................................................................................ 9 2.5 Who needs an NSI record? .......................................................................... 9 2.6 How do Organisations find out about changes to NSI data? ...................... 10 2.7 How can the NSI system be accessed? ..................................................... 10 2.7.1 Web Interface ..................................................................................... 10 2.7.2 REST Interface ................................................................................... 11 2.7.3 Batch File Interface ............................................................................. 11 2.8 What is the difference between the Web, REST and Batch Interfaces? .... 11 2.9 What is the best NSI system interface option for you? ............................... 12 2.10 Integration Considerations ......................................................................... 12 2.11 What next? ................................................................................................. 14 3 NSI Functional Overview ................................................................................... 16 3.1 Introduction ................................................................................................ 16 3.2 Unknown Birth date .................................................................................... 16 3.3 Search ....................................................................................................... 16 3.4 Add / Insert................................................................................................. 18 3.5 Update ....................................................................................................... 19 3.6 Merge Request .......................................................................................... 22 3.7 Change Notifications .................................................................................. 22 3.7.1 Changed Field Indicator ...................................................................... 23 3.8 Challenge ................................................................................................... 24 3.9 Create/Update Student Provider Relationships.......................................... 24 4 Web Interface .................................................................................................... 26 4.1 Overview .................................................................................................... 26 4.2 Security and Authentication ....................................................................... 27 5 REST Interface.................................................................................................. 28 5.1 What is REST? .......................................................................................... 28 Guide to National Student Index - GINS 6.5-final.docx Page 2 of 148 5.2 Accessing the API ...................................................................................... 28 5.3 Authentication – ESAA OAuth.................................................................... 29 5.3.1 ESAA Environment URLS................................................................... 30 5.3.2 Privilege levels .................................................................................... 30 5.3.3 Authentication and Authorisation Errors.............................................. 30 5.4 API details .................................................................................................. 30 5.4.1 Naming standard ................................................................................ 30 5.4.2 Dates .................................................................................................. 31 5.4.3 JSON .................................................................................................. 31 5.4.4 Encoding ............................................................................................. 31 5.4.5 Query string parameter encoding ....................................................... 31 5.5 Result codes and messages ...................................................................... 32 5.6 REST API Resources ................................................................................ 33 5.6.1 Session Resource ............................................................................... 33 5.6.2 Student Functions ............................................................................... 33 5.6.3 The student resource .......................................................................... 33 5.7 REST Function Details ............................................................................... 40 5.7.1 Create NSI Session via REST ............................................................ 40 5.7.2 Search Request via REST .................................................................. 43 5.7.3 Add Student Record via REST ........................................................... 50 5.7.4 Modify Student Record via REST ....................................................... 61 5.7.5 Request to Merge Student Records via REST .................................... 70 5.7.6 Create / Update Student Provider Relationship (SPR) via REST ....... 74 5.7.7 Logout of the NSI via REST ................................................................ 78 6 Batch File Interface ........................................................................................... 80 6.1 Overview .................................................................................................... 80 6.2 Accessing the Batch interface .................................................................... 80 6.2.1 Batch File Types ................................................................................. 80 6.2.2 Batch File Format ............................................................................... 81 6.2.3 File Naming Conventions .................................................................... 81 6.2.4 Delimited File Footers ......................................................................... 82 6.2.5 Uploading/Downloading Batch Files ................................................... 83 6.3 Security and Authentication ....................................................................... 83 6.4 Batch File Functions .................................................................................. 85 6.4.1 Search Request File ........................................................................... 85 6.4.2 Update/Insert Batch File ..................................................................... 85 6.4.3 Merge Request Batch File .................................................................. 87 6.4.4 Change Notification Batch Files .......................................................... 87 6.4.5 Student-Provider Relationship (Add / Update) .................................... 87 6.5 Automated Upload/Download of Batch Files .............................................. 88 6.5.1 Login to the NSI through Batch Interface ............................................ 89 Guide to National Student Index - GINS 6.5-final.docx Page 3 of 148 6.5.2 Logout from the NSI through the Batch Interface ................................ 91 6.5.3 Automated Upload of Batch files ......................................................... 93 6.5.4 Automated Download of Batch Files ................................................... 93 6.6 Delimited Batch File Formats ..................................................................... 94 6.6.1 Encoding ............................................................................................. 94 6.6.2 Search ................................................................................................ 95 6.6.3 Update/Insert ...................................................................................... 99 6.6.4 Merge Request ................................................................................. 104 6.6.5 Student-Provider Relationship (ATA) Add / Update .......................... 107 6.6.6 Change Notifications ......................................................................... 110 6.7 XML Batch File Formats .......................................................................... 111 6.7.1 Encoding ........................................................................................... 111 6.7.2 Search .............................................................................................. 112 6.7.3 Update/Insert .................................................................................... 118 6.7.4 Merge Request ................................................................................. 126 6.7.5 Student-Provider Relationship (ATA) Add/Update ............................ 130 6.7.6 Change Notifications ......................................................................... 134 7 Appendix B: Glossary of Terms....................................................................... 136 8 Appendix C: Error Codes ................................................................................ 138 9 Appendix D: Related Documents .................................................................... 144 9.1 Web Interface User Guide........................................................................ 144 9.2 NSI Web UI Learning Module .................................................................. 144 9.3 NSI Web UI Quick Reference Guide (QRG) ............................................ 144 9.4 ESAA Application Form ........................................................................... 144 10 Appendix E: REST Code Example .............................................................. 145 10.1 Encode username and password ............................................................. 145 10.2 Get Authentication token from ESAA ....................................................... 145 10.3 Create an NSI session ............................................................................. 146 10.4 Send NSI request ..................................................................................... 147 10.5 Logout using NSI session token in request header .................................. 147 Guide to National Student Index - GINS 6.5-final.docx Page 4 of 148 1 Introduction 1.1 Document Purpose This document explains the necessary requirements to enable your organisation / application to integrate with the National Student Index (NSI) system. It explains the NSI functionality and details each of the options available for integration with the NSI. 1.2 Document Audience This document is written for Organisations, their NSI users and those developing systems that interface with the NSI. The first part of this document deals with business processes and general matters relating to integration. This includes section 2 (Getting Started) through to section 3 (NSI Functional Overview). The final part of this document deals with the technical aspects of integrating the NSI with your systems. This includes section 4 Web Interface onwards. 1.3 Interface Support IMPORTANT NOTE: Please be aware that this Guide for Integrating with the NSI (GINS) is valid as at issue date. The Ministry reserves the right to upgrade interfaces to ensure compliance with current industry standards, and to meet future business requirements. We will provide notice to known users of the interfaces of changes impacting on them. Support for legacy interfaces will be withdrawn after a notified ‘sundown’ period. The Ministry has made available a test version of NSI (Compliance) for use by Vendors / providers when testing their interface with NSI. The Compliance database is refreshed from Production on the 1st Tuesday of every month. 1.4 Contacts Matters relating to the scope and nature of the NSI or requests for technical support in integrating with the NSI system should be addressed to: National Student Index c/- Ministry of Education Service Desk Ministry of Education Guide to National Student Index - GINS 6.5-final.docx Page 5 of 148 P O Box 1666 Wellington or emailed to: service.desk@education.govt.nz or call the MoE Service Desk on 0800 422 599 1.5 Document Revision History This section records any major updates applied to this document since version 4.4. Specifically, it lists the document version number and date and describes the changes. Date Revision Sections Changed Description of Changes 15/12/2014 5.0 Various NSI Replacement Version released 22/12/2014 5.1 Various Updates based on Vendor feedback: Section 1.2 – last paragraph – reference corrected Document revision history updated Added Section 3.2 Unknown Birth date Clarifications in Section 3.7 Change Notifications Clarifications in Section 3.9 Create / Update Student Provider Relationships Clarification in Section 5.7.7.2 Clarification in Section 5.5.2.1 Clarification in Section 5.5.4.1 Change of font in Section 6.5.4.1 Clarification in Section 6.5.5.1.1 Change of font in Section 6.6.4.1 Corrected last tag in Section 6.6.5.1 Clarifications and font change in Section 6.6.5.1.1 Clarification in Appendix C - Error message 290 11/02/2015 5.3 Various Tidy up of document for final release 01/05/2015 5.4 Various Accept all changes for final release of GINS 07/07/2015 5.5 Various Minor updates made to add further information for vendors Addition of the REST code example Guide to National Student Index - GINS 6.5-final.docx Page 6 of 148 03/02/2015 Date Revision Sections Changed Description of Changes 09/07/2015 5.6 Various Accept all changes for release of GINS 22/07/2015 6.0 Various Remove the XML and SOAP Interface details into separate documents Update the REST code examples to reference the correct URLs 24/02/2016 6.1 Various Various - Update Service desk email address 1.3 – Reference Compliance environment 3.3 – Specify the use of ~ in search 4.2 – Reference NSI timeout period 5.3 – Updated reference to Appendix E (REST code examples) 5.6.3 – Separated Alt Name from student resource 5.7.2.2.1.1 – Alternate Name(s) may be included in output from NSN search 5.7.5.1.1 – Update Resource URL 6.2 – New section - Accessing the Batch Interface 10.1 – Updated encoding result 24/2/2016 Various Accepted Tracked changes (v6.1) 07/03/2016 6.3 5.2 Accessing the API Corrected REST Production URL 01/06/2016 6.4 5.4 Added ESAA URL’s as references for authentication 01/08/2016 6.5 5.6.3 Date formatting specs corrected. Removed leading space and added third milliseconds digit. 6.2 Guide to National Student Index - GINS 6.5-final.docx Page 7 of 148 2 Getting Started 2.1 What is the National Student Index? The National Student Index (NSI) is a database system maintained by the Ministry of Education and is the education sector’s core register of learner identity data. The NSI is used to allocate a unique identifier, a National Student Number (NSN) to every student in New Zealand. Each student should only be allocated one NSN which will be used throughout their early childhood, school and tertiary education. An NSN will be allocated to a student when they first enrol in early childhood education, a school or tertiary education in New Zealand. NSNs are required to be included for every student reported to the Ministry for example in the Single Data Returns (SDRs). This allows information about each student to be linked together. 2.2 National Student Index queries The day-to-day operation of the NSI is managed by the Ministry of Education's Service Desk. Specifically, the Service Desk is responsible for helping organisations to start using the National Student Index (NSI), establishing and maintaining access privileges, distributing documentation and informational material and providing ongoing technical and operational guidance. Organisations can contact the Ministry of Education's Service Desk with questions or requests. Phone 0800 422 599 or email service.desk@education.govt.nz. 2.3 What can the NSI system be used to do? The NSI system is available for organisations to perform searches on existing records, add new records, update existing records and to request that two or more duplicate NSI records be merged. Organisations can use student information from the NSI for enrolment purposes as well as for reporting to the Ministry, TEC and NZQA. Individuals can request a copy of their information held on the NSI. Where required, they can submit a request for their information to be corrected through the MoE Service Desk by providing appropriate documentation. Guide to National Student Index - GINS 6.5-final.docx Page 8 of 148 2.4 What is an NSI record? An NSI record is unique to a student and records basic identification details. The fields on an NSI record include: Family name Three Given names Birth date (DoB) Gender Residential status Record status Date of death Alternative names A preferred name indicator Verification indicators for the name & birth date fields and for the residential status field An NSI record can have one of two statuses with an associated Record status reason. These are: 1) Active – the record is in use on the NSI application. a) In use – the student record is used by the NSI application and can be Searched for and Updated. 2) Inactive – the record has been made inactive for one of the following reasons: a) Slave – following the receipt of a request to merge two or more student records. Once the merge request is processed, the duplicate record(s) will be marked as a ‘Slave’ record and linked to the ‘Master’ record. b) Deceased – following the receipt of notification and supporting documentation of a student’s death from an Organisation c) Created in error – following the receipt of notification of an incorrectly created student. d) Do not use – following the receipt of notification that this record should not be used. 2.5 Who needs an NSI record? NSI records will be created for individuals who: Enrol in a New Zealand Early Childhood Education provider. Enrol in a New Zealand school. Register for the NCEA Enrol or seek to enrol with a tertiary organisation All type “D” students (as defined in the Ministry of Education’s Single Data Return manual) must have a corresponding NSI record with verified name, birth date and residential status to claim student achievement component (SAC) funding. Guide to National Student Index - GINS 6.5-final.docx Page 9 of 148 2.6 How do Organisations find out about changes to NSI data? To ensure that changes to NSI records are communicated to organisations that need to know, a record of a student’s ‘relationship’ with an organisation is maintained by the NSI system. When an NSI record is added or updated by an organisation, that NSN is marked as having a ‘relationship’ with that organisation. Any changes made to an NSI record will be notified to all organisations that have requested to receive change notifications and have a current ‘relationship’ with the student via the change notification process. Change notifications applicable to an organisation will be available for viewing on the NSI web interface. Files may be downloaded from the web interface or through the Batch Interface. For example, if a Student’s Birth date is updated by an organisation, all the organisations which have a relationship with that student will be notified. If a student dies, the change notification process will also be used to inform all organisations that have either a current or expired ‘relationship’ with the student. 2.7 How can the NSI system be accessed? The NSI system can be accessed only by authorised people from: ECE Services Schools (via the ENROL system) NZQA Tertiary Education Organisations Tertiary Education Commission (TEC) Ministry of Education support staff. Providers may wish to access the NSI through a chosen Student Management System (SMS). Individual SMS applications will integrate with the NSI through the REST and/or BATCH interfaces. The NSI system can be accessed in any of three different ways. These three methods are all offered so that you can choose the ones which are best suited to your organisation. Please note that all new providers will need to go through a go live process before they are given access to the NSI system. Login details and information about the go live process can be obtained from the Ministry of Education. MoE Service Desk (0800 422 599 or email service.desk@education.govt.nz) The interface options are: 2.7.1 Web Interface The NSI web site allows users to perform NSI functions which will be processed immediately. All functionality (including additional functionality such as raising a Challenge, viewing reports, viewing Merge status, viewing Change Notifications that is not available through other interfaces) can be accessed by providers who are Guide to National Student Index - GINS 6.5-final.docx Page 10 of 148 authorised to do so. No special integration is required to use this interface other than the need to have a valid username and password to log in with REST Interface 2.7.2 REST Interface The REST interface allows SMS systems to integrate with NSI data and functionality, over a standardised protocol. This allows the maintenance of your student records to remain in your SMS software, while sending and retrieving data from NSI in the background. Integration with the REST interface requires custom development, which is covered later in this document. 2.7.3 Batch File Interface A batch file interface will be available to allow organisations to submit requests for NSI searches, additions, updates, and merges and the creation/updating of student relationships. Depending on the SMS implementation, as actions are carried out on the SMS, batch files may accumulate an organisation’s requests for searches, additions, updates, and merge requests and the creation/updating of student relationships for the NSI system to perform. The batch file is sent by the organisation to the NSI system for processing by the NSI system. For each batch file processed by the NSI, a result file is generated that reports the outcome of batch file processing. This result file will be available for organisations to download and will then need to be loaded into the SMS. 2.8 What is the difference between the Web, REST and Batch Interfaces? The web interface is online and does not require systems integration. Organisations will access it using a browser in the same way that they access any other Internet web site. A go-live process is in place for training new providers before they can access the system. The REST interface is also an online method of connecting with the NSI, but will operate behind the scenes via the SMS. This means that systems which use this interface option can expect to send requests and receive responses from the NSI over the Internet, but the direct user interaction will be only with their SMS. In order for this interface to work, the organisation will need to be connected to the Internet, sending information and waiting for a response. The batch file interface option involves the accumulation of any NSI interaction into batches of requests to the NSI system, placing these requests into files and then transmitting them to the NSI for processing. The files returned from the NSI can then be uploaded into the SMS with any errors or exceptions being processed manually. Batch files and results can be uploaded and downloaded either via the NSI Web interface, or via an automated interface between an SMS and the NSI. Guide to National Student Index - GINS 6.5-final.docx Page 11 of 148 It should be noted that for functions available on multiple interfaces, the actions performed on the NSI system are the same, regardless of the interface method used. 2.9 What is the best NSI system interface option for you? The variety of interfaces means that a provider can utilise the method (or combination of methods) that fits best with their existing business processes. Most smaller organisations may use only the NSI web interface. However larger organisations may use more than one type of interface. For example, an organisation’s staff interacting with students may use the NSI web interface but the batch process may be used during peak enrolment periods to send and receive NSI data for that organisation’s students. 2.10 Integration Considerations The NSI system and processes have been designed to be as flexible as possible. This means that you can implement them in your own organisation in the way that best fits with your current practice. Depending on which interface(s) you decide to implement you should consider the following points: 1. How does the data in your SMS map to NSI data? (e.g. Family names in the NSI can be 100 letters in length which may differ from your SMS, and Given name(s) may not be stored in separate fields on your SMS which means they will need to be parsed before being passed to the NSI) 2. When you are searching for an NSN do you want to check your own SMS records first before making a call/request to the NSI system? This is recommended. 3. If using the batch interface, how will you manage the creation and purging of batch files? How will you manage the storage of inbound and outbound batch files? How will you manage the distribution of batch results to the originating requestor? 4. If you are using the REST interface, do you want to ask your developer to restrict the number of search results that are displayed to the users of your SMS? (the NSI will return up to 100 results per search request) 5. What changes, if any, are required to be made to your database? 6. How will you move data between your SMS and the NSI? 7. When you change student data on your SMS how will these changes be passed to the NSI (where relevant)? 8. When students re-enrol or change their details ‘in person’ do you want to print-off their NSI details and ask them to sign the printout? 9. What type of security do you wish to have in place when connecting with the NSI? Guide to National Student Index - GINS 6.5-final.docx Page 12 of 148 The following diagram sets out some of the key factors to consider when selecting the most appropriate interface(s) to use: It is suggested that the decision about which NSI interface(s) to use be made in consultation with your SMS vendor/developer. Guide to National Student Index - GINS 6.5-final.docx Page 13 of 148 2.11 What next? You will need to take the following steps to start using the NSI: Step 1: Contact MoE Service Desk Your organisation’s CEO or Head of IT or Academic Registrar (or equivalent) should contact the MoE Service Desk to make arrangements for your organisation to start using the NSI. Please note that if you are intending to implement the batch or an online interface that you will need to contact the MoE Service Desk at least three months before you want to start using the NSI system. Step 2: Determine Interface and Make System and/or Business Process Changes (if required) The information in section 2.9 will help you to determine the best interface or interfaces for your organisation. This decision will need to be made in conjunction with considering your student administration business processes, and liaison with your SMS supplier or in-house IT developer. Depending on the interface(s) you implement, changes may need to be made to your SMS or the way in which you manage students’ personal information. The specifications for the online and batch interfaces are set out in the following sections: Web Interface – refer to section 4 REST Interface – refer to section 5 Batch File Interface – refer to section 6 Before implementing any systems changes it is recommended that consideration be given to the points set out in section 2.10, and that a decision be made as to which staff within your organisation will use the NSI. Step 3: Perform Testing If you are using the REST or Batch interfaces then you will need to carry out testing prior to using the NSI. Your testing will need to include the sending of data or files. The MoE Service Desk will assist you through this process. If you are testing an integrated online interface you will also have to perform specific tests with the MoE Service Desk before being allowed live access to the system. Step 4: Data Load The final step in preparation before using the NSI is to load your existing records into the NSI system. This means that when you go live your students will already have NSI records. Again, the MoE Service Desk will help you with the data load to ensure that the process is successful. Guide to National Student Index - GINS 6.5-final.docx Page 14 of 148 Note that depending on the size of your organisation it may be preferable to begin the data load before step 3 (above) is completed. The data load process may take several weeks depending on the number of students you have. Step 5: Go Live Your organisation can start using the NSI system once the data load is finished, testing has been completed, and a date has been agreed with the MoE Service Desk. Guide to National Student Index - GINS 6.5-final.docx Page 15 of 148 3 NSI Functional Overview 3.1 Introduction This section details the functions available to organisations via any of the three NSI interface options. Where there is a difference in the way the function operates that arises because of the interface option used, it is mentioned in brief here and detailed later in the section relating to that option. All of the functions available for searching, adding or updating NSI records, or requesting a merge, require a predefined set of information to be passed to the NSI. Similarly, each of the functions will return a predefined set of information to the requestor. This information falls into one of two categories: mandatory or optional. The information which is passed to, and returned from, the NSI functions is identified in the detailed sections that follow. That which is mandatory is clearly indicated. 3.2 Unknown Birth date Where a student’s birth date is recorded in the NSI database as unknown, the REST and Web UI interfaces will return ‘Unknown’ to represent an unknown birth date. A birth date of 11/11/1918 will be returned in batch and other legacy outputs from the NSI to the providers representing an unknown birth date. When a birth date of 11/11/1918 is received by the NSI, it will be treated by the NSI as an unknown birth date. 3.3 Search The search facility is used to search for students in the NSI database. Searches can be performed using only the NSN (NSN search) or using a student’s name and other fields (Criteria search). It is highly recommended searches which do not include NSN, include the student’s full name (Family and Given name(s)) and Birth date. NSN search: Direct lookup. The result will always be an exact match with one NSI record, unless it does not exist or is invalid. Criteria search: This will search for the student by the following parameters: Student name (‘main’ name and ‘alternative’ names will be searched); there will be some allowance for variance in spelling of names and additional given names. Guide to National Student Index - GINS 6.5-final.docx Page 16 of 148 Birth date, it is highly recommended the birth date is included in a criteria search to increase the reliability of search results. There will be some allowance for ‘close’ birth dates (e.g. 01/10/1988 and 01/10/1989). The tilde symbol ‘~’ can be used in addition to one single name when the student has only one name. Each record returned in a search will be given a score to indicate the likelihood of match of the returned record. The score returned for each match is determined by the search software. The NSI Search software uses probabilistic matching which incorporates the following logic: Transposed birth dates Variations in spelling Phonetics, etc. For example, a search of the family name “Petersen” and Birth date “13/09/78” may return: Score NSI Name Date of Birth 086 Lyndon Neville Petersen 13/09/1978 079 Claire Elizabeth Peterson 13/09/1978 072 Kerrie Elizabeth Peterson 03/09/1978 If a record exists on the NSI database that exactly matches the search criteria entered, (name and birth date), then the results will be returned with a score of 100. Note that multiple records may be returned. For example: a search of Given name 1 “Lyndon”, Family name “Petersen” and Birth date “13/09/78” may return: Score NSI Name Date of Birth 100 Lyndon Neville Petersen 13/09/1978 100 Lyndon Petersen 13/09/1978 And a search of Given name 1 “Lyndon”, Given name 2 “Neville”, Family name “Petersen” and Birth date “13/09/78” would return: Score NSI Name Date of Birth 100 Lyndon Neville Petersen 13/09/1978 Guide to National Student Index - GINS 6.5-final.docx Page 17 of 148 It is also possible that you may get a single result returned that is not considered an Exact match, or a Definite match. For example, a search of Given name 1 “Neville”, Family name “Petersen” and Birth date “13/09/78” would return: Score NSI Name Date of Birth 85 Lyndon Neville Petersen 13/09/1978 Please note – Alternative name matches: When performing a search it is important to be able to display all names returned for a single NSI record. Alternative names as well as main names will be returned in the search results (where they match the criteria entered). A user must be able to accept an alternative name back into their SMS without having to perform a change to where the name sits on the NSI record. Why? The NSI is a means to identify a student and can hold multiple names for one student. Student records have a ‘main name’ and as many ‘alternative names’ as required. 3.4 Add / Insert The add facility is used to create new NSI records. Before adding a record a search must have been performed in order to confirm that the student being added does not already have a NSI record. REST and BATCH add requests automatically initiate the prerequisite search. When adding (inserting) a student into the NSI, it is recommended you provide verification of the data on the student record. For example, if you have sighted the student’s passport, you can pass in ‘P’ for Name & birth date verification and Residential status verification. Once a student records details have been verified, the data cannot be updated (see ‘Updating NSI records’ section for more information on updating existing NSI records) As well as verifying a student record, it is important to enter the name of the student as it appears on the verification document, as well as other student details you are verifying. When entering a name in the NSI, the name will be saved in exactly the same case as entered. For example if the name is entered as “John LaRose”, it will be saved in NSI as “John LaRose”. The NSI system will not change the case of “LaRose” to “Larose”. Alternatively if the name is entered as “jOhN”, it will be saved in NSI as “jOhN”. Guide to National Student Index - GINS 6.5-final.docx Page 18 of 148 Definite match - If a record already exists that the NSI considers a ‘Definite match’ (a search result which has a score high enough to be over the NSI determined threshold) a new student record cannot be added. The NSN of the ‘Definite match’ is returned to the user who can either use that NSI record, or if you know the student record matched is a different student to the one you are trying to add to the NSI, you can raise a challenge against the matched student and submit supporting information to the MoE Service Desk who can add the record for you. Possible match - If a record already exists that the NSI considers a ‘Possible match’ (a search result which has a score high enough to be over the NSI determined threshold for ‘Possible matches’ but not high enough to be considered a ‘Definite match’) a user must confirm the addition of the student record after reviewing the details of the ‘possible matches’. Through the Web Interface, this is achieved via a confirmation button, the BATCH interface and the REST service will provide the user with an override code which can be used to add the new record if the user is certain that they are dealing with a different student to the one which has been found on the NSI. The NSI will require this override code to be included in a subsequent request to add the record. No matching records - Where no matches are returned from the prerequisite search, the student record will be added and the new NSN will be returned to the user. The user ID, organisation code and date of creation are recorded with that record. 3.5 Update The update facility is used to update existing NSI records. Updating a record in the NSI requires that an NSN be provided to identify the record being changed. Updates will be initiated when, for example, a student changes their name or residential status. It is important to note that when entering a name in the NSI, the name will be saved in exactly the same case as entered. For example if the name is entered as “John LaRose”, it will be saved in NSI as “John LaRose”. The NSI system will not change the case of “LaRose” to “Larose”. Alternatively if the name is entered as “jOhN”, it will be saved in NSI as “jOhN”. Updating Birth Date of NSI Records Birth date can only be modified by users in the following scenarios: The user logged in is logged in as the provider organisation which created the student record within a certain time period (currently set at 90 days) before the modify date o In this case, if the Name & birth date verification has been either ‘Birth register’ verified, or verified by MoE, it cannot be modified. The birth date is ‘Unknown’ Guide to National Student Index - GINS 6.5-final.docx Page 19 of 148 Outside of these scenarios, birth date cannot be modified. If you believe the birth date on a student record is incorrect, you can raise a challenge to the MoE Service Desk with supporting documentation to get the birth date updated. Where a user attempts to update a birth date through the legacy interfaces (XML, SOAP, and Batch) and does not meet the rules to be able to do so, the NSI system will return error #305. Through the REST interface, the NSI system will return error #957. Verified NSI Records Users cannot update name and birth date information when it is verified on a student record (unless the birth date is being modified and it is in one of the scenarios given above). Residential status information can be modified unless it is verified by ‘Birth register’ or by MoE. Where an organisation has evidence that the verified details of a student are incorrect, a challenge can be raised on the web interface and supporting documentation can be forwarded to the MoE Service Desk who can update the record. Where an NSI record already has a verified name and a user wishes to add another name by which the student is known, whether verified or not, this name can be added as an alternative name. Error messages Where a user attempts to modify either name or birth date and it is verified, the following message will be returned. Where Name & birth date verification is any verification other than ‘Birth register’ and is not verified or verification is confirmed by MoE and a user is modifying name and/or Birth date and/or Name & birth date verification 274 Cannot modify verified data. Where Name & birth date verification is ‘Birth register’ and a user is modifying name and / or Birth date AND where Residential status verification is ‘Birth register’ and a user is modifying Residential status 369 BDM verified fields cannot be modified. Where Name & birth date verification is any verification other than ‘Birth register’ and is verified or verification is confirmed by MoE and a user is modifying name and / or Birth date AND where Residential status verification is verified or verification is confirmed by MoE and a user is modifying Residential status 290 Cannot change Ministry of Education verified data. Editable fields Guide to National Student Index - GINS 6.5-final.docx Page 20 of 148 The following table defines fields that are ‘Locked’ in each scenario when updating a student record. Primary name and Birth date fields. The top row specifies the value for ‘Name & birth date verification: ‘Birth Verified Verified (not Birth register’ by MoE register) ‘Unverified’ Primary name Locked Locked Locked Editable Birth date Locked Locked Locked (Unless user created the record – see ‘Update birth date’ rules.) Locked (unless user created the record or Birth date is ‘Unknown’ – see ‘Update birth date’ rules) Name & birth date verification Locked Locked Locked Editable Residential status. The top row specifies the value for ‘Residential status verification: ‘Birth Verified Verified (not Birth register’ by MoE register) ‘Unverified’ Residential status Locked Locked Editable Editable Residential status verification Locked Locked Editable Editable Other Student fields can be updated as follows: Editable fields Insert-able fields Gender Alternative name Preferred name indicator Alternative name verification (not ‘M’ – Birth register) Record status and Reason (MoE only) Date of Death (MoE only) Multiple Field Updates If the update request (where a valid NSN is supplied) includes any data that represents a change to locked data on a verified NSI record, even if it also contains changes to editable fields, it will result in an error. Guide to National Student Index - GINS 6.5-final.docx Page 21 of 148 In order to update editable fields, the request must either contain no information in the locked fields, or exactly the same information for the record being updated. This must be supplied in conjunction with the NSN and the updated data in the editable fields. Unverified NSI Records Where a student’s name can be updated (an unverified name), full name details should be supplied. For example, if a student exists as ‘Sarah Wallace’ on the NSI and you wish to update the information to ‘Sarah Jane Wallis’, all of the name fields must be supplied in the input files. When the ‘main name’ fields are updated, the original main name will be added as an alternative name for the student (where the names are not duplicates). Notification of updates Changes to an NSI record will be notified to all organisations recorded in the NSI system as having an active “Student-Provider relationship (SPR)” with the student, via the change notification facility (See 3.7 Change Notifications) 3.6 Merge Request Where an organisation believes there are multiple NSI records for one student, a request to merge the student records can be submitted to the NSI. There are three potential outcomes of a merge request: Merge approved: Where NSI determined criteria is met, the NSI records will be merged and the user will be notified of the single NSN to continue to use as the students NSN. Merge requires manual intervention: Where NSI determined criteria for merge approval are not met, the merge request will be lodged with the MoE Service desk to be considered and approved or declined as appropriate. (They may request supporting documentation to justify the Merge request, for example, a copy of a marriage certificate may be supplied to support a merge of records with two very different names). Merge rejected: Where the submitted records are not appropriate for a merge request (e.g. too many NSNs submitted, Invalid NSNs submitted) the merge request will be rejected. The user will need to rectify the error and re-submit the request. 3.7 Change Notifications The change notification facility communicates NSI student data changes to organisations that have requested to know about the changes. Where an organisation has requested to receive change notifications (arrange this via MoE Service Desk), they will be able to receive notification of changes to NSI records that are recorded as having a “Student-Provider relationship (SPR)” with that organisation. Guide to National Student Index - GINS 6.5-final.docx Page 22 of 148 Organisations can request Change notifications as often as required (change notifications will not automatically be sent to providers, they must be requested via the web or batch interface). When an organisation retrieves change notifications they can choose to either: Receive changes made to student records since the last date (and time) change notifications were generated (up to 12 months in the past) Through the web interface users can request to view changes made over a specified time period (not exceeding six months from date of request) Change notification files will be available for download from the NSI web interface or can be downloaded via the Batch Interface (this will require SMS integration). When the NSI is notified of a student’s death, all organisations with either a current or expired relationship with the student will be notified of the student’s death via the change notification process. 3.7.1 Changed Field Indicator The Change Notification files include a Changed Field indicator which allows the recipient to determine which fields have been changed. The Changed_field_indicator field will be populated using an integer number (which has an implied binary coded decimal nature) that is derived in the following way: Changed Field Decimal Value master_nsn 1 surname 2 forename1 4 forename2 8 forename3 16 gender 32 preferred_name_indicator 64 dob 128 dod 256 name_dob_verification 512 residential_status 1024 residential_status_verification 2048 nzqa_paid 4096 student_status 8192 Guide to National Student Index - GINS 6.5-final.docx Page 23 of 148 The “changed_field_indicator” will be set to the sum of the decimal values attributed to the fields changed allowing an organisation to determine the field(s) that have changed in each change notification record. NOTE: The ‘nzqa_paid’ field is a legacy field that is no longer stored in the NSI. It will never be updated. The flag will be returned in the results file to support applications that have been integrating with the NSI before the replacement application. The returned value will always be ‘U’ 3.8 Challenge A facility to challenge a change made to an NSI record is available on the NSI web interface. This may be used, for example, if two records have been merged and a user believes this to have been incorrect, or if the user believes that some verified information on a student record is incorrect. Using the Challenge function available on the Web interface (URL is: https://nsi.education.govt.nz/), search for the NSN, register a challenge, including the reason for the challenge. This will then be submitted to the MoE Service Desk for consideration. Supporting documentation can be emailed separately to the NSI team at nsi.unit@education.govt.nz 3.9 Create/Update Student Provider Relationships A Student-Provider Relationship (SPR) records the relationship between an organisation and an NSI record. The purpose of an SPR is to ensure organisations are notified of NSI record changes (see 3.7 Change Notifications section for more details) to student records which may impact them. The list of students ‘SPR’s’ is maintained within the NSI. When an NSI record is added or updated by an organisation, an SPR is created (or updated if it already exists) between the student and the organisation. The duration of an SPR for a student is determined by the ‘SPR duration’ for each provider. The SPR duration specifies how long a Student-Provider relationship will exist between the provider and student. The default period is 1 year, any alteration to this period may be advised to the MoE Service Desk. When the SPR duration between the organisation and that student is reached, the relationship will be marked as ‘expired’ but will not be deleted. This allows historical relationship information to be recorded. SPRs can be maintained through the REST and Batch Interfaces through the following services: REST: Create/update SPR Batch: ATA file upload. Guide to National Student Index - GINS 6.5-final.docx Page 24 of 148 SPRs may be maintained for the following reasons: A provider re enrols a student, but has no updates to make to the student’s details. Updating their SPR will ensure the provider receives Change Notifications about the student prior to the provider submitting their SDR information. A provider wishes to amend the default relationship period for a student. (Note if a different SPR duration is desired to be applied to all students for a provider it is recommended that the SPR duration for the provider is updated. This can be done by contacting MoE Service Desk.) Guide to National Student Index - GINS 6.5-final.docx Page 25 of 148 4 Web Interface 4.1 Overview The NSI web interface allows all of the NSI functions to be accessed over the Internet. Simply access the Ministry’s NSI web interface, (https://nsi.education.govt.nz/), login using your Education Sector Authentication (ESAA) login. The following functions will be available to you via the Web Interface: Student search Add Student View Student (including History) Modify a Student Request merges View Merge Request status Raise a Challenge View or download change notification result files Upload or download batch files as required Access reports Actions performed against the NSI database using the web interface are effected immediately, with users performing NSI-based actions interactively. Transferring data from your SMS to the NSI and back again will be a manual operation via the web interface. The web interface is not designed to be integrated with an SMS. The NSI web interface Uniform Resource Locator (URL) could be integrated with your SMS to make the linking from your system to the NSI as seamless as possible, although this is not required. You may also choose to have the NSI web interface URL recorded as a “favourite” in your web browser. The NSI web interface URL is: https://nsi.education.govt.nz/ Once you have launched a browser and have logged into the NSI web interface, the NSI functionality is there and ready to be used. The best place to learn more about how to use and navigate around the NSI web interface is the NSI Web Interface User Guide. See Appendix D for the link to this document. Guide to National Student Index - GINS 6.5-final.docx Page 26 of 148 The following browser versions were supported by the Ministry at the time this document was written1 : Browser Internet Version Internet Explorer Version 8.0-10.0 Firefox Current Version (mid 2014) Chrome Current Version (mid 2014) In order to use the site successfully, browsers will need to be JavaScript enabled. 4.2 Security and Authentication When entering the web interface, you will be prompted to enter your user name and password. The MoE Service Desk must have established this for you in order for you to gain access. If you require this to be set up for you, please either contact the MoE Service Desk (0800 422 599 or email service.desk@education.govt.nz) Any NSI session will time out after 20 minutes of inactivity. Users will be required to log into NSI again in order to continue using the functionality. The 20 minutes starts from when the session token is issued and is reset each time there activity against the NSI database. 1 Here supported means that the browser or operating system has been tested and is known to enable the core functionality of the NSI system. Guide to National Student Index - GINS 6.5-final.docx Page 27 of 148 5 REST Interface This section explains the necessary requirements to enable your application to integrate with the National Student Index (NSI) system using the REST interface and the NSI functionality available through REST. 5.1 What is REST? REST (REpresentation State Transfer) is a common standard for online interfaces. It uses a definition of a resource (e.g. a student), and allows a range of actions for it. The HTTP protocol is leveraged to communicate more clearly: Different HTTP verbs are used (GET, PUT (update), POST (create), etc) HTTP response codes help differentiate success, security checking and validation responses. The URL helps describe which resource is being accessed (e.g. /student/13), HTTP headers are used to transmit auxiliary information not part of the resource e.g.: The security token. 5.2 Accessing the API Base URL for all API queries: https://{site URL}/API/{version}/ Key notes: The REST API will be versioned. This document describes ‘v1’. This allows for future versions, while maintaining backwards compatibility with v1. The API must be accessed over SSL Environment URLs for production and compliance are: o Production: https://nsi.education.govt.nz/api/V1 o Compliance: https://nsi.compliance.education.govt.nz/api/V1 Example template for detailed queries: Base URL: https://{site URL}/API/{version}/{resource}/[{params}] NSI Authentication token in the header for all operations, bar Login {params} to identify current resource (retrieve (GET) operations) HTTP-Body properties for appropriate HTTP verbs (PUT, POST) Guide to National Student Index - GINS 6.5-final.docx Page 28 of 148 5.3 Authentication – ESAA OAuth Authentication to the NSI REST interface involves MoE’s ESAA single sign-on (SSO) platform. To login to the NSI system, you are required to have signed in with the ESAA SSO, and have retrieved a valid ESAA token. Logging into the NSI system will return an NSI auth token, which will be required for all subsequent NSI API calls. This NSI token will be supplied in the HTTP header – not part of the main body payload. See Appendix E for REST code examples. Diagram – NSI Login sequence: Guide to National Student Index - GINS 6.5-final.docx Page 29 of 148 5.3.1 ESAA Environment URLS Environment URLs for production and compliance are: o Production: https://security.education.govt.nz/ o Compliance: https://ppsecurity.education.govt.nz/ All requests (with the exception of login) require a valid NSI auth token, and will return the standard HTTP response codes if the token is invalid: 401 – Unauthorized o The NSI token supplied is not valid 403 – Forbidden o The current user is not authorized to perform that given action 5.3.2 Privilege levels ESAA provides users with one of the following levels of access: Student search only Access to all API calls described in this document 5.3.3 Authentication and Authorisation Errors The following messages will be returned where Authentication / authorisation has failed: Trigger HTTP Code Response Session token not supplied 401 Session token invalid / expired 401 User does not have permission to access the function (i.e. User does not have permissions to update a student) 403 5.4 API details 5.4.1 Naming standard MoE has chosen title case as its naming standard for entities and resource names. This simply means that ‘names’ all start with a capital letter. E.g.: A hypothetical example: { “FamilyName”: <family name>, "Given1Name” : <given name (1)>, Guide to National Student Index - GINS 6.5-final.docx Page 30 of 148 "BirthDate": <birth date>, "NameBirthDateVerification: <name & birth date verification> } 5.4.2 Dates Dates use the UTC format: yyyy-MM-ddTHH:mm:ss E.g.: 2013-11-28T14:35:24 5.4.3 JSON NSI REST API will use JSON formatting. Example request & response objects in this document are given as JSON. HTTP headers for JSON: Content-Type: application/json Accept: application/json 5.4.4 Encoding The NSI REST results will be UTF-8 encoded. Diacritics and special characters (other than ‘~’ for Given name 1) will not be accepted by the NSI system. Where diacritics are submitted to the NSI, the following error message will be returned Error code Description 272 {0} must only contain alphabetic characters, space, hyphen, apostrophe or a single '~'. Space hyphen and apostrophe cannot be used without another character or repeated. Names must start with an apostrophe or an alphabetic character.). 5.4.5 Query string parameter encoding Arguments passed in the query string must be URL encoded. e.g.: In the example below, the spaces are encoded to ‘%20’. And the characters ‘?’, ‘=’ and ‘&’ are part of the standard query string syntax, so remain: /student/?FamilyName=Van%20Der%20Name&Given1Name=Person Guide to National Student Index - GINS 6.5-final.docx Page 31 of 148 5.5 Result codes and messages All result codes and descriptions will be passed back to interfacing systems as an array, allowing a single or multiple errors to be returned to a user if required. Client applications may perform business logic based on specific error code IDs, but the content of the error code message may change over time. Parsing text from the message content is not supported/recommended. The result codes and descriptions will be returned in the following format: { “MessageList”: [ { “MessageCode”: <error/info code1>, “MessageDescription”: <error/info description1> } ] } Where there are multiple validation errors resulting from a particular input request, they will all be returned to the interfacing system in the format below. { “MessageList”: [ { “MessageCode”: <error/info code1>, “MessageDescription”: <error/info description1> }, { “MessageCode”: <error/info code2>, “MessageDescription”: <error/info description2> } ] } Field Definitions Label / Field Type/Length Description MessageCode Alphanumeric (10) Relevant NSI message code MessageDescription Alphanumeric (300) Guide to National Student Index - GINS 6.5-final.docx Relevant NSI message description Page 32 of 148 5.6 REST API Resources The NSI system will provide the following resources to interfacing systems. This section defines the fields and structure of each resource. This information is referenced within the specific function details to avoid replication. 5.6.1 Session Resource Available operations: Operation REST Verb Resource URL Create NSI Session POST session/ Logout DELETE session/ 5.6.2 Student Functions Available operations: Operation REST Verb Resource URL Search GET Student/<NSN> Search GET Student/<Search params> AddStudent POST Student/ ModifyStudent PUT Student/ 5.6.3 The student resource The following student resource is used in all Student operations. Some fields are read-only, and will only be present on a Student GET. For Add and Modify, the submit fields are specified under the ‘Inputs’ section for each function, for clarity. Resource Response Body (JSON) Student { "NSN" : <nsn>, “FamilyName” : <family name>, "Given1Name" : <given name (1)>, "Given2Name" : <given name (2)>, "Given3Name" : <given name (3)>, "PreferredName": <preferred name>, "Gender": <gender>, "BirthDate": <birth date>, "NameBirthDateVerification": <name birth date verification>, "NameBirthDateVerifiedBy": <name birth date verified by>, Guide to National Student Index - GINS 6.5-final.docx Page 33 of 148 Resource Response Body (JSON) "NameBirthDateVerifiedDate": <name birth date verified date>, "NameBirthDateVerificationConfirmedByMoe": <verification confirmed by moe (name & birth date verification)>, "ResidentialStatus": <residential status>, "ResidentialStatusVerification": <residential status verification>, "ResidentialStatusVerifiedBy": <residential status verified by>, "ResidentialStatusVerifiedDate": <residential status verified date>, "ResidentialStatusVerificationConfirmedByMoe": <verification confirmed by moe (residential status verification)>, "DeathDate": <date of death>, "RecordStatus": <record status>, "RecordStatusReason": <record status reason>, "CreatedDate": <created date>, "CreatedByUserId": <created by userid>, "CreatedByProviderCode": <created by provider code>, "MatchScore": <score>, "MatchIndicator": <match indicator>, "AltNameList": [AltName – See separate definition] } Alt Name definition: AltName { "AltFamilyName": <alternative family name>, "AltGiven1Name": <alternative given name (1)>, "AltGiven2Name": <alternative given name (2)>, "AltGiven3Name": <alternative given name (3)>, "PreferredName": <alternative preferred name indicator>, "AltNameBirthDateVerification": <alternative name birth date verification> } Field definitions: Field Type/Length Description NSN Numeric (10) The NSN of the record. Guide to National Student Index - GINS 6.5-final.docx Page 34 of 148 Field Type/Length Description FamilyName Alphanumeric (100) The surname of the student found. Given1Name Alphanumeric (100) The first given name of the student found. Given2Name Alphanumeric (100) The second given name of the student found. Given3Name Alphanumeric (100) The third given name of the student found. PreferredName Boolean Indicates whether or not this name is set as the preferred name for the student. Values can be: true false Gender Alphanumeric (1) The gender of the student. Values can be: Male (M) Female (F) Unknown (U) BirthDate Alphanumeric (20) The birth date of the student. Values can be: Date eg. 1980-12-09 ‘Unknown’ When a date is entered, format must meet the following format: Format: yyyy-MM-dd e.g. 201311-31 NameBirthDateVer Alphanumeric (1) ification The verification method used to verify the name and birth date. Values can be: Unverified (U) Passport (P) Birth certificate (B) Birth register (M) Other (O) NameBirthDateVer Alphanumeric (10) ifiedBy Read-only The provider code of the provider that verified the name and birth date data. Guide to National Student Index - GINS 6.5-final.docx Page 35 of 148 Field Type/Length Description NameBirthDateVer Date/Time (20) ifiedDate Read-only The date and time the Name & birth date verification was set for the student record Format: yyyy-MMddTHH:mm:ss.mss e.g. 2013-11-28T14:35:24.001 NameBirthDateVer Boolean ificationConfirmed Read-only ByMoe Indicates whether the Name & birth date verification for the student record has been verified by the Ministry of Education. Values can be: true false ResidentialStatus Alphanumeric (1) The residential status of the student. Values can be: NZ Citizen (C) NZ Permanent resident (P) Australian citizen (A) Overseas (O) Unknown (U) ResidentialStatus Verification Alphanumeric (1) The method used to verify the residential status. Values can be: Unverified (U) Passport (P) Birth certificate (B) Birth Register (M) Other (O) ResidentialStatus VerifiedBy Alphanumeric (10) Read-only The provider code of the provider that verified the Residential status. ResidentialStatus VerifiedDate Date/Time (20) Read-only The date and time the Residential status verification was set for the student record Format:“yyyy-MMddTHH:mm:ss.mss” e.g. “201311-28T14:35:24.001” Guide to National Student Index - GINS 6.5-final.docx Page 36 of 148 Field Type/Length Description ResidentialStatus VerificationConfir medByMoe Boolean Read-only Indicates whether the Residential status verification for the student record has been verified by the Ministry of Education Values can be: true false DeathDate Date/Time (20) Read-only The date of death of the student. Format: yyyy-MM-dd e.g.201311-28 RecordStatus Alphanumeric (1) Read-only The status of the record. Values can be: Active (A) Inactive (I) RecordStatusReas Alphanumeric (100) on Read-only Description of record status. Values can be: In Use Deceased Created in error Do not use CreatedDate Date/Time (20) Read-only The date and time the record was created. Format:“yyyy-MM-ddTHH:mm:ss” e.g.“2013-11-28T14:35:24” CreatedByUserId Alphanumeric (200) Read-only The User ID of the user that created the record. CreatedByProvide rCode Alphanumeric (10) Read-only The associated provider code of the user that created the record See “Field Definitions – Alt Name” AltNameList The following are only displayed for student search (including ‘Add’ prerequisite search): MatchScore Numeric (10) Read-only Guide to National Student Index - GINS 6.5-final.docx The match score attributed to the returned record. Where the search was an NSN search, score returned will be 100 Only returned for SEARCH and ADD student. Page 37 of 148 Field Type/Length Description MatchIndicator Numeric (10) Read-only Which name on the record contained the match 0 = Primary name of master record AltNameId‘ = 0 and Master NSN = NSN 2 = Alternate name of master record AltNameId‘ > 0 and Master NSN = NSN Only returned for SEARCH and ADD student. Field definitions – Alt Name Field Type/Length Description AltFamilyName Alphanumeric (100) The alternative family name of the student. AltGiven1Name Alphanumeric (100) The alternative first given name of the student. AltGiven2Name Alphanumeric (100) The alternative second given name of the student. AltGiven3Name Alphanumeric (100) The alternative third given name of the student. PreferredName Boolean Indicates whether or not this name is set as the preferred name of the student. Values can be: true false AltNameBirthDate Verification Alphanumeric (1) The method used to verify the Name and Birth date for the alternative name. Values can be: Unverified (U) Passport (P) Birth certificate (B) Birth register (M) Other (O) Guide to National Student Index - GINS 6.5-final.docx Page 38 of 148 Other fields returned / submitted: Field Type/Length Description NSISessionToke n Alphanumeric (36) Session token to be used in subsequent calls. OrgID Alphanumeric (10) Organisation ID of User logging in OverrideCode Numeric (10) NSN + 1 If returned then the process has determined that there is at least one student already in the database that could possibly match the criteria to be inserted. ProviderCode Alphanumeric (10) The provider code of the provider that the NSI record will have a relationship with (when creating a SPR) ActiveUntilDate Date/Time (20) Date student provider relationship will expire Format: yyyy-MM-dd e.g. 201311-28 ESAAAccessTok en <Defined by ESAA – not an NSI field> ESAA Access Token as retrieved from OAuth. Guide to National Student Index - GINS 6.5-final.docx Page 39 of 148 5.7 REST Function Details The following sections specify the requirements for each function available for the REST interface. 5.7.1 Create NSI Session via REST This function creates a session with the NSI system by logging the user in. This function will be used to ensure that the user performing the call has the necessary security privileges set and stored within ESAA. In order to gain access to the NSI, users will submit a login request to ESAA, which will contain their username and password. Refer to the REST code example for details on how to login to ESAA. Once the login to ESAA has been successful, ESAA will return an ESAA access token to the user which is then passed through to the NSI system in the below Create NSI Session request. Once the NSI system receives this ESAA access token, NSI will validate that the token is valid before returning an NSI session token, which is then used in subsequent calls to the NSI system. Guide to National Student Index gins Page 40 of 148 5.7.1.1 Create NSI Session Function - Inputs 5.7.1.1.1 Input Function Syntax Operation REST Verb Resource URL Header payload Body Payload (JSON) Create NSI Session POST session/ Content-Type { ”ESAAAccessToken” : <esaa access token>, “OrgID” : <orgid> } 5.7.1.1.2 Input Data Fields Field Type/Length Content-Type Description Requirement Indicates the "type" associated with the message body's byte sequence. Must read “application/json” Mandatory Message #789 ESAAAcessToken <Defined by ESAA – not ESAA Access Token as retrieved from OAuth. an NSI field> Mandatory Message #257 Message #513 OrgID Alphanumeric (10) Mandatory Message #257 Message #339 Guide to National Student Index - GINS 6.5-final.docx Organisation ID of User logging in Page 41 of 148 5.7.1.2 Create NSI Session Function – Outputs 5.7.1.2.1 Output Function Syntax The following table explains the returned HTTP response message passed over the HTTPS medium for each Create NSI Session request and the relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP response code and if required, a JSON message which will include the NSI error message code and descriptions. Operation Status HTTP Code Response Response Header Response Body (JSON) Create NSI Session Successful login 200 NSISessionToken <none> Not authenticated 401 Result message details – section 5.5 Message #513 Not authorised 403 Result message details – section 5.5 Message #515 Message #521 Bad request 400 Result message details – section 5.5 Message #257 Message #339 Message #1283 Bad syntax 500 Result message details – section 5.5 Message #789 Guide to National Student Index - GINS 6.5-final.docx Page 42 of 148 Message 5.7.2 Search Request via REST There are two types of search requests that can be performed: 1. NSN search – Where an NSN is provided 2. Match search – Where an NSN is not provided but other information is provided to search the NSI system 5.7.2.1 Search Function – Inputs 5.7.2.1.1 Input Data Syntax (NSN Search) Operation REST Verb Resource URL Header payload Body Payload (JSON) Search GET Student/<NSN> NSISessionToken <none> 5.7.2.1.2 Input Data Fields (NSN Search) Field Type/Length Description Requirement NSISessionToken Alphanumeric (36) Session token returned from previous Login Call Mandatory Message #257 Message #528 NSN Numeric (10) The NSN of the student to search for. Mandatory Message #257 Guide to National Student Index - GINS 6.5-final.docx Page 43 of 148 5.7.2.1.3 Input Data Syntax (Match Search) Operation REST Verb Resource URL Header payload Query string parameters Search GET Student/<params> NSISessionToken “FamilyName”=<family name>, "Given1Name"=<given name (1)>, "Given2Name"=<given name (2)>, "Given3Name"=<given name (3)>, “BirthDate”=<birth date> E.g.: ?FamilyName=Smith&Given1Name=Joe 5.7.2.1.4 Input Data Fields (Match Search) Field Type/Length Description Requirement NSISessionToken Alphanumeric (36) NSI Session token returned from previous Login Call Mandatory Message #257 Message #258 FamilyName Alphanumeric (100) The surname of the student to be searched for. Mandatory Message #257 Message #272 Given1Name Alphanumeric (100) The first given name of the student to be searched for. Mandatory Message #257 Message #272 Guide to National Student Index - GINS 6.5-final.docx Page 44 of 148 Field Type/Length Description Requirement Given2Name Alphanumeric (100) The second given name of the student to be searched for. Conditionally mandatory if Given name (3) provided Message #257 Message #272 Given3Name Alphanumeric (100) The third given name of the student to be searched for. Optional. Message #272 BirthDate Alphanumeric (20) The birth date of the student. Values can be: Date eg. 1980-12-09 ‘Unknown’ Optional, but can only be used if name is submitted Message #304 Message #305 Message #945 Message #951 When a date is entered, format must meet the following format: yyyy-MM-dd e.g. 2013-11-31 Guide to National Student Index - GINS 6.5-final.docx Page 45 of 148 5.7.2.2 Search Function – Outputs The following tables explain the returned HTTP response message passed over the HTTPS medium for each search request and the relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP response code and if required, a JSON message which will include the NSI error message code and descriptions. 5.7.2.2.1 Matched records 5.7.2.2.1.1 Output Function Syntax For each matched record found the following fields will be returned. NOTE: The matched name will be returned for each matched student record including the AltName List if relevant and if only one NSN was returned.: Operation Status Search Successful – match found HTTP Code Response Response Header Response Body (JSON) 200 NSISessionToken { “Students” : [ {Student Resource – section 5.6.3} ], “MessageList” : [NULL] } Guide to National Student Index - GINS 6.5-final.docx Page 46 of 148 Message Operation Status Search Successful – more than 100 matches found HTTP Code Response Response Header Response Body (JSON) Message 200 NSISessionToken { Message #784 “Students” : [ {Student Resource – section 5.6.3} ], “MessageList” : [ {Result message details – section 5.5} ] } Guide to National Student Index - GINS 6.5-final.docx Page 47 of 148 5.7.2.2.2 Errors 5.7.2.2.2.1 Output Function Syntax If no records are found an error message will be returned (No matches found) If there is an error with the submitted search criteria, an error message will be returned (Bad request) Operation Status HTTP Code Response Response Header Response Body (JSON) Message Search No matches found 200 NSISessionToken { Message #785 “Students” : [NULL], “MessageList” : [ {Result message details – section 5.5} ] } Bad request 400 NSISessionToken { “Students” : [NULL], “MessageList” : [ {Result message details – section 5.5} ] } Guide to National Student Index - GINS 6.5-final.docx Page 48 of 148 Message #012 Message #257 Message #272 Message #304 Message #305 Message #337 Message #945 Message #951 Operation Status HTTP Code Response Response Header Response Body (JSON) Message Not Authorised 401 NSISessionToken { Message #257 Message #528 “Students” : [NULL], “MessageList” : [ {Result message details – section 5.5} ] } Guide to National Student Index - GINS 6.5-final.docx Page 49 of 148 5.7.3 Add Student Record via REST The NSI System will search the NSI using the information supplied in the Add Request. Depending on whether matches are found above the Add Definite Match Threshold a new record will be added or an override code returned. 5.7.3.1 Add Student Record Function – Inputs 5.7.3.1.1 Input Data Syntax Operation REST Verb Resource URL Header payload Body Payload (JSON) AddStudent POST Student/ Content-Type NSISessionToken { Optional: ?OverrideCode= <override code> Guide to National Student Index - GINS 6.5-final.docx "FamilyName": <family name>, "Given1Name": <given name (1)>, "Given2Name": <given name (2)>, "Given3Name": <given name (3)>, "PreferredName": <preferred name>, "Gender": <gender>, "BirthDate": <birth date>, "NameBirthDateVerification": <name birth date verification>, "ResidentialStatus": <residential status>, "ResidentialStatusVerification": <residential status verification>, "AltNameList": [ { "AltFamilyName": <alternative family name>, "AltGiven1Name": <alternative given name (1)>, "AltGiven2Name": <alternative given name (2)>, Page 50 of 148 Operation REST Verb Resource URL Header payload Body Payload (JSON) "AltGiven3Name": <alternative given name (3)>, "PreferredName": <alternative preferred name indicator>, "AltNameBirthDateVerification": <alternative name birth date verification> } ] } 5.7.3.1.2 Input Data Fields Field Type/Length Content-Type Description Requirement Indicates the "type" associated with the message body's byte sequence. Must read “application/json” Mandatory Message #789 NSISessionToken Alphanumeric (36) Session token returned from previous Login Call. Mandatory Message #257 Message #528 FamilyName Alphanumeric (100) The family name of the student. Mandatory Message #257 Message #272 Given1Name Alphanumeric (100) The first given name of the student. Mandatory Message #257 Message #272 Guide to National Student Index - GINS 6.5-final.docx Page 51 of 148 Field Type/Length Description Requirement Given2Name Alphanumeric (100) The second given name of the student. Conditionally mandatory if Given name (3) provided Message #257 Message #272 Given3Name Alphanumeric (100) The third given name of the student. Optional Message #272 PreferredName Boolean Value specifying that this name is the preferred name. Values can be: true false Mandatory Message #257 Message #409 Gender Alphanumeric (1) The gender of the student. Values can be: Male (M) Female (F) Unknown (U) Mandatory Message #257 Message #288 BirthDate Alphanumeric (20) The birth date of the student. Values can be: Date eg. 1980-12-09 ‘Unknown’ Mandatory Message #257 Message #304 Message #305 Message #945 Message #951 When a date is entered, format must meet the following format: Format: yyyy-MM-dd e.g. 2013-11-31 Guide to National Student Index - GINS 6.5-final.docx Page 52 of 148 Field Type/Length Description Requirement NameBirthDateVerific ation Alphanumeric (1) The verification method used to verify the name and birth date. Values can be: Unverified (U) Passport (P) Birth certificate (B) Other (O) Mandatory Message #257 Message #275 ResidentialStatus Alphanumeric (1) The residential status. Values can be: NZ Citizen (C) NZ Permanent resident (P) Australian citizen (A) Overseas (O) Unknown (U) Mandatory Message #257 Message #309 ResidentialStatusVeri fication Alphanumeric (1) The verification method used to verify the residential status. Values can be: Unverified (U) Passport (P) Birth cert (B) Other (O) Mandatory Message #257 Message #409 AltFamilyName Alphanumeric (100) The alternative family name for the student. Conditionally Mandatory if Alternative given name (1) is supplied Message #257 Message #272 Guide to National Student Index - GINS 6.5-final.docx Page 53 of 148 Field Type/Length Description Requirement AltGiven1Name Alphanumeric (100) The alternative first given name for the student. Conditionally Mandatory if Alternative family or Alternative given name (2) is supplied Message #257 Message #272 AltGiven2Name Alphanumeric (100) The alternative second given name for the student. Conditionally Mandatory if Alternative given name (3) is supplied Message #257 Message #272 AltGiven3Name Alphanumeric (100) The alternative third given name for the student. Optional Message #272 PreferredName Boolean Value specifying that this name is the preferred name. Values can be: true false Conditionally Mandatory. if Alternative family name is supplied Message #257 Message #409 Guide to National Student Index - GINS 6.5-final.docx Page 54 of 148 Field Type/Length Description Requirement AltNameBirthDateVer ification Alphanumeric (1) The verification method used to verify the name and birth date. Values can be: Unverified (U) Passport (P) Birth certificate (B) Other (O) Conditionally Mandatory. if Alternative family name is supplied Message #257 Message #275 OverrideCode Numeric (10) Indicates that the record should be added despite the known existence of a possible matching record already in the NSI database. The value will be the same as that returned by the previous attempt to add a record. Optional Message #942 Guide to National Student Index - GINS 6.5-final.docx Page 55 of 148 5.7.3.2 Add Student Record Function – Outputs There are four different outputs, depending on the outcome of the add request. Successful addition Close/Possible match found (override code returned) - A possible match is when a record is found that matches the details entered as part of the add request, and the matching record has a score between the Possible match threshold and the Add Definite match threshold. Definite/Exact match found (record not added) – A definite match is when a record is found that matches the details entered as part of the add request, and the matching records has a score higher than the Add Definite match threshold. The matching record will be returned with an error message and error description. Error code and description. If there are any issues with the input, an error message and description will be returned back to the user. The following tables explain the returned HTTP response message passed over the HTTPS medium for each add request and the relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP response code and if required, a JSON message which will include the NSI error message code and descriptions. Guide to National Student Index - GINS 6.5-final.docx Page 56 of 148 5.7.3.2.1 Successful Addition of a student record Where a record has been added successfully, the fields returned are as follows: 5.7.3.2.1.1 Output Function Syntax Operation Status HTTP Code Response Response Header Response Body (JSON) Message Add Successful 200 NSISessionToken { Message #025 Message #939 Message #941 “NSN”: <NSN>, “MessageList” : [ {Result message details – section 5.5} ] } Guide to National Student Index - GINS 6.5-final.docx Page 57 of 148 5.7.3.2.2 Possible Match found and Override Code returned An override code is generated when a record with a score between the Add Possible match threshold and the Add Definite match threshold is found, and then returned with the most closely matched NSN(s). If an override code is returned then the user must check whether the student details they hold match the NSN(s) returned. If the results are a match, the user should use the returned NSN in their system. If they are certain the NSN does not match their student’s details, they must submit the Add Student Record request again, this time supplying the override code returned by the previous call. An override code is calculated by adding 1 to the NSN of the closest matched record. For example: If the add request finds a possible match on NSN 11, the override code returned will be 12. 5.7.3.2.2.1 Output Function Syntax Operation Status HTTP Code Response Response Header Response Body (JSON) Message Add Conflict 409 NSISessionToken { Message #021 Message #942 “OverrideCode” : <override code>, “PossibleMatches”: [ {Student resource – see section 5.6.3} ], “DefiniteMatchNSN”: null, “MessageList”: [ {Result message details – see section 5.5} ] } Guide to National Student Index - GINS 6.5-final.docx Page 58 of 148 5.7.3.2.3 Definite/exact match found When a record is found that has a score above the Add Definite match threshold, the system will return the NSN of the record with the highest score above the Add Definite match threshold 5.7.3.2.3.1 Output Function Syntax Operation Status HTTP Code Response Response Header Response Body (JSON) Message Add Conflict 409 NSISessionToken { Message #921 “OverrideCode” : null, “PossibleMatches”: null, “DefiniteMatchNSN”: <NSN>, “MessageList”: [ {Result message details – see section 5.5} ] } Guide to National Student Index - GINS 6.5-final.docx Page 59 of 148 5.7.3.2.4 Errors 5.7.3.2.4.1 Output Function Syntax Operation Status HTTP Code Response Response Header Response Body (JSON) Message Add Bad request 400 NSISessionToken Result message details – section 5.5 Message #023 Message #027 Message #257 Message #272 Message #275 Message #276 Message #288 Message #304 Message #305 Message #321 Message #409 Message #945 Message #951 Unauthorised 401 NSISessionToken Result message details – see section 5.5 Message #257 Message #528 Forbidden 403 NSISessionToken Result message details – see section 5.5 Message #529 Bad syntax 500 NSISessionToken Result message details – see section 5.5 Message #789 Guide to National Student Index - GINS 6.5-final.docx Page 60 of 148 5.7.4 Modify Student Record via REST The NSI System will search the NSI for the NSN supplied in the modify request. Provided all validation is passed the NSI System will then modify the NSN record using the supplied information in the request. This web service is used to modify records already on the NSI system. The NSN is provided along with the data to be modified. 5.7.4.1 Modify Student Record Function – Inputs When a Modify request is submitted through the REST interface, only the fields that the user wishes to modify are required to be submitted to the NSI system, along with the mandatory fields. The input fields for the modify request are detailed below. 5.7.4.1.1 Input Data Syntax Operation REST Verb Resource URL Header payload Body Payload (JSON) Modify PUT Student/ Content-Type NSISessionToken { Guide to National Student Index - GINS 6.5-final.docx “NSN”: <nsn>, "FamilyName": <family name>, "Given1Name": <given name (1)>, "Given2Name": <given name (2)>, "Given3Name": <given name (3)>, "PreferredName": <preferred name>, "Gender": <gender>, "BirthDate": <birth date>, "NameBirthDateVerification": <name birth date verification>, "ResidentialStatus": <residential status>, "ResidentialStatusVerification": <residential status verification>, Page 61 of 148 Operation REST Verb Resource URL Header payload Body Payload (JSON) "AltNameList": [ { "AltFamilyName": <alternative family name>, "AltGiven1Name": <alternative given name (1)>, "AltGiven2Name": <alternative given name (2)>, "AltGiven3Name": <alternative given name (3)>, "PreferredName": <alternative preferred name indicator>, "AltNameBirthDateVerification": <alternative name birth date verification> } ] } 5.7.4.1.2 Input Data Fields Field Type/Length Content-Type NSISessionToken Alphanumeric (36) Guide to National Student Index - GINS 6.5-final.docx Description Requirement Indicates the "type" associated with the message body's byte sequence. Must read “application/json” Mandatory Message #789 Session token returned from previous Login Call. Mandatory Message #257 Message #528 Page 62 of 148 Field Type/Length Description Requirement NSN Numeric (10) The NSN of the student to modify. Mandatory Message #257 Message #409 FamilyName Alphanumeric (100) The family name of the student. Optional Message #257 Message #272 Given1Name Alphanumeric (100) The first given name of the student. Optional Message #257 Message #272 Given2Name Alphanumeric (100) The second given name of the student. Optional Message #257 Message #272 Given3Name Alphanumeric (100) The third given name of the student. Optional Message #272 PreferredName Boolean Value specifying that this name is the preferred name. Values can be: true false Optional Message #409 Gender Alphanumeric (1) The gender of the student. Values can be: Male (M) Female (F) Unknown (U) Optional Message #288 Guide to National Student Index - GINS 6.5-final.docx Page 63 of 148 Field Type/Length Description Requirement BirthDate Alphanumeric (20) The birth date of the student. Values can be: Date eg. 1980-12-09 ‘Unknown’ When a date is entered, format must meet the following format: yyyy-MM-dd e.g. 2013-11-31 Optional Message #304 Message #305 Message #945 Message #951 NameBirthDateVerific ation Alphanumeric (1) The verification method used to verify the name and birth date. Values can be: Unverified (U) Passport (P) Birth certificate (B) Other (O) Optional Message #275 ResidentialStatus Alphanumeric (1) The residential status. Values can be: NZ Citizen (C) NZ Permanent resident (P) Australian citizen (A) Overseas (O) Unknown (U) Optional Message #309 ResidentialStatusVeri fication Alphanumeric (1) The residential status verification. Values can be: Unverified (U) Passport (P) Birth cert (B) Other (O) Optional Message #409 Guide to National Student Index - GINS 6.5-final.docx Page 64 of 148 Field Type/Length Description Requirement AltFamilyName Alphanumeric (100) The alternative family name for the student. Conditionally Mandatory if Alternative given name (1) provided Message #257 Message #272 AltGiven1Name Alphanumeric (100) The alternative first given name for the student. Conditionally Mandatory if Alternative family name or Alternative given name (2) provided Message #257 Message #272 AltGiven2Name Alphanumeric (100) The alternative second given name for the student. Conditionally Mandatory if Alternative given name (3) provided Message #257 Message #272 AltGiven3Name Alphanumeric (100) The alternative third given name for the student. Optional Message #272 Guide to National Student Index - GINS 6.5-final.docx Page 65 of 148 Field Type/Length Description Requirement PreferredName Boolean Value specifying that this name is the preferred name. Values can be: true false Conditionally Mandatory if Alternative family name is supplied Message #257 Message #409 AltNameBirthDateVer ification Alphanumeric (1) The verification method used to verify the name. Values can be: Unverified (U) Passport (P) Birth certificate (B) Other (O) Conditionally Mandatory if Alternative family name is supplied Message #257 Message #275 * If alternative name information is included this will be treated as an addition of a new alternative name. Guide to National Student Index - GINS 6.5-final.docx Page 66 of 148 5.7.4.2 Modify Student Record Function – Outputs There are two different outputs, depending on the outcome of the modify request. 1. Successful modification 2. Unsuccessful modification The following tables explain the returned HTTP response message passed over the HTTPS medium for each modify request and the relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP response code and if required, a JSON message which will include the NSI error message code and descriptions. 5.7.4.2.1 Successful modification Where a record has been modified successfully, the fields returned are as follows: 5.7.4.2.1.1 Output Function Syntax Operation Status HTTP Code Response Response Header Response Body (JSON) Message Modify Successful 200 NSISessionToken { Message #025 Message #938 Message #939 Message #941 Message #943 Student resource – Section 5.6.3, “MessageList” : [ {Result message details – section 5.5} ] } Guide to National Student Index - GINS 6.5-final.docx Page 67 of 148 5.7.4.2.2 Unsuccessful modification 5.7.4.2.2.1 Output Function Syntax Where a record has been modified unsuccessfully, the fields returned are as follows: Operation Status HTTP Code Response Response Header Response Body (JSON) Message Modify Bad request 400 NSISessionToken Result message details – section 5.5 Message #023 Message #027 Message #034 Message #257 Message #272 Message #275 Message #276 Message #277 Message #279 Message #288 Message #290 Message #304 Message #305 Message #320 Message #321 Message #337 Message #370 Message #409 Message #422 Message #789 Message #934 Guide to National Student Index - GINS 6.5-final.docx Page 68 of 148 Operation Status HTTP Code Response Response Header Response Body (JSON) Message Message #945 Message #951 Message #957 Message #1282 Unauthorised 401 NSISessionToken Result message details – section 5.5 Message #257 Message #528 Forbidden 403 NSISessionToken Result message details – section 5.5 Message #529 Bad Syntax 500 NSISessionToken Result message details – section 5.5 Message #789 Guide to National Student Index - GINS 6.5-final.docx Page 69 of 148 5.7.5 Request to Merge Student Records via REST This web service receives and processes a request to merge between 2 and up to 10 NSI student records. 5.7.5.1 Request to Merge Student Record Function – Inputs 5.7.5.1.1 Input Data Syntax Operation REST Verb Resource URL Header payload Body Payload (JSON) Submit Merge Request POST MergeRequest/ Content-Type NSISessionToken { "NSNList": [ {"NSN": <NSN1> }, {"NSN": <NSN2> },...] } 5.7.5.1.2 Input Data Fields Field Type/Length Content-Type Description Requirement Indicates the "type" associated with the message body's byte sequence. Must read “application/json” Mandatory Message #789 NSISessionToken Alphanumeric (36) Session token returned from previous login call. Mandatory Message #257 Message #528 NSN Numeric (10) First NSN to be included in the set of records to be merged. Mandatory Message #257 Message #819 NSN Numeric (10) Second NSN to be included in the set of records to be merged. Mandatory Message #257 Message #819 Guide to National Student Index - GINS 6.5-final.docx Page 70 of 148 Field Type/Length Description Requirement NSN Numeric (10) Third NSN to be included in the set of records to be merged. Optional Up to ten NSN’s can be included in a merge request. The fourth through to the tenth NSN submitted will have the same attributes and messages as the third NSN described above. Guide to National Student Index - GINS 6.5-final.docx Page 71 of 148 5.7.5.2 Request to Merge Student Record Function – Outputs 5.7.5.2.1 Output Function Syntax The following tables explain the returned HTTP response message passed over the HTTPS medium for each merge request and the relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP response code and if required, a JSON message which will include the NSI error message code and descriptions. Operation Status HTTP Code Response Response Header Response Body (JSON) Message Merge request Successful – Merge automatically approved 200 NSISessionToken Result message details – section 5.5 Message #055 Successful – Merge sent for Manual Intervention 200 NSISessionToken Result message details – section 5.5 Parent Message: Message #915 Sub-messages: Message #817 Message #898 Message #899 Message #902 Message #903 Message #916 Message #944 Guide to National Student Index - GINS 6.5-final.docx Page 72 of 148 Operation Status HTTP Code Response Response Header Response Body (JSON) Message Successful – Merge Rejected 200 NSISessionToken Result message details – section 5.5 Parent message: Message #956 Sub-messages: Message #897 Message #338 Bad request 400 NSISessionToken Result message details – section 5.5 Message #257 Message #337 Message #353 Message #819 Message #956 Unauthorised 401 NSISessionToken Result message details – section 5.5 Message #257 Message #528 Forbidden 403 NSISessionToken Result message details – section 5.5 Message #529 Bad Syntax 500 NSISessionToken Result message details – section 5.5 Message #789 Guide to National Student Index - GINS 6.5-final.docx Page 73 of 148 5.7.6 Create / Update Student Provider Relationship (SPR) via REST This web service allows the creation/updating of Student Provider relationships. Where an Active until date is provided this will be used to set the date the relationship will expire. Where no date is provided the default duration of the Provider’s relationships will be used. 5.7.6.1 Create / Update Student-Provider Relationship Function – Inputs 5.7.6.1.1 Input Data Syntax Operation REST Verb Resource URL Header payload Body Payload (JSON) Add or Update Student Provider Relationship POST Student Provider Relationship/ Content-Type NSISessionToken { “ProviderCode” : <Provider code>, “NSN” : <NSN>, “ActiveUntilDate” : <Active until date> } 5.7.6.1.2 Input Data Fields Field Type/Length Content-Type NSISessionToken Alphanumeric (36) Guide to National Student Index - GINS 6.5-final.docx Description Requirement Indicates the "type" associated with the message body's byte sequence. Must read “application/json” Mandatory Message #789 Session token returned from previous Login Call. Mandatory Message #257 Message #528 Page 74 of 148 Field Type/Length Description Requirement ProviderCode Alphanumeric (10) The provider code of the provider that the NSI record will have a relationship with Optional (This is the provider the SPR is to be set up with. Default is the user’s Provider organisation. If supplied, the user’s provider organisation must be authorised to submit Student Provider relationships ‘on behalf’ of other organisations.) Message #060 Message #339 NSN Numeric (10) The NSN of the record the relationship is created/updated for Mandatory Message #257 Message #409 Guide to National Student Index - GINS 6.5-final.docx Page 75 of 148 Field Type/Length Description Requirement ActiveUntilDate Date/Time (20) Date student provider relationship will expire yyyy-MM-dd e.g. 2013-11-28 Optional. If not provided use the default active at period as set in the Provider Details for the uploading organisation (if provided), otherwise the organisation associated with the user sending the request. Message #304 Message #305 Message #423 Guide to National Student Index - GINS 6.5-final.docx Page 76 of 148 5.7.6.2 Create / Update Student-Provider Relationship Function – Outputs 5.7.6.2.1 Output Function Syntax The following tables explain the returned HTTP response message passed over the HTTPS medium for each request and the relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP response code and if required, a JSON message which will include the NSI error message code and descriptions. Operation Status HTTP Code Response Response Header Response Body (JSON) Student Successful Provider Bad Request Relationship 200 NSISessionToken <none> 400 NSISessionToken Result message details – section 5.5 Message #060 Message #257 Message #304 Message #305 Message #337 Message #339 Message #409 Message #422 Unauthorised 401 NSISessionToken Result message details – section 5.5 Message #257 Message #528 Forbidden 403 NSISessionToken Result message details – section 5.5 Message #529 Bad Syntax 500 NSISessionToken Result message details – section 5.5 Message #789 Guide to National Student Index - GINS 6.5-final.docx Page 77 of 148 Message 5.7.7 Logout of the NSI via REST This function ends a session with the NSI system by logging the user out. 5.7.7.1 Logout Function - Inputs A logout operation results in deletion of the NSI Session Token from session table and request to ESAA for termination of the ESAA session token. 5.7.7.1.1 Input Data Syntax Operation REST Verb Resource URL Header payload Body Payload (JSON) Logout DELETE session/ <NSISessionToken> none 5.7.7.1.2 Input Data Fields Label / Field Type/Length Description Requirement NSISessionToken Alphanumeric (36) Session Token returned from previous Login Call Mandatory Message #257 Message #528 Guide to National Student Index - GINS 6.5-final.docx Page 78 of 148 5.7.7.2 Logout Function – Outputs 5.7.7.2.1 Output Data Syntax The following table explains the returned HTTP response message passed over the HTTPS medium for each logout request and the relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP response code and if required, a JSON message which will include the NSI error message code and descriptions. Operation Status HTTP Code Response Logout Successful logout Not Authorised Response Body (JSON) Error 200 Result message details – section 5.5 Message #088 401 Result message details – section 5.5 Message #257 Message #528 Guide to National Student Index - GINS 6.5-final.docx Response Header Page 79 of 148 6 Batch File Interface 6.1 Overview The batch interface mechanism allows organisations to build up a batch of requests in a batch file over the course of a day (or any period that suits the organisation’s business processes). These files are then uploaded to the NSI system for batch processing. 6.2 Accessing the Batch interface Base URL for all Batch queries: https://nsi.education.govt.nz/interface/batch_ Key notes: following the “batch_”, the batch function is entered i.e. login.asp or upload.asp Environment URLs for production and compliance are: o Production: https://nsi.education.govt.nz/interface/batch_ o Compliance: https://nsi.compliance.education.govt.nz/interface/batch_ To access the NSI Web UI (required to view Batch files available to be downloaded), use the following URL’s: o Production: https://nsi.education.govt.nz/ o Compliance: https://nsi.compliance.education.govt.nz/ 6.2.1 Batch File Types There are four batch file types available for upload to the NSI: Search Request, Update/Insert Request, and Merge Request files Student-Provider Relationship add/update (ATA) These files are described in full in the following sections. Once a batch file has been submitted via the NSI Web Application, the file is processed and then a results file is made available for the organisation to download. This file reports all outcomes of the request file. Guide to National Student Index gins Page 80 of 148 6.2.2 Batch File Format Batch files can be supplied in one of two formats (the results files returned to the organisation will be in the corresponding format): 1. Delimited, or 2. XML Please note the NSI system will not accept any batch files larger than 2MB. 6.2.3 File Naming Conventions 6.2.3.1 Inbound File Naming Convention All inbound request files must conform to the following naming convention: tttnnnnn.fff Where: ttt = file type i.e. SEA, UPI, MER or ATA nnnnn = organisation's unique file reference, e.g. 10345 or au926 fff = file format, which must be either “xml” or “txt” For example: MER00001.xml would be a merge request file in xml format. SEA008td.txt would be a search file in txt format. UPI90302.txt would be an update/insert file in txt format ATA12345.xml would be an ATA file in xml format. Organisations should keep a record of their unique file reference (nnnnn above) to allow them to cross-reference the request file with the outbound results file. 6.2.3.2 Outbound File Naming Convention There are five result files that are generated by the NSI system for organisations. These files are: 1. Search Results. 2. Update/Insert Results. 3. Merge Results. 4. ATA Results 5. Change Notification. These five output files produced by the NSI will conform to the following naming convention: REtnnnnn.fff Guide to National Student Index - GINS 6.5-final.docx Page 81 of 148 Where RE = Indicates “results” file t = file type indicator (defined below) nnnnn = organisation's unique file reference fff = file format (“xml” or “txt”) The one-char file type indicators are S (Search), U (Update/Insert), M (Merge), C (Change Notification) and A (Student-Provider Relationship - ATA) So, REM00001.xml would be a merge request results file in xml format. 6.2.4 Delimited File Footers Delimited file formats must include information in the footer as specified below. 6.2.4.1 Inbound File Footer Convention Information contained within the footer record of each inbound pipe-delimited text file must conform to the following layout: ZZXXCCZZXXCC | provider_code | input filename | date file created | time file created | file type long description | record count where: Fieldname Description Example (where applicable) ZZXXCCZZXXCC A literal indicating that this is a footer line. - provider_code The Ministry organisation code. 9999 input filename The name of the file. UPI00001.txt date file created The date the file was created in the format yyyymmdd. 20010915 time file created The time the file was created in the format hhmmss. 140000 file type long description Text describing the file contents, Update/Insert. For UPI files the footer must include the text ‘Update/Insert’ in this field. Update/Insert/Sear ch Merge/Active At Guide to National Student Index - GINS 6.5-final.docx Page 82 of 148 Fieldname Description Example (where applicable) record count A total of all lines in the input file (including the footer record). - 6.2.4.2 Outbound File Footer Convention Information contained within the footer record of each outbound pipe-delimited file will conform to the following layout: ZZXXCCZZXXCC | provider_code | output filename | original input filename | date outfile created | time outfile created | file type long description | record count Where the record (line) count includes footer record, file type long description is "Batch xxxxx Results" where xxxxx is one of Search, Merge or Update/Insert. Change Notification files do not have a footer. 6.2.5 Uploading/Downloading Batch Files Batch files can be uploaded and downloaded via the Web Interface (manually) or via the Batch interface (automated through your SMS). Uploading and downloading batch files via the web interface requires the manual upload of the file. Users can also view all results files available for their organisation and choose to download those files. The automated method of uploading your batch files requires an HTTPS Upload process to be set up in conjunction with the MoE Service Desk. Please contact the MoE Service Desk if you wish to automate either of these processes. Please note: Each file uploaded via the Batch Interface must have a unique filename. This applies even if the file is being run a second time after errors have been cleaned up. 6.3 Security and Authentication This will be achieved using HTTPS Upload and user authentication via the connection to the NSI application. Please talk with the MoE Service Desk if you want to establish secure access to the NSI using a server-based login and password to authenticate. This must be done well in advance of sending any batch files. Guide to National Student Index - GINS 6.5-final.docx Page 83 of 148 When login and password authentication is being used, note that three incorrect logon attempts will result in you being ‘locked out’ of the NSI, and you will need to contact the MoE Service Desk to regain access to the system via .service.desk@education.govt.nz or . 0800 422 599 Where a logon has expired or been ‘locked out’, the following error code will be returned: Error code Description 528 Session has timed out, or session not established. Those integrating at a server level will need to trap for this code being returned in order to ensure that SMS users are aware of why their access is being denied, and know what action to take. Guide to National Student Index - GINS 6.5-final.docx Page 84 of 148 6.4 Batch File Functions 6.4.1 Search Request File The NSI System will perform an NSN search on each provided NSN in the Search Request file or will perform a match search on each non-NSN criteria provided. 6.4.2 Update/Insert Batch File Organisations can upload an Update/Insert request file at any time. Additionally, prior to an organisation using the NSI system, their student data will be loaded into the NSI system using this method. The same file format will be used for both of these cases. When an existing NSN is supplied in an Update/Insert file, the request will be treated as an update to this record. When the NSN is not supplied (but other search criteria such as names and birth date are) the request will be treated initially as a search and then, if no matches are found above a threshold, an insert will be made. If a ‘definite’ match is found, that record will be returned to the user and a new record will NOT be added (to add a record you will need to contact the MoE Service Desk with documentation to prove the student records are different). If a ‘possible’ match is found, an override code will be returned. In this case, in order for the record to be added, this override code must be supplied in the batch file in a subsequent request. The process will be conducted for each separate request in the file and the results returned accordingly. A file formatting error anywhere in the file will result in a failure of the whole file to process. Guide to National Student Index - GINS 6.5-final.docx Page 85 of 148 The following diagram shows the Update/Insert batch file process flow. NSN provided? Yes No ADD UPDATE Validate input for Add request Validation passed? Validate input for Update request Yes Process Match Search Definite match found? No Possible match found? Yes Yes Return definite match in results Override code supplied? Guide to National Student Index gins No Add Student and send new NSN Yes Yes Validation passed? No No Generate override code Return override code in results Page 86 of 148 Validation passed? Yes Update Student 6.4.3 Merge Request Batch File Where an organisation believes there are multiple NSI records for one student, a request to merge the student records can be submitted to the NSI. There are three basic outcomes of a merge request that will be returned from a merge request. These are: 1. Successful merge – master NSN automatically selected. 2. Merge rejected – merge set sent to merge denied list. 3. Merge sent to manual intervention. 6.4.4 Change Notification Batch Files Change Notification files contain details of any records which have an ‘SPR’ with an organisation the organisation requesting the file, where changes have occurred since the last change notification file was downloaded (see section 3.6) which have changed. 6.4.5 Student-Provider Relationship (Add / Update) The Active At file contains a list of NSNs and associated providers. If the record passes validation a student-provider relationship is created or the existing active until date updated for each record. Guide to National Student Index - GINS 6.5-final.docx Page 87 of 148 6.5 Automated Upload/Download of Batch Files The automated method of uploading your batch files requires an HTTPS Upload process to be set up in conjunction with the MoE Service Desk. Similarly, it is possible for results files to be downloaded via HTTPS Download. Please contact the MoE Service Desk if you wish to automate either of these processes. The automated method of uploading and downloading Batch files requires users to login/logout through the Batch Interface, as well as send specific requests to defined URLs. The basic steps required to be performed for uploading files include: 1. Login – by posting the Login Request as per section 6 to https://nsi.education.govt.nz/interface/batch_login.asp 2. Post files to https://nsi.education.govt.nz/interface/batch_upload.asp? 3. Logout – by posting the Logout Request as per section 6 to https://nsi.education.govt.nz/interface/batch_login.asp Similarly, it is possible for results files to be downloaded via HTTPS Download. The basic steps required to be performed include: 1. Login – by posting the Login Request as per section 6 to https://nsi.education.govt.nz/interface/batch_login.asp 2. Get list of files to download from https://nsi.education.govt.nz/interface/batch_download.asp?list 3. Get each file from https://nsi.education.govt.nz/interface/batch_download.asp?file={filename} 4. Logout – by posting the Logout Request as per section 6 to https://nsi.education.govt.nz/interface/batch_login.asp Guide to National Student Index - GINS 6.5-final.docx Page 88 of 148 6.5.1 Login to the NSI through Batch Interface 6.5.1.1 Input The following details the XML format users must comply with when logging into the NSI through the Batch Interface as the input: <?xml version="1.0" encoding="ISO-8859-1" ?> <login version="1.0"> <user_id></user_id> <password></password> <org_id></org_id> </login> The following detail describes the XML tags detailed above to guide users of this document who may not be familiar with XML (this table does not describe data fields) Tag Description <?xml version="1.0" encoding="ISO-8859-1" ?> Common XML header <login version="1.0"> Start of login record </login> End of login record The following table details the data fields associated to each of the input fields described above. The table details the data type of the field, the description of that field and the business requirement for including the field in the request file. Field Type/Length Description Requirement user_id Character (200) User ID of user logging in. Mandatory. password Character (32) Password of user logging in. Mandatory. org_id Character(10) The organisation the user is signing in on behalf of. Mandatory. Guide to National Student Index - GINS 6.5-final.docx Page 89 of 148 6.5.1.2 Outputs <?xml version="1.0" encoding="ISO-8859-1" ?> <result version="1.0"> <code></code> <description></description> </result> Field Type /Length Description code 32-bit signed Integer Outcome of login attempt description Character (255) Description of error message The following detail describes the XML tags detailed above to guide users of this document who may not be familiar with XML (this table does not describe data fields) Tag Description <?xml version="1.0" encoding="ISO-8859-1" ?> Common XML header <result version="1.0"> Start of result record </result> End of result record Guide to National Student Index - GINS 6.5-final.docx Page 90 of 148 6.5.2 Logout from the NSI through the Batch Interface 6.5.2.1 Input The following details the XML format users must comply with when logging out of the NSI through the Batch Interface as the input: <?xml version="1.0" encoding="ISO-8859-1" ?> <logout/> The following detail describes the XML tags detailed above to guide users of this document who may not be familiar with XML (this table does not describe data fields) Tag Description <?xml version="1.0" encoding="ISO-8859-1" ?> Common XML header <logout/> logout record The following table details the data fields associated to each of the input fields described above. The table details the data type of the field, the description of that field and the business requirement for including the field in the request file. Field Type/Length Security Key Guide to National Student Index - GINS 6.5-final.docx Description Requirement Cookie from login response header containing the security key to be used in successive requests. Mandatory Page 91 of 148 6.5.2.2 Outputs <?xml version="1.0" encoding="ISO-8859-1" ?> <result version="1.0"> <code></code> <description></description> </result> Field Type /Length Description code 32-bit signed Integer Outcome of login attempt description Character (255) Description of error message The following detail describes the XML tags detailed above to guide users of this document who may not be familiar with XML (this table does not describe data fields) Tag Description <?xml version="1.0" encoding="ISO-8859-1" ?> Common XML header <result version="1.0"> Start of result record </result> End of result record Guide to National Student Index - GINS 6.5-final.docx Page 92 of 148 6.5.3 Automated Upload of Batch files Once you have logged into the NSI through the Batch Interface, you can POST your batch file to the following URL: https://nsi.education.govt.nz/interface/batch_upload.asp?Page=2 6.5.3.1 Successful Upload Output When you have uploaded a file successfully using the automated upload function, you will get the following output: Msg:<message description> File: File Name : <uploaded filename> Size: File Length: <file size> 6.5.3.2 Unsuccessful Upload Output When an error has occurred when uploading a batch file using the automated batch upload function, you will get the following out: <br><error description><br> 6.5.4 Automated Download of Batch Files 6.5.4.1 Download List To view if there are any files available for download for your organisation, you will need to send a get request to the following URL: https://nsi.education.govt.nz/interface/batch_download.asp?list The returned results will only display files that have not yet been downloaded from the NSI for your organisation. The output will be returned as a space delimited list 6.5.4.2 Download File To use the automated download of a file from the NSI system, you must know the name of the results file you wish to download. Once the file name is known, you will need to send a GET request to the following URL: https://nsi.education.govt.nz/ interface/batch_download.asp?file={filename} The name of the file you wish to download will be populated in the {filename} field above. Guide to National Student Index - GINS 6.5-final.docx Page 93 of 148 6.6 Delimited Batch File Formats 6.6.1 Encoding Delimited batch file results will be ANSI encoded. Diacritics and special characters (other than ‘~’ for Given name 1) will not be accepted by the NSI system. Where diacritics are submitted to the NSI, the following error message will be returned Error code Description 272 {0} must only contain alphabetic characters, space, hyphen, apostrophe or a single '~'. Space hyphen and apostrophe cannot be used without another character or repeated. Names must start with an apostrophe or an alphabetic character.). Guide to National Student Index - GINS 6.5-final.docx Page 94 of 148 6.6.2 Search The following sections detail the input and output requirements for delimited Search batch files 6.6.2.1 Inputs The following details the Delimited format users must comply with when requesting a search for student details using a .txt (delimited) file type as the input: nsn | name | dob | gender | residential_status | provider_reference Please note: Spaces are used between field names and delimiter in examples for clarity only. Spaces between delimiters and data should not be supplied in any batch files as they will cause the file to fail processing. An example of the correct format is: 122|||||1001 or |Joe Bloggs|19800101|M|C|1001 All delimited files require a footer record. Refer to section 6.1.4 Delimited File Footers for information on the file footer requirements. The following table details the data fields associated to each of the input fields described above. Parameter Type Description Requirement nsn 32-bit signed Integer The NSN of the student to search for. Mandatory if no other parameters are supplied. name Character (403) The name to be searched for. Mandatory if NSN is not supplied. dob Character (8) The date of birth of the student in format yyyymmdd e.g. 19890621 Optional – may only be used in conjunction with Name. Guide to National Student Index - GINS 6.5-final.docx Page 95 of 148 Parameter Type Description Requirement gender Character (1) The gender of the student, where U stands for unknown. Valid values for Gender: M (Male) F (Female) U (Unknown) Optional – may only be used in conjunction with Name. residential_stat Character (1) us The residential status of the student. Valid values for Residential status: C (NZ citizen) P (NZ Permanent resident) A (Australian citizen) O (Other) U (Unknown) Optional – may only be used in conjunction with Name. provider_refer ence A reference passed from an SMS to the NSI in order for it to be returned in the output. Optional. Character (30) Guide to National Student Index - GINS 6.5-final.docx Page 96 of 148 6.6.2.2 Outputs A new section starting with an ‘S’ line will appear in the results file for each name submitted to the search. 6.6.2.2.1 Successful Match – Definite Match Search string: S | search string i.e. S | nsn | name | dob | gender | residential_status | provider_reference Exact match U | nsn | surname | forename1 | forename2 | forename3 | preferred_name_indicator | dob | name_dob_verification | name_dob_verified_by | residential_status | residential_status_verification | residential_status_verified_by | gender | created_date | created_by_userid | created_by_provider_code | dod | nzqa_paid | record_status | ranking | alternate_surname | alternate_forename1 | alternate_forename2 | alternate_forename3 | alternate_preferred_name_indicator | match_indicator | provider_reference U refers to unique match. For every alternative name found, a separate ‘U’ line will be returned following the ‘U’ line which contains the main record details. For example, if a record has two alternative names, three ‘U’ lines will be present, one containing the main record details, and a subsequent line for each alternative name. 6.6.2.2.2 Successful Match – Possible Match(es) Search String: S | search string i.e. S | nsn | name | dob | gender | residential_status | provider_reference Inexact (partial) match (search on criteria excluding NSN): P | ranking | nsn | surname | forename1 | forename2 | forename3 | dob | gender | preferred_name_indicator | residential_status | residential_status_verified_by | created_date | created_by_provider_code | match_indicator | provider_reference P refers to partial match. Guide to National Student Index - GINS 6.5-final.docx Page 97 of 148 6.6.2.2.3 Unsuccessful search – No matches found/Error returned Search string: S | search string i.e. S | nsn | name | dob | gender | residential_status | provider_reference Errors: E | error code | error description | provider_reference 6.6.2.2.4 File Footer The Results file footer will be display directly after the final processed record ZZXXCCZZXXCC | provider code | output filename | input filename | created date | created time | Batch Search Results | record count Guide to National Student Index - GINS 6.5-final.docx Page 98 of 148 6.6.3 Update/Insert The following sections detail the input and output requirements for delimited Update/Insert batch files 6.6.3.1 Inputs The pipe character ‘|’ (ASCII 124) will be used as the delimiter. The file must be in DOS format, that is, each line must be terminated with a Carriage Return (ASCII 13) and a Line Feed (ASCII 10). nsn | surname | forename1 | forename2 | forename3 | gender | preferred_name_indicator | dob | name_dob_verification | residential_status | residential_status_verification | alternate_surname | alternate_forename1 | alternate_forename2 | alternate_forename3 | alternate_preferred_name_indicator | override_code | provider_reference Please note: Spaces are used between field names and delimiter in examples for clarity only. Spaces between delimiters and data should not be supplied in any batch files as they will cause the file to fail processing. An example of the correct format is: 122|Bloggs|Joe|William|Tom|M|Y|19181111|U|C|P|Blogs|Joseph|||||1001 All delimited files require a footer record. Refer to section 6.1.4 Delimited File Footers for information on the file footer requirements. The following table details the data fields associated to each of the input fields described above. Parameter Type Description Requirement nsn 32-bit signed Integer The NSN of the student to search for. Mandatory surname Character (100) Surname of the student Mandatory forename1 Character (100) First forename of the student Mandatory for an Insert request forename2 Character (100) Second forename of the student Conditionally mandatory if Forename3 is supplied forename3 Character (100) Third forename of the student Optional Guide to National Student Index - GINS 6.5-final.docx Page 99 of 148 Parameter Type Description Requirement gender Character (1) M, F or U. The gender of the student, where U stands for unknown Optional preferred_nam e_indicator Character (1) Y or N specifying that this name Optional is the preferred name. dob Character (8) The date of birth of the student in format yyyymmdd e.g. 19890621 Mandatory for a Insert request name_dob_ver Character (1) ification The verification method used to verify name/dob. Can be Unverified, Passport, Birth Cert, or Other primary id. Optional residential_stat Character (1) us The residential status of the student. NZ Citizen, NZ Permanent resident, Australian citizen, Overseas or Unknown. Optional. residential_stat Character (1) us_verification The residential status verification. Can be Unverified, Passport, Birth Cert, or Other primary id. Optional alternative_sur name Character (100) The last name of an alternative name used by the student Optional alternative_for ename1 Character (100) The first name of an alternative name used by the student Optional alternative_for ename2 Character (100) The second name of an alternative name used by the student Optional alternative_for ename3 Character (100) The third name of an alternative Optional name used by the student alternative_pre ferred_name_i ndicator Character (1) Y or N specifying whether this alternative name is the preferred name. Optional override_code Character (10) Indicates that the record should be added despite the known existence of a partially matching record/s already in the NSI database. The value will be the same as that returned by a previous attempt to add the record Optional Guide to National Student Index - GINS 6.5-final.docx Page 100 of 148 Parameter Type Description Requirement provider_refer ence Character (30) A reference passed from an SMS to the NSI in order for it to be returned in the output Optional Footer lines must be terminated with a Carriage Return (ASCII 13). Guide to National Student Index - GINS 6.5-final.docx Page 101 of 148 6.6.3.2 Outputs 6.6.3.2.1 Student Added / Definite Match Returned / Successful Update When no matching records are returned and the student record is added successfully OR a definite match is returned OR an update has been processed successfully, the result will contain either, the created student record, the updated student record or the matched student record. The format is: M | nsn | surname | forename1 | forename2 | forename3 | gender | preferred_name_indicator | dob | name_dob_verification | name_dob_verified_by | residential_status | residential_status_verification | residential_status_verified_by | nzqa_paid | dod | student_status | created_date | created_by_userid | created_by_provider_code | alternate_surname | alternate_forename1 | alternate_forename2 | alternate_forename3 | alternate_preferred_name_indicator | alternate_name_dob_verification | override_code | provider_reference 6.6.3.2.2 Possible Match(es) Returned The submitted details of the student record will be returned in an ‘M’ line along with an override code. This will be followed by the matching record(s) as an “S” line. The format is: M | nsn | surname | forename1 | forename2 | forename3 | gender | preferred_name_indicator | dob | name_dob_verification | name_dob_verified_by | residential_status | residential_status_verification | residential_status_verified_by | nzqa_paid | dod | student_status | created_date | created_by_userid | created_by_provider_code | alternate_surname | alternate_forename1 | alternate_forename2 | alternate_forename3 | alternate_preferred_name_indicator | alternate_name_dob_verification | override_code | provider_reference S | nsn | surname | forename1 | forename2 | forename3 | gender | preferred_name_indicator | dob | name_dob_verification | name_dob_verified_by | residential_status | residential_status_verification | residential_status_verified_by | nzqa_paid | dod | student_status | created_date | created_by_userid | created_by_provider_code | ranking | match_indicator | provider_reference Guide to National Student Index - GINS 6.5-final.docx Page 102 of 148 6.6.3.2.3 Error When an error has occurred with the submitted information, the submitted details of the student will be returned in an “M” line (as above), followed by the error details in an “E” row as detailed below: E | code | description | provider_reference 6.6.3.2.4 File Footer The Results file footer will be display directly after the final processed record ZZXXCCZZXXCC | provider code | output filename | input filename | created date | created time | Batch Update/Insert Results | record count 6.6.3.2.5 Processing Statistics Below the results file footer, the batch file will contain statistics on the processing of the file: New NSNs issued: nn Matches Not Requiring Manual Intervention: nn Matches Requiring Manual Intervention: nn Records updated: nn Records failed validation: nn Total Records processed: nn Guide to National Student Index - GINS 6.5-final.docx Page 103 of 148 6.6.4 Merge Request The following sections detail the input and output requirements for delimited Merge Request batch files, 6.6.4.1 Inputs nsn | nsn | nsn | nsn | nsn | nsn | nsn | nsn | nsn | nsn Please note: Spaces are used between field names and delimiter in examples for clarity only. Spaces between delimiters and data should not be supplied in any batch files as they will cause the file to fail processing. An example of the correct format is: 122|13 Or 13|26|39|45|58|61|67|80|96|122 All delimited files require a footer record. Refer to section 6.1.4 Delimited File Footers for information on the file footer requirements. The following table details the data fields associated to each of the input fields described above. The table details the data type of the field, the description of that field and the requirement for including the field in the request file. Field Type/Length Description Requirement nsn1 32-bit signed Integer NSN of a record to be included in the set of records to be merged Mandatory nsn2 32-bit signed Integer NSN of a record to be included in the set of records to be merged Mandatory nsn3 32-bit signed Integer NSN of a record to be included in the set of records to be merged Optional nsn4 32-bit signed Integer NSN of a record to be included in the set of records to be merged Optional nsn5 32-bit signed Integer NSN of a record to be included in the set of records to be merged Optional nsn6 32-bit signed Integer NSN of a record to be included in the set of records to be merged Optional Guide to National Student Index - GINS 6.5-final.docx Page 104 of 148 Field Type/Length Description Requirement nsn7 32-bit signed Integer NSN of a record to be included in the set of records to be merged Optional nsn8 32-bit signed Integer NSN of a record to be included in the set of records to be merged Optional nsn9 32-bit signed Integer NSN of a record to be included in the set of records to be merged Optional nsn10 32-bit signed Integer NSN of a record to be included in the set of records to be merged Optional Guide to National Student Index - GINS 6.5-final.docx Page 105 of 148 6.6.4.2 Outputs The following sections define the syntax for all potential outcomes of a merge request in delimited format. 6.6.4.2.1 Records merged successfully Student records merged, master NSN is returned along with the NSNs included in the request. M | Request string N | new_master_nsn | surname | forename1 | forename2 | forename3 6.6.4.2.2 Merge rejected Merge request not submitted. NSNs in request returned to the user with the related error code and description. M | Request string E | error code | Merge Rejected | reason text 6.6.4.2.3 Manual Intervention required Merge request created and submitted to MoE for review. NSN’s included in the merge request returned along with the related error code and description. M | Request string E | error code | Manual Intervention Required | reason text 6.6.4.2.4 Error Merge request not submitted. Error with request, NSNs included in request are returned to the user with the related error code and description. M | Request string E | error code | reason text 6.6.4.2.5 Processing Statistics Below the results file footer, the batch file will contain statistics on the processing of the file: Successful Merge: nn Rejected Merge: nn Manual Intervention Required: nn Total Records processed: nn Guide to National Student Index - GINS 6.5-final.docx Page 106 of 148 6.6.5 Student-Provider Relationship (ATA) Add / Update The following sections detail the input and output requirements for delimited ATA batch files 6.6.5.1 Inputs Provider Code | NSN | Active Until Date Please note: Spaces are used between field names and delimiter in examples for clarity only. Spaces between delimiters and data should not be supplied in any batch files as they will cause the file to fail processing. An example of the correct format is: 6022|13|20160101 All delimited files require a footer record. Refer to section 6.1.4 Delimited File Footers for information on the file footer requirements. The following table details the data fields associated to each of the input fields described above. The table details the data type of the field, the description of that field and the requirement for including the field in the request file. 6.6.5.1.1 Data Fields Parameter Type Description Requirement provider_code Character(10) The Ministry assigned provider code. Conditionally mandatory (This is the provider the SPR is to be set up with. Default is the user’s Provider organisation. If supplied, the user’s provider organisation must be authorised to submit Student Provider relationships ‘on behalf’ of other organisations.) Guide to National Student Index - GINS 6.5-final.docx Page 107 of 148 Parameter Type Description Requirement nsn 32-bit signed Integer The NSN of the student to search for. Mandatory Valid date in format yyyymmdd e.g. 19890621 Optional. If not provided use the default active at period as set in the Provider Details for the uploading organisation (if provided), otherwise the organisation associated with the user sending the request. active_until_da Character(8) te Guide to National Student Index - GINS 6.5-final.docx Page 108 of 148 6.6.5.2 Outputs 6.6.5.2.1 Successful Active At creation For a successful Active At creation, no message is reported back to the user. 6.6.5.2.2 Errors returned Error records are reported first: E | Error Code | Error Description | Input record (see inbound file) 6.6.5.2.3 Processing statistics Statistics are returned in all result files (errors and successful additions). Summary of processing: nn Records created/updated for provider code nnnn: nn Records failed validation for provider code nnnn: nn Records created/updated: nn Records failed validation: nn Total records processed: nn Guide to National Student Index - GINS 6.5-final.docx Page 109 of 148 6.6.6 Change Notifications The following sections detail the delimited Change Notification batch files. There are no related Change Notification inputs. 6.6.6.1 Inputs N/A 6.6.6.2 Outputs The pipe character ‘|’ - ASCII 124 - will be used as the delimiter. Changed Records: Denoted by a C at the start of the line, these records are used to report a data change as follows: C | modified_date | nsn | master nsn | surname | forename1 | forename2 | forename3 | preferred_name_indicator | gender | dob | dod | name_dob_verification | residential_status | residential_status_verification | nzqa_paid | student_status | modified_by_provider_code | changed_field_indicator Merge Denied Records: Denoted by a D at the start of the line, these records are used to report that a merge request from the organisation has been denied. Up to 10 NSN’s may be reported on this record. All delimiters will be present despite the number of NSN’s reported: D | NSN | NSN | NSN | NSN | NSN | NSN | NSN | NSN | NSN | NSN Guide to National Student Index - GINS 6.5-final.docx Page 110 of 148 6.7 XML Batch File Formats 6.7.1 Encoding XML batch file results will be ISO 8859-1 encoded. Diacritics and special characters (other than ‘~’ for Given name 1) will not be accepted by the NSI system. Where diacritics are submitted to the NSI, the following error message will be returned Error code Description 272 {0} must only contain alphabetic characters, space, hyphen, apostrophe or a single '~'. Space hyphen and apostrophe cannot be used without another character or repeated. Names must start with an apostrophe or an alphabetic character.). . Guide to National Student Index - GINS 6.5-final.docx Page 111 of 148 6.7.2 Search The following sections detail the input and output requirements for XML Search batch files. 6.7.2.1 Inputs The following details the XML format users must comply with when requesting a search for student details using an .xml file type as the input. The student_list can contain one or more student elements: <?xml version=”1.0” encoding=”ISO-8859-1” ?> <student_list version=”1.0”> <student> <nsn></nsn> <name></name> <dob></dob> <gender></gender> <residential_status></residential_status> <provider_reference></provider_reference> </student> </student_list> The following detail describes the XML tags detailed above to guide users of this document who may not be familiar with XML (this table does not describe data fields) Tag Description <?xml version="1.0" encoding="ISO-8859-1" ?> Common XML header <student_list version= "1.0"> Start of list of students </student_list> End of list of students <student> Start of student record within student list <student> Start of student record within student list </student> End of student record within student list 6.7.2.1.1 Data Fields The following table details the data fields associated to each of the input fields described above. The table details the data type of the field, the description of that field and the requirement for including the field in the request file. Guide to National Student Index - GINS 6.5-final.docx Page 112 of 148 Parameter Type Description Requirement nsn 32-bit signed Integer The NSN of the student to search for. Mandatory if no other parameters are supplied. name Character (403) The name to be searched for. Mandatory if NSN is not supplied. dob Character (8) The date of birth of the student in format yyyymmdd e.g. 19890621 Optional – may only be used in conjunction with Name. gender Character (1) The gender of the student, where U stands for unknown. Valid values for Gender: M (Male) F (Female) U (Unknown) Optional – may only be used in conjunction with Name. residential_stat Character (1) us The residential status of the student. Valid values for Residential status: C (NZ citizen) P (NZ Permanent resident) A (Australian citizen) O (Overseas) U (Unknown) Optional – may only be used in conjunction with Name. provider_refer ence A reference passed from an SMS to the NSI in order for it to be returned in the output. Optional. Character (30) Guide to National Student Index - GINS 6.5-final.docx Page 113 of 148 6.7.2.2 Outputs Where more than one search has been submitted in the XML input file, a separate <student/> element within each <result/> tag will be present in the output for each in the result_list. The following details the XML format of the XML results files returned to a user when a download request is processed: 6.7.2.2.1 Successful Match – One result found <?xml version=”1.0” encoding=”ISO-8859-1”?> <result_list version=”1.0”> <result> <criteria> <nsn></nsn> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> <dob></dob> <gender></gender> <residentialstatus></residentialstatus> <provider_reference></provider_reference> </criteria> <student_list> <student> <nsn></nsn> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> <gender></gender> <preferred_name_indicator></preferred_name_indicator> <dob></dob> <name_dob_verification></name_dob_verification> <name_dob_verified_by></name_dob_verified_by> <residential_status></residential_status> <residential_status_verification></residential_status_verificatio n> <residential_status_verified_by></residential_status_verified_by> <nzqa_paid></nzqa_paid> <dod></dod> Guide to National Student Index - GINS 6.5-final.docx Page 114 of 148 <student_status></student_status> <created_by_userid></created_by_userid> <created_date></created_date> <created_by_provider_code></created_by_provider_code> <ranking></ranking> <match_indicator> </match_indicator> <name_list> <name> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> <preferred_name_indicator></preferred_name_indicator> <name_dob_verification></name_dob_verification> </name> </name_list> </student> </student_list> </result> </results_list> 6.7.2.2.2 Successful Match – Possible Match(es) If more than one record is found then the returned XML block will follow the above structure, and contain a separate </student> tag for each record, showing the following fields within each <student/> element: <nsn/> <surname/> <forename1/> <forename2/> <forename3/> <gender/> <preferred_name_indicator/> <dob/> <name_dob_verification/> <name_dob_verified_by/> <residential_status/> <residential_status_verification/> <residential_status_verified_by/> <nzqa_paid/> Guide to National Student Index - GINS 6.5-final.docx Page 115 of 148 <dod/> <student_status/> <created_date/> <created_by_userid/> <created_by_provider_code/> <ranking/> <match_indicator/> <name_list/> 6.7.2.2.3 Unsuccessful search – No matches found/Error returned <?xml version=”1.0” encoding=”ISO-8859-1” ?> <result_list version=”1.0”> <result> <criteria> <nsn></nsn> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> <dob></dob> <gender></gender> <residentialstatus></residentialstatus> <provider_reference></provider_reference> </criteria> <error> <code></code> <description></description> </error> </result> </results_list> The following detail describes the XML tags detailed above to guide users of this document who may not be familiar with XML.(This table does not describe data fields) Tag Description <?xml version="1.0" encoding="ISO-8859-1" ?> Common XML header <result_list version= "1.0"> Start of result list </result_list> End of result list <result> Start of result record within results list Guide to National Student Index - GINS 6.5-final.docx Page 116 of 148 Tag Description </result> End of result record within results list <criteria> Start of data input </criteria> End of data input <student_list> Start of list of students </student_list> End of list of students <student> Start of student record within student list </student> End of student record within student list <name_list> Start of list of names for student record </name_list> End of list of names for student record <name> Start of name record for student within name list </name> End of name record for student within name list <error> Start of error record for student </error> End of error record for student Guide to National Student Index - GINS 6.5-final.docx Page 117 of 148 6.7.3 Update/Insert The following sections detail the input and output requirements for XML Update/Insert batch files. 6.7.3.1 Inputs <?xml version=”1.0” encoding=”ISO-8859-1” ?> <student_list version=”1.0”> <student> <nsn></nsn> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> <dob></dob> <name_dob_verification></name_dob_verification> <preferred_name_indicator></preferred_name_indicator> <residential_status></residential_status> <residential_status_verification></residential_status_verification> <gender></gender> <override_code></override_code> <provider_reference></provider_reference> <alternate_name> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> <preferred_name_indicator></preferred_name_indicator> <alternate_name></alternate_name> </student> </student_list> The following detail describes the XML tags detailed above to guide users of this document who may not be familiar with XML (this table does not describe data fields) Tag Description <?xml version="1.0" encoding="ISO-8859-1" ?> Common XML header <student_list version= "1.0"> Start of list of student records <student> Start of student record within match list Guide to National Student Index - GINS 6.5-final.docx Page 118 of 148 Tag Description </student> End of student record within match list <alternate_name> Start of alternate name record within student record </alternate_name > End of alternate name record within student record </student_list> End of list of student records 6.7.3.1.1 Data Fields The following table details the data fields associated to each of the input fields described above. The table details the data type of the field, the description of that field and the requirement for including the field in the request file. Parameter Type Description Requirement nsn 32-bit signed Integer The NSN of the student to search for. Mandatory for an update request surname Character (100) Surname of the student Mandatory for an Insert Request forename1 Character (100) First forename of the student Mandatory for an Insert request forename2 Character (100) Second forename of the student Conditionally mandatory if Forename3 is supplied forename3 Character (100) Third forename of the student Optional gender Character (1) M, F or U. The gender of the student, where U stands for unknown Optional preferred_nam e_indicator Character (1) Y or N specifying that this name is the preferred name. Optional dob Character (8) The date of birth of the student in format yyyymmdd e.g. 19890621 Mandatory for a Insert request The verification method used to verify name/dob. Can be Unverified, Passport, Birth Cert, or Other primary id. Optional name_dob_ver Character (1) ification Guide to National Student Index - GINS 6.5-final.docx Page 119 of 148 Parameter Type Description Requirement residential_stat Character (1) us The residential status of the student. NZ Citizen, NZ Permanent resident, Australian citizen, Overseas or Unknown. Optional. residential_stat Character (1) us_verification The residential status verification. Can be Unverified, Passport, Birth Cert, or Other primary id. Optional alternative_sur name Character (100) The last name of an alternative name used by the student Optional alternative_for ename1 Character (100) The first name of an alternative name used by the student Optional alternative_for ename2 Character (100) The second name of an alternative name used by the student Optional alternative_for ename3 Character (100) The third name of an alternative name used by the student Optional alternative_pre ferred_name_i ndicator Character (1) Y or N specifying whether this Optional alternative name is the preferred name. override_code Character (10) Indicates that the record should be added despite the known existence of a partially matching record/s already in the NSI database. The value will be the same as that returned by a previous attempt to add the record Optional provider_refer ence Character (30) A reference passed from an SMS to the NSI in order for it to be returned in the output Optional Guide to National Student Index - GINS 6.5-final.docx Page 120 of 148 6.7.3.2 Outputs 6.7.3.2.1 Student Added / Definite Match Returned / successful update When no matching records are returned and the student record is added successfully OR a definite match is returned OR an update has been processed successfully, the result will contain either, the created student record, the updated student record or the matched student record. When a definite match is returned, the <student/> tag contains a full record. The format is: <?xml version=”1.0” encoding=”ISO-8859-1” ?> <result_list version=”1.0”> <result> <student> <nsn></nsn> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> <gender></gender> <preferred_name_indicator></preferred_name_indicator> <dob></dob> <name_dob_verification></name_dob_verification> <name_dob_verified_by></name_dob_verified_by> <residential_status></residential_status> <residential_status_verification></residential_status_verification > <residential_status_verified_by></residential_status_verified_by> <nzqa_paid></nzqa_paid> <dod></dod> <student_status></student_status> <created_date></created_date> <created_by_userid></created_by_userid> <created_by_provider_code></created_by_provider_code> <alternate_name> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> Guide to National Student Index - GINS 6.5-final.docx Page 121 of 148 <preferred_name_indicator></preferred_name_indicator> <name_dob_verification></name_dob_verification> <alternate_name></alternate_name> <override_code></override_code> <provider_reference></provider_reference> </student> </result> </result_list> 6.7.3.2.2 Possible Match(es) Returned Where a possible match is returned the <student/> tag is not reporting a new record inserted to the NSI. Instead it is reporting the information that has been submitted to the system as well as an override code. A <match_list> block will detail all matching students with a score above the NSI determined parameter for possible matches. The format is: <?xml version="1.0" encoding="ISO-8859-1"?> <result_list version="1.0"> <result> <student> <nsn><nsn/> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3> </forename3> <dob></dob> <name_dob_verification></name_dob_verification> <preferred_name_indicator/> <residential_status></residential_status> <residential_status_verification></residential_status_verification > <gender></gender> <override_code></override_code> <provider_reference></provider_reference> <alternate_name> <surname> <surname/> <forename1><forename1/> <forename2><forename2/> <forename3><forename3/> <preferred_name_indicator><<preferred_name_indicator/> <alternate_name></alternate_name> Guide to National Student Index - GINS 6.5-final.docx Page 122 of 148 </student> <match_list> <student> <nsn></nsn> <surname> </surname> <forename1> </forename1> <forename2></forename2> <forename3></forename3> <gender></gender> <preferred_name_indicator></preferred_name_indicator> <dob></dob> <name_dob_verification></name_dob_verification> <name_dob_verified_by></name_dob_verified_by> <residential_status></residential_status> <residential_status_verification></residential_status_verificatio n> <residential_status_verified_by></residential_status_verified_by> <nzqa_paid></nzqa_paid> <dod></dod> <student_status></student_status> <created_date></created_date> <created_by_userid> </created_by_userid> <created_by_provider_code></created_by_provider_code> <ranking></ranking> <match_indicator></match_indicator> </student> </match_list> </result> </result_list> 6.7.3.2.3 Batch XML Error Codes When an error has occurred with the submitted information, the submitted details of the student will be returned in the <student> tag, followed by the error details in <error> tags as detailed below: All error codes output by the batch XML interface are in the following format: <?xml version=”1.0” encoding=”ISO-8859-1” ?> <result_list version=”1.0”> <result> <student> <nsn></nsn> Guide to National Student Index - GINS 6.5-final.docx Page 123 of 148 <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> <gender></gender> <preferred_name_indicator></preferred_name_indicator> <dob></dob> <name_dob_verification></name_dob_verification> <name_dob_verified_by></name_dob_verified_by> <residential_status></residential_status> <residential_status_verification></residential_status_verification > <residential_status_verified_by></residential_status_verified_by> <nzqa_paid></nzqa_paid> <dod></dod> <student_status></student_status> <created_date></created_date> <created_by_userid></created_by_userid> <created_by_provider_code></created_by_provider_code> <alternate_name> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> <preferred_name_indicator></preferred_name_indicator> <name_dob_verification></name_dob_verification> <alternate_name></alternate_name> <override_code></override_code> <provider_reference></provider_reference> </student> <error> <code></code> <description></description> </error> </result> </result_list> 6.7.3.2.4 Processing statistics The batch file will contain statistics on the processing of the file: Guide to National Student Index - GINS 6.5-final.docx Page 124 of 148 <stats> <new_nsns_issued></new_nsns_issued> <matches_not_requiring_manual_intervention></matches_not_requiring_m anual_intervention> <matches_requiring_manual_intervention></matches_requiring_manual_in tervention> <records_updated></records_updated> <records_failed_validation></records_failed_validation> <total_records_processed></total_records_processed> </stats> <?xml version=”1.0” encoding=”ISO-8859-1” ?> <result_list version=”1.0”> <result> <criteria> <nsn></nsn> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> <dob></dob> <gender></gender> <residentialstatus></residentialstatus> <provider_reference></provider_reference> </criteria> <error> <code></code> <description></description> </error> </result> </results_list> Errors will be returned in NSI XML responses depending on where the error occurred in the input block, usually at the record level. This means that they will appear just inside the end of a record tag (as shown above). Guide to National Student Index - GINS 6.5-final.docx Page 125 of 148 6.7.4 Merge Request The following sections detail the input and output requirements for XML Merge Request batch files. 6.7.4.1 Inputs <?xml version="1.0" encoding="ISO-8859-1" ?> <student_list version=”1.0”> <student> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> </student> </student_list> A minimum of 2 and maximum of 10 NSI records can be submitted within one merge request. Any number of merge request groups can be submitted in a batch merge request file. All 10 <nsn> tags are not required when submitting a batch merge request. For example, a request to have two records merged need only contain two <NSN> tags. The number of tags required depends on the number of duplicate records. So if there are only two duplicates which the organisation wishes to merge together, you should only submit two tags. The following detail describes the XML tags detailed above to guide users of this document who may not be familiar with XML (this table does not describe data fields) Tag Description <?xml version="1.0" encoding="ISO-8859-1" ?> Common XML header <student_list version= "1.0"> Start of list of student records <student> Start of student record within list of students </student> End of student record within list of students Guide to National Student Index - GINS 6.5-final.docx Page 126 of 148 The following table details the data fields associated to each of the input fields described above. The table details the data type of the field, the description of that field and the business requirement for including the field in the request file. Field Type/Length Description Requirement nsn1 32-bit signed Integer NSN of a record to be included in the set of records to be merged Mandatory nsn2 32-bit signed Integer NSN of a record to be included in the set of records to be merged Mandatory nsn3 32-bit signed Integer NSN of a record to be included in the set of records to be merged Optional Up to 10 NSN’s can be included in a merge request. NSN’s 4 – 10 will be validated as per NSN3 above. Guide to National Student Index - GINS 6.5-final.docx Page 127 of 148 6.7.4.2 Outputs The <request_string/> returned will contain the details previously submitted in the <student/> XML tag as shown above. 6.7.4.2.1 Records merged successfully <?xml version=”1.0” encoding=”ISO-8859-1” ?> <result_list version=”1.0”> <result> <request_string> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> </request_string> <new_master_nsn></new_master_nsn> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> </result> 6.7.4.2.2 Merge rejected/Manual Intervention required/Error returned In the case of a rejected merge request or a merge request that requires manual intervention, the information contained in the request file will be returned in the results file along with the appropriate message code and description. <result> <request_string> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> Guide to National Student Index - GINS 6.5-final.docx Page 128 of 148 <nsn></nsn> <nsn></nsn> <nsn></nsn> </request_string> <error_code></error_code> <error_description></error_description> </result> 6.7.4.2.3 Processing Statistics Below the result_list element, the batch file will contain statistics on the processing of the file: <stats> <successful_merge></successful_merge> <rejected_merge></rejected_merge> <manual_intervention_required></manual_intervention_required> <total_records_processed></total_records_processed> </stats> Tags for XML formatting (not data fields) Tag Description <?xml version="1.0" encoding="ISO-8859-1" ?> Common XML header <result_list version= "1.0"> Start of result list </result_list> End of result list <result> Start of result record within results list </result> End of result record within results list <stats> Start of statistics for batch file </stats> End of statistics for batch file Guide to National Student Index - GINS 6.5-final.docx Page 129 of 148 6.7.5 Student-Provider Relationship (ATA) Add/Update The following sections detail the requirements for ATA Batch files in XML format. 6.7.5.1 Inputs XML files will be formatted as follows: <?xml version=”1.0” encoding=”ISO-8859-1” ?> <active_at version=”1.0”> <student> <provider_code></provider_code> <nsn></nsn> <active_until_date></active_until_date> </student> </active_at> The following detail describes the XML tags detailed above to guide users of this document who may not be familiar with XML (this table does not describe data fields) Tags for XML formatting (not data fields) Tag Description <?xml version="1.0" encoding="ISO-8859-1" ?> Common XML header <active_at version= "1.0"> Start of list of active at records <student> Start of active at record within list </student> End of active at record within list </active_at > End of list of active at records 6.7.5.1.1 Data Fields The following table details the data fields associated to each of the input fields described above. The table details the data type of the field, the description of that field and the requirement for including the field in the request file. Guide to National Student Index - GINS 6.5-final.docx Page 130 of 148 Parameter Type Description Requirement provider_code Character(10) The Ministry assigned provider code. Conditionally Mandatory (This is the provider the SPR is to be set up with. Default is the user’s Provider organisation. If supplied, the user’s provider organisation must be authorised to submit Student Provider relationships ‘on behalf’ of other organisations.) nsn 32-bit signed Integer The NSN of the student to search for. Mandatory. Valid date in format yyyymmdd e.g. 19890621 Optional. If not provided use the default active at period as set in the Provider Details for the uploading organisation (if provided), otherwise the organisation associated with the user sending the request. active_until_da Character(8) te Guide to National Student Index - GINS 6.5-final.docx Page 131 of 148 6.7.5.2 Outputs 6.7.5.2.1 Successful Active At creation For a successful Active At creation, no message is reported back to the user. 6.7.5.2.2 Errors returned Where an error has occurred, the criteria submitted in the request will be returned followed by the appropriate error code and description. <?xml version=”1.0” encoding=”ISO-8859-1” ?> <result_list version=”1.0”> <result> <criteria> <provider_code></provider_code> <nsn></nsn> <active_until_date></active_until_date> </criteria> <error> <code></code> <description></description> </error> </result> </result_list> 6.7.5.2.3 Processing statistics Statistics are returned for all result files (errors and successful additions). <stats> <provider_success> <provider> <provider_code></provider_code> <created_or_updated></created_or_updated> </provider> </provider_success> <provider_failure> <provider> <provider_code></provider_code> <created_or_updated></created_or_updated> </provider> </provider_failure> <records_created_or_updated></records_created_or_updated> <records_failed_validation></records_failed_validation> Guide to National Student Index - GINS 6.5-final.docx Page 132 of 148 <total_records_processed></total_records_processed> </stats> Tags for XML formatting (not data fields) Tag Description <?xml version="1.0" encoding="ISO-8859-1" ?> Common XML header <result_list version= "1.0"> Start of result list </result_list> End of result list <result> Start of result record within results list </result> End of result record within results list <criteria> Start of active at record within list </criteria> End of active at record within list <error> Start of error record for student </error> End of error record for student <stats> Start of statistics for batch file </stats> End of statistics for batch file Guide to National Student Index - GINS 6.5-final.docx Page 133 of 148 6.7.6 Change Notifications The following sections detail the XML Change Notification batch files. There are no related Change Notification inputs. 6.7.6.1 Inputs N/A 6.7.6.2 Outputs Changed records and merge denials are both reported back to organisations in the same XML block, as shown here: <notification_list> <update_notification_list> <update_notification> <modified_date></modified_date> <nsn></nsn> <master_nsn></master_nsn> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3></forename3> <preferred_name_indicator></preferred_name_indicator> <gender></gender> <dob></dob> <dod></dod> <name_dob_verification></name_dob_verification> <residential_status></residential_status> <residential_status_verification></residential_status_verification > <nzqa_paid></nzqa_paid> <student_status></student_status> <modified_by_provider_code></modified_by_provider_code> <changed_field_indicator></changed_field_indicator> </update_notification> </update_notification_list> <merge_denied_list> <merge_denied> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> Guide to National Student Index - GINS 6.5-final.docx Page 134 of 148 <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> </merge_denied> </merge_denied_list> </notification_list> Guide to National Student Index - GINS 6.5-final.docx Page 135 of 148 7 Appendix B: Glossary of Terms BDM Births Deaths and Marriages The BDM Office registers all births, deaths and marriages which take place in New Zealand, and provides access to this registered information through a variety of products and services. BDM also provides a number of other services, including changes of name by statutory declaration and the appointment of marriage celebrants. The BDM Office is a section of the Department of Internal Affairs (see below). DIA The Department of Internal Affairs The New Zealand government department that works to: · safeguard and strengthen communities · support executive and local government · provide New Zealanders with records of personal identity · ensure gaming is fair, legal and honest. HTTPS Secure Hypertext transfer protocol HTTPS is a Web protocol developed by Netscape and built into its browser that encrypts and decrypts user page requests as well as the pages that are returned by the Web server. HTTPS is really just the use of Netscape's Secure Socket Layer (SSL) as a sub layer under its regular HTTP application layering. (HTTPS uses port 443 instead of HTTP port 80 in its interactions with the lower layer, TCP/IP.) SSL uses a 40-bit key size for the RC4 stream encryption algorithm, which is considered an adequate degree of encryption for commercial exchange NCEA National Certificates of Education Achievement An NCEA is a standards-based qualification that will attest to a broad range of New Zealand Curriculum related education outcomes. There are three National Certificates of Educational Achievement: Level 1 NCEA, Level 2 NCEA, and Level 3 NCEA. A student will be awarded a National Certificate when she/he has accumulated sufficient credits by being successfully assessed against NQF standards. NSN National student number The unique identifier for a record in the NSI system. ROA Record of Achievement An individual learner's transcript of unit standards credited and national qualifications completed, provided by NZQA from a national database. REST REpresentation State Transfer (REpresentation State Transfer) is a common standard for online interfaces. It uses a definition of a resource (e.g. a student), and allows a range of actions for it. SMS Student management system System that exists for organisations to enrol and retain information on their students. SOAP Simple object access protocol Guide to National Student Index - GINS 6.5-final.docx Page 136 of 148 SOAP is a way for a program running in one kind of operating system (such as Windows 2000) to communicate with a program in the same or another kind of an operating system (such as Linux) by using the World Wide Web's Secure Hypertext Transfer Protocol (HTTPS) and its Extensible Markup Language (XML) as the mechanisms for information exchange. STEO Services for tertiary education organisations The Ministry’s Tertiary website which provides password-controlled access to the Course Register, Qualifications Register, NZSCED and the Single Data Return Validation Program. TEC Tertiary Education Commission The Tertiary Education Commission (TEC) Te Amorangi Matauranga Matua, is a crown entity established under the provisions of the Education (Tertiary Reform) Amendment Act 2002. TEC is responsible for funding all post-compulsory education and training offered by universities, polytechnics, colleges of education, wananga, private training establishments, foundation education agencies, industry training organisations and adult and community education providers. UNICODE Unicode Standard Character Coding System The Unicode standard is a character coding system designed to support the interchange, processing, and display of the written texts of diverse languages. URL Uniform Resource Locator A URL is the address of a file (resource) accessible on the Internet. The type of resource depends on the Internet application protocol. Using the World Wide Web's secure protocol, the Secure Hypertext Transfer Protocol (HTTPS), the resource can be an HTML page (like the one you're reading), an image file, a program such as a common gateway interface application or Java applet, or any other file supported by HTTPS. The URL contains the name of the protocol required to access the resource, a domain name that identifies a specific computer on the Internet, and a hierarchical description of a file location on the computer. UTF-8 Unicode Transformation Format 8-bit encoding form UTF-8 is the Unicode Transformation Format that serializes a Unicode scalar value (code point) as a sequence of one to four bytes. XML Extensible mark up language XML is a flexible way to create common information formats and share both the format and the data on the World Wide Web, intranets, and elsewhere. For example, computer makers might agree on a standard or common way to describe the information about a computer product (processor speed, memory size, and so forth) and then describe the product information format with XML. Such a standard way of describing data would enable a user to send an intelligent agent (a program) to each computer maker's Web site, gather data, and then make a valid comparison. XML can be used by any individual or group of individuals or companies that wants to share information in a consistent way. Guide to National Student Index - GINS 6.5-final.docx Page 137 of 148 8 Appendix C: Error Codes The following table lists all errors that can be returned from the NSI from the external interfaces (XML, SOAP, Batch and REST). This table is up to date as at 08/12/2014. Note: Error codes output via the SOAP interface will be output as the NSI message code minus an offset of 2146828288. This rule applies to all messages returned through each SOAP function. e.g. Message code ‘528’ is output as ‘-2146827760’ Notes: Errors returned through the automated batch upload function only return message descriptions without the message codes. Message descriptions that include “{}” are dynamic messages, where the “{}” can be populated with various values i.e. the message will be returned for various fields Some REST messages consist of a single message with another message embedded within the description that provides more information. These relate to the following messages: o Message #956 can be embedded with: Message #338 or Message #897 o Message #915 can be embedded with: Message #916 or, Message #898 or, Message #899 or, Message #902 or, Message #903 or, Message #944 Code 2 Interface2 Message Value 0 B Success. 012 R Please enter a minimum of two names, or one name and a birth date. Birth date, Gender and Residential status may only be used in conjunction with at least one name. 013 B Type mismatch. B = Batch, R = REST Guide to National Student Index - GINS 6.5-final.docx Page 138 of 148 Code Interface2 Message Value 021 R Record(s) that closely match this record have been found. Please confirm whether you wish to add this record. 023 R Name & birth date and Residential status verification cannot be set to anything other than 'Unverified' when 'Birth date' and / or Residential status is 'Unknown'. 025 R Student record successfully saved. 027 R Names which exactly match another name on the student record cannot be added. 034 R This record contains verified name and birth date information. If you wish to update this information please raise a challenge. 055 R Student records have been automatically merged. The master record is {0}. 060 R No such Provider exists. Please check and re-enter. 074 B Please ensure the file you are uploading has either a .txt or .xml extension. 075 B Please ensure the file you are uploading has either a ATA, SEA, MER, or UPI prefix. 076 B Please ensure the file you are uploading has a ATA, SEA, or MER or UPI prefix then 5 characters then a ‘.txt’ or ‘.xml’ extension. 088 R You have been logged out of the NSI. 256 B {0} is invalid. 257 B,R Please enter values for the following mandatory field(s):\n{0} 258 S NSN required to update an NSN record. 259 B Name, DoB, Residential Status and Gender cannot be supplied as search criteria with NSN. 272 B,R {0} must only contain alphabetic characters, space, hyphen, apostrophe or a single '~'. Space hyphen and apostrophe cannot be used without another character or repeated. Names must start with an apostrophe or an alphabetic character. 273 B Verification Flag cannot be set without corresponding data. 274 B Cannot modify verified data. 275 B,R Invalid verification flag. 276 B,R Verification Flag cannot be set to BDM. 277 R You cannot update {0} when {1} is 'Birth register'. 279 B,R {0} cannot be changed from a verified value to 'Unverified'. Guide to National Student Index - GINS 6.5-final.docx Page 139 of 148 Code Interface2 Message Value 280 B Birth date AND name details may not be updated together. If required, submit the updates & supporting information as a Challenge to nsi.unit@education.govt.nz using the student NSN as a reference number. 281 B BDM verification flags cannot be changed. 288 B,R Invalid gender. 290 B,R Cannot change Ministry of Education verified data. 304 B,R Invalid date format. 305 B,R You must have permission to update this field. {0} must be earlier than today's date and be in one of the following formats: dd/mm/yyyy, yyyymmdd or yymmdd. 309 B,R Residential status is invalid. 320 B,R Preferred name indicator is invalid. 321 B,R Preferred name indicator set for more than one name. 336 B,R Invalid NSN. 337 B,R NSI record {0} does not exist. 338 B,R {0} is already a slave of record {1}. Slave records cannot be merged. 339 R Invalid Provider Code. Only Standard characters (A-Z, 0-9) are permitted. Leading or trailing spaces are not permitted. 352 B Request failed to be lodged with NSI Unit - too few records identified in group (minimum is 2). 353 B,R A maximum of ten unique student records can be included in a merge request. 369 B BDM verified fields cannot be modified. 370 B,R NSI Record is inactive and cannot be updated. 409 R Unexpected validation Error. 416 B Incorrect File Format. 417 B Incorrect Format for file footer record. 418 B Incorrect Record Format. 422 B,R NSN found is a slave record. 423 B,R Student Provider Relationship period is out of range. 424 B Invalid provider code. 513 B,R Invalid user name or password. 515 B,R Organisation is not valid for user. Guide to National Student Index - GINS 6.5-final.docx Page 140 of 148 Code Interface2 Message Value 521 B,R The {0} interface is not enabled for you. 528 B,R Session has timed out, or session not established. 529 B,R Access denied. 768 B Unexpected validation error. 769 B {0} is not a valid XML command. 784 R More than {0} records have been found matching the search criteria. The top {0} records have been returned. Please refine your search criteria. 785 B,R No search results found. 789 B,R A system fault means that the NSI is temporarily unavailable. If the problem persists contact the MoE Service Desk. Please accept our apologies for any inconvenience. 800 B Update denied student has been merged. 817 R Your merge request has been forwarded to the NSI Team. Can you please forward supporting documentation through to nsi.unit@education.govt.nz 818 B {0} exist in the merge denied list. Merge request requires manual intervention. 819 R At least two unique student records are required for merge. 820 B Merge request requires manual intervention. 821 B Merge request cannot be processed – invalid status. 822 B NSN records >1 NSI records have NZQA paid flag set to Y or N ({0}, {1}) have got NZQA paid flag set to Y or N. Merge request requires manual intervention. 823 B Merge request includes BDM verified records. Merge request requires manual intervention. 897 R The following NSN(s) are included in a merge request that is currently awaiting processing and cannot be merged. {0} 898 R The following NSN(s) have been verified by the Birth register: {0} 899 R The following NSN(s) have been previously denied: {0} 902 R Records in the merge group are not a close enough match for automatic merging. 903 R The following NSN(s) have current challenges: {0} 915 R Merge request requires manual intervention for the following reason(s). Please contact the MoE Service Desk if you require more information. Guide to National Student Index - GINS 6.5-final.docx Page 141 of 148 Code Interface2 Message Value 916 R The following NSN(s) have an Inactive status: {0} 921 R Record(s) that match this record have been found. Please review match(es) returned. If you wish to have a new record added, the information and verification must be submitted to the MoE Service Desk as a Challenge of the existing student details. The NSI team will process your challenge via e-mail. Supporting information can be forwarded separately to nsi.unit@education.govt.nz using the student NSN as a reference number. 934 R You are attempting to change the Birth date AND name details of this student. If you wish to continue with this update the information and verification must be submitted to the MoE Service Desk as a Challenge of the existing student details. The NSI team will process your challenge via e-mail. Supporting information can be forwarded separately to nsi.unit@education.govt.nz using the student NSN as a reference number. 938 R This student is part of a merge request that is awaiting processing - Contact the MoE Service Desk if you require further information. 939 R Student record successfully saved. Please note this record has an unknown birth date. 941 R Student record successfully saved. Please note this record has 'Unverified' details. 942 R Invalid override code. 943 R Student record successfully saved. Please note verified Residential status details have been updated. 944 R The following NSN's have student provider relationships with NZQA: {0}. The following NSN's don’t have student provider relationships with NZQA: {1} 945 R Birth date cannot be today's date. 951 R {0} cannot be later than current date. 953 B Unknown File Type {0} 954 B Incorrect file extension (.xml/.txt) 955 B Your file name should have 1 to 5 characters after the 3 letter prefix. {0} 956 R Merge request has been rejected. 957 R Birth date cannot be modified. 1282 R NSN record has not been modified. Guide to National Student Index - GINS 6.5-final.docx Page 142 of 148 Code Interface2 Message Value 1283 R You cannot access the NSI. Your organisation's Go Live date has not yet been reached. Please contact the MoE Service Desk. 1284 B FILE SUCCESSFULLY UPLOADED Please Note: It is recommended that systems are developed to interpret message codes, not message text. Message text may change over time. Guide to National Student Index - GINS 6.5-final.docx Page 143 of 148 9 Appendix D: Related Documents The following is a list of links to documents which relate to integration with the NSI. 9.1 Web Interface User Guide The best place to learn more about how to use and navigate around the NSI web interface is the NSI Web Interface User Guide. The latest version of this guide is available for download from the Ministry of Education’s website. Or contact Service.Desk@education.govt.nz or call 0800 422 599 to request a copy. 9.2 NSI Web UI Learning Module An online NSI Web UI Learning Module has been developed for Web UI users. Providers using an in house or vendor Student Management System may also find this useful to look over. It is available from the Ministry of Education’s website. This module will show you how to work through the common processes within the NSI web interface. The module will take you approximately 20 to 25 minutes to work through. 9.3 NSI Web UI Quick Reference Guide (QRG) This QRG for the NSI application is a short check list covering the basic business activities for Web UI users. It is available from the Ministry of Education’s website. 9.4 ESAA Application Form You can download an ESAA application form from the Ministry’s STEO website at http://info.identity.education.govt.nz/esaa/ Guide to National Student Index - GINS 6.5-final.docx Page 144 of 148 10 Appendix E: REST Code Example The following contains code examples of how to consume the REST service in NSI. This example is supplied here as is and is not the only way that the REST interface can be consumed, nor is this necessarily the recommended way to consume the REST interface. 10.1 Encode username and password Get a Base64 Encoded string of your login details. Encode your username and password in this format: Username:Password public static string Base64Encode(string plainText) { var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(plainText); return System.Convert.ToBase64String(plainTextBytes); } For example: var plainTextBytes = System.Text.Encoding.UTF8.GetBytes("STNSIUNIT1:myPassword123"); string ss = System.Convert.ToBase64String(plainTextBytes); returns: ss = U1ROU0lVTklUMTpteVBhc3N3b3JkMTIz== 10.2 Get Authentication token from ESAA Get Authentication token using User ID and the Encoded string - calling ESAA //Get access token using (var client = new HttpClient()) { var parameters = new Dictionary<string, string> { { "grant_type", "client_credentials" }, { "end_user_id", username}, //username e.g STNSIUNIT1 { "scope", "APP_NSI2" } }; Uri theUriHost = new Uri("https://ppsecurity.education.govt.nz/oauth2/access_token?"); //Building the Uri var builder = new UriBuilder(theUriHost.ToString()); var query = HttpUtility.ParseQueryString(builder.Query); Guide to National Student Index - GINS 6.5-final.docx Page 145 of 148 //Add parameters to Uri foreach (KeyValuePair<string, string> value in parameters) { query[value.Key] = value.Value; } builder.Query = query.ToString(); string url = builder.ToString(); // url ends up like this: https://SECURITY.education.org.nz/oauth2/access_token?grant_type=client_credentia ls&end_user_id= STNSIUNIT1&scope=APP_NSI2 //Adding the headers client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", encodedUserLogin); //encodedUserLogin is the string returned in step 1 client.DefaultRequestHeaders.Host = theUriHost.Host; var content = new FormUrlEncodedContent(parameters); var response = await client.PostAsync(url, content); //await allows you to do parallel processing while the application is awaiting a reponse from the server } The reponse will include an access token which is used for the login request. An example is shown below. { "token_type": "Bearer", "access_token": "N0Y1HGVCRjUtMERFDC1BN0Y0LTY2MDUtCzRFQjMyAzIyMDQ3" } 10.3 Create an NSI session Create an NSI session using authentication token - returns NSI session token in response header //Request NSI session using (var client = new HttpClient()) { Uri theUri = new Uri("https://nsi.compliance.education.govt.nz/api/v1/session"); //Adding the headers client.DefaultRequestHeaders.Accept.Clear(); client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); client.DefaultRequestHeaders.Host = theUri.Host; var parameters = new Dictionary<string, string> { Guide to National Student Index - GINS 6.5-final.docx Page 146 of 148 from the { "EsaaAccessToken", responseTokens["access_token"]}, //Using the access token reponse in step 2 { "OrgId", "-1" } }; var content = new FormUrlEncodedContent(parameters); var response = await client.PostAsync(theUri, content); } The reponse will send back an NSISessionToken in the header; this token will be used in all subsequent requests (Search student, Update student, Add student, Logout etc) for NSI. It looks something like this: 1239495d-b059-12f2-bd1f-39d0114a7e02 10.4 Send NSI request Use NSI session token in request header for your request e.g. search, update etc //(GET) Search student by NSN using (var client = new HttpClient()) { String studentToSearch = nsnNumber; String uriWithStudent = "https://nsi.compliance.education.govt.nz/api/v1/student/" + studentToSearch; Uri theUri = new Uri(uriWithStudent); //Adding the headers client.DefaultRequestHeaders.Accept.Clear(); client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); //Could be xml client.DefaultRequestHeaders.Add("NSISessionToken", responseTokens["NSISessionToken"]); client.DefaultRequestHeaders.Host = theUri.Host; var response = await client.GetAsync(theUri); } Searching a student in the system by their NSN number. Put the NSISessionToken into the header of the request to do search. 10.5 Logout using NSI session token in request header using (var client = new HttpClient()) { Uri theUri = new Uri("https://nsi.compliance.education.govt.nz/api/v1/session"); client.DefaultRequestHeaders.Accept.Clear(); client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); Guide to National Student Index - GINS 6.5-final.docx Page 147 of 148 client.DefaultRequestHeaders.Add("NSISessionToken", responseTokens["NSISessionToken"]); client.DefaultRequestHeaders.Host = theUri.Host; Console.WriteLine("Loggingout"); var response = await client.DeleteAsync(theUri); Using Delete operation and the NSISession Token in the header to log the user out. Guide to National Student Index - GINS 6.5-final.docx Page 148 of 148