NATIONAL STUDENT INDEX

Transcription

1 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.9 October 2017 National Student Index c/- Education Service Desk Ministry of Education P O Box 1666 Wellington Guide to National Student Index - GINS 6 9 final.docx Page 1 of 162

2 Table of Contents Table of Contents Introduction Document Purpose Document Audience Interface Support Contacts Document Revision History Getting Started What is the National Student Index? National Student Index queries What can the NSI system be used to do? What is an NSI Record? Who needs an NSI Record? How do Organisations find out about changes to NSI Data? How can the NSI System be accessed? Web Interface REST Interface Batch File Interface What is the difference between the Web, REST and Batch Interfaces? What is the best NSI System Interface option for you? Integration Considerations What Next? NSI Functional Overview Introduction Unknown Birth Date Search Add / Insert Update Alternate Name Updates Updating Birth Date of NSI Records Name and Birth Date Verification Verified Residential Status Error Messages Editable Fields Multiple Field Updates Unverified NSI Records Notification of Updates Merge Request Guide to National Student Index - GINS 6 9 final.docx Page 2 of 162

3 3.7 Change Notifications Changed Field Indicator Challenge Create/Update Student Provider Relationships REST Interface What is REST? Accessing the API Authentication ESAA OAuth ESAA Environment URLS Education Sector Authentication Privilege levels Authentication and Authorisation Errors API Details Naming Standard Dates JSON Encoding Query string parameter encoding Result codes and messages REST API Resources Session Resource Student Functions The Student Resource REST Function Details Create NSI Session via REST Search Request via REST Add Student Record via REST Modify Student Record via REST Request to Merge Student Records via REST Create / Update Student Provider Relationship (SPR) via REST Logout of the NSI via REST Batch File Interface Overview Accessing the Batch interface Batch File Types Batch File Format File Naming Conventions Delimited File Footers Uploading/Downloading Batch Files Security and Authentication Batch File Functions Guide to National Student Index - GINS 6 9 final.docx Page 3 of 162

4 5.4.1 Search Request File Update/Insert Batch File Merge Request Batch File Change Notification Batch Files Student-Provider Relationship (Add / Update) Automated Upload/Download of Batch Files Login to the NSI through Batch Interface Logout from the NSI through the Batch Interface Automated Upload of Batch files Automated Download of Batch Files Delimited Batch File Formats Encoding Search Update/Insert Merge Request Student-Provider Relationship (ATA) Add / Update Change Notifications XML Batch File Formats Encoding Search Update/Insert Merge Request Student-Provider Relationship (ATA) Add/Update Change Notifications Appendix B: Glossary of Terms Appendix C: Error Codes and Triggers Appendix D: Related Documents Web Interface User Guide NSI Web UI Learning Module NSI Web UI Quick Reference Guide (QRG) ESAA/ESL Request Access Appendix E: REST Code Example Encode Username and Password Get Authentication Token from ESAA Create an NSI Session Send NSI Request Logout using NSI Session Token in Request Header Common Function Calls to ESAA and NSI Using REST Get Auth ESAA Token Create NSI Session Search Request NSN Guide to National Student Index - GINS 6 9 final.docx Page 4 of 162

5 9.6.4 Search Request Match Search (Name and DOB) Add Student Record Primary Record Details Only Add Student Record Primary and Alternate Name/s Modify - Primary Record Details Only Modify - Primary and Alternate Name/s Request to Merge Student Records Create/Update Student Provider Relationship Logout of NSI Guide to National Student Index - GINS 6 9 final.docx Page 5 of 162

6 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. 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/- Education Service Desk Ministry of Education P O Box 1666 Wellington or service.desk@education.govt.nz or phone: Guide to National Student Index - GINS 6 9 final.docx Page 6 of 162

7 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/ Various NSI Replacement Version released 22/12/ 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 Clarification in Section Clarification in Section Change of font in Section Clarification in Section Change of font in Section Corrected last tag in Section Clarifications and font change in Section Clarification in Appendix C - Error message /02/ Various Track changes removed Issued 11/02/ Various Tidy up of document for final release 01/05/ Various Accept all changes for final release of GINS 07/07/ Various Minor updates made to add further information for vendors Addition of the REST code example 09/07/ Various Accept all changes for release of GINS Guide to National Student Index - GINS 6 9 final.docx Page 7 of 162

8 Date Revision Sections Changed Description of Changes 22/07/ Various Remove the XML and SOAP Interface details into separate documents Update the REST code examples to reference the correct URLs 24/02/ Various Various - Update Service desk 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) Separated Alt Name from student resource Alternate Name(s) may be included in output from NSN search Update Resource URL 6.2 New section - Accessing the Batch Interface 10.1 Updated encoding result 24/2/ Various Accepted Tracked changes (v6.1) 07/03/ Accessing the API Corrected REST Production URL 01/06/ Added ESAA URL s as references for authentication 01/08/ Date formatting specs corrected. Removed leading space and added third milliseconds digit. 31/08/ Replaced revision 5.2 details in Revision History table Noted that sub messages in REST output do not include error codes (as built) (section 5.5 & section ) Version issued in conjunction with NSI v Guide to National Student Index - GINS 6 9 final.docx Page 8 of 162

9 Date Revision Sections Changed Description of Changes 30/11/ Various Added descriptions of ESAA user types Added note to advise using ~ (tilde) as given name (1) is accepted 3.3 Clarified that alternate names cannot be updated 3.5 Added in error message triggers sect 8 Appendix C 27/02/ Altered ESAA token URL. 20/10/ Various Version issued in conjunction with NSI v Plus updates resulting from REST migration testing feedback Alternate name updates: Verification may be updated Name and Birth date verification: Verification may be updated Verification Hierarchy: Section added Verified Residential status: Section added Modify Student Record via REST: Reference section 3.5 Update for name and birth date verification and alternate name values Batch URL updated Batch upload successful/unsuccessful behaviour REST URL and payload examples added section Guide to National Student Index - GINS 6 9 final.docx Page 9 of 162

10 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 Education 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 or 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 of Education, 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 Education Service Desk by providing appropriate documentation. 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 Guide to National Student Index - GINS 6 9 final.docx Page 10 of 162

11 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. 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. Guide to National Student Index - GINS 6 9 final.docx Page 11 of 162

12 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 Education Service Desk (phone or service.desk@education.govt.nz) The interface options are: 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 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. 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 9 final.docx Page 12 of 162

13 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 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. 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. Guide to National Student Index - GINS 6 9 final.docx Page 13 of 162

14 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. 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 NSI Batch Interface process may be used during peak enrolment periods to send and receive NSI data for that organisation s students 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 9 final.docx Page 14 of 162

15 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 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 Education 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 Education 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. Guide to National Student Index - GINS 6 9 final.docx Page 15 of 162

16 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 REST Interface and Batch File Interfaces are set out in the following sections: REST Interface refer to section 4 Batch File Interface refer to section 5 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 Interface 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 Education 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 Education 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 Education Service Desk will help you with the data load to ensure that the process is successful. 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 9 final.docx Page 16 of 162

17 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 User 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. 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). Guide to National Student Index - GINS 6 9 final.docx Page 17 of 162

18 The tilde symbol ~ can be used in addition to one single name when the student has only one name. The tilde symbol ~ should be input in the Given Name 1 field and the single name should be input in the Family name field. 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/ Claire Elizabeth Peterson 13/09/ 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/ 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 9 final.docx Page 18 of 162

19 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. 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 Guide to National Student Index - GINS 6 9 final.docx Page 19 of 162

20 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 Education 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 Alternate Name Updates Once an alternate name is added to a student record, it cannot be deleted by end users. If your customer wishes to update the verification of an existing alternate name, they should submit a modification request including the alternate name and verification value and the system will apply the update to the verification only. Multiple alternate names may be added in one transaction via the REST interface. If alternate name information is included this will be treated as an addition of a new alternate name. If your customer wishes to delete an alternate name, they need to request this from the Education Service Desk (either by or by raising a challenge). Guide to National Student Index - GINS 6 9 final.docx Page 20 of 162

21 3.5.2 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 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 Education Service Desk with supporting documentation to get the birth date updated. Where a user attempts to update a birth date through the Batch interface 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 # Name and Birth Date Verification Where an organisation has evidence that the verified details of a student differ to what is existing on the NSI record, they may update the verification providing that the new verification documentation is higher in the verification hierarchy. The verification hierarchy (relevance) is defined as (in descending order of relevance): a. Birth Register b. Verification confirmed by MoE Set to Yes or Verified by Provider is MoE c. Passport d. Birth Certificate e. Other Users will be able to update the verification of a name to a verification value that is equal or higher than the existing value via the Modify function Verified Residential Status Residential status information can be modified unless it is verified by Birth Register or by MoE Error Messages 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 Guide to National Student Index - GINS 6 9 final.docx Page 21 of 162

22 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 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 register Verified by MoE Verified (not Birth register) Unverified Primary name Locked Locked Locked Editable Birth date Locked Locked Locked (Unless user created the record see Update birth date rules.) Name & birth date verification Locked Locked Locked Editable Locked (unless user created the record or Birth date is Unknown see Update birth date rules) Residential Status. The top row specifies the value for Residential status verification: Residential status Residential status verification Birth register Verified by MoE Verified (not Birth register) Unverified Locked Locked Editable Editable Locked Locked Editable Editable Other Student fields can be updated as follows: Editable fields Gender Preferred name indicator Insert-able fields Alternative name Alternative name verification (not M Birth register) Guide to National Student Index - GINS 6 9 final.docx Page 22 of 162

23 Editable fields Record status and Reason (MoE only) Date of Death (MoE only) Insert-able fields 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. 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 Education 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. Guide to National Student Index - GINS 6 9 final.docx Page 23 of 162

24 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 the Education 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. 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 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 master_nsn 1 surname 2 forename1 4 forename2 8 forename3 16 gender 32 preferred_name_indicator 64 dob 128 dod 256 Decimal Value name_dob_verification 512 Guide to National Student Index - GINS 6 9 final.docx Page 24 of 162

25 Changed Field Decimal Value residential_status 1024 residential_status_verification 2048 nzqa_paid 4096 student_status 8192 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: search for the NSN, register a challenge, including the reason for the challenge. This will then be submitted to the Education Service Desk (NSI Team) for consideration. Supporting documentation can be ed 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 Education 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. Guide to National Student Index - GINS 6 9 final.docx Page 25 of 162

26 SPRs can be maintained through the REST and Batch Interfaces through the following services: REST: Create/update SPR Batch: ATA file upload. 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 Education Service Desk.) Guide to National Student Index - GINS 6 9 final.docx Page 26 of 162

27 4 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. 4.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. 4.2 Accessing the API Base URL for all API queries: 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: o Compliance: Example template for detailed queries: Base URL: 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 9 final.docx Page 27 of 162

28 4.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 9 final.docx Page 28 of 162

29 4.3.1 ESAA Environment URLS Environment URLs for production and compliance are: o Production: o Compliance: 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 Education Sector Authentication NSI access is governed by the Education Sector Access & Authentication application. This is the Sector s Identity and Access Management System. Each individual user of NSI must have an Education Sector Logon User account in the Education Sector Authentication application and this User account controls their access to functions within NSI. The Education Sector Access & Authentication application allows the provisioning of machine accounts or individual user accounts. If an organisation is accessing NSI via our machine interfaces (REST & BATCH), this will generally be via their SMS or other type of system), the provider will have one machine account for use by all individual users who access their SMS. It is an expectation of the Ministry that each SMS has inbuilt security at an individual user level although information about these individual users is not sent through to NSI. In this case the only the machine account name and organisation name will be visible in NSI (see example dated 17 Mar 2009 below). If a user is accessing NSI via our Web UI interface, they will have an individual user account. They will use this account each time they access NSI. In this case the individual User ID and organisation name will be visible in NSI. (see example dated 7 Dec 2007 below). Guide to National Student Index - GINS 6 9 final.docx Page 29 of 162

30 4.3.3 Privilege levels ESAA provides users with one of the following levels of NSI access: Student search only (read only) User able to make changes to NSI records (read/write) User able to make changes as NZQA user (read/write) Access to all API calls described in this document Authentication and Authorisation Errors The following messages will be returned where Authentication / authorisation has failed: Trigger 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) 4.4 API Details Naming Standard HTTP Code Response 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)>, "BirthDate": <birth date>, "NameBirthDateVerification: <name & birth date verification> } Dates Dates use the UTC format: yyyy-mm-ddthh:mm:ss 403 Guide to National Student Index - GINS 6 9 final.docx Page 30 of 162

31 E.g.: T14:35: 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 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.) 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 4.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 : [ { Guide to National Student Index - GINS 6 9 final.docx Page 31 of 162

32 ] } 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> } ] } Where an error consists of a parent message with various sub messages (e.g. message 915 & 817, 898, 899, 902, 903, 916, 944), only the parent message code will be returned, together with the message wording for the parent message and the sub messages. This will be returned in the format below: { MessageList : [ { MessageCode : <error/info code1>, MessageDescription : <error/info description1> - <error/info description2> - <error/info description3> } ] } Field Definitions Label / Field Type/Length Description MessageCode Alphanumeric (10) Relevant NSI message code MessageDescription Alphanumeric (300) Relevant NSI message description Guide to National Student Index - GINS 6 9 final.docx Page 32 of 162

33 4.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 Session Resource Available operations: Operation REST Verb Resource URL Create NSI Session POST session/ Logout DELETE session/ Student Functions Available operations: Operation REST Verb Resource URL Search GET Student/<NSN> Search GET Student/<Search params> AddStudent POST Student/ ModifyStudent PUT Student/ 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 Student { Response Body (JSON) "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>, "NameBirthDateVerifiedDate": <name birth date verified date>, "NameBirthDateVerificationConfirmedByMoe": <verification confirmed by moe (name & birth date verification)>, Guide to National Student Index - GINS 6 9 final.docx Page 33 of 162

34 Resource Response Body (JSON) "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. FamilyName Alphanumeric (100) The surname of the student found. Given1Name Alphanumeric (100) The first given name of the student found. Guide to National Student Index - GINS 6 9 final.docx Page 34 of 162

35 Field Type/Length Description 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 Unknown When a date is entered, format must meet the following format: Format: yyyy-mm-dd e.g NameBirthDateVer ification NameBirthDateVer ifiedby NameBirthDateVer ifieddate Alphanumeric (1) Alphanumeric (10) Read-only Date/Time (20) Read-only 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) The provider code of the provider that verified the name and birth date data. The date and time the Name & birth date verification was set for the student record Format: yyyy-mmddthh:mm:ss.mss e.g T14:35: Guide to National Student Index - GINS 6 9 final.docx Page 35 of 162

36 Field Type/Length Description NameBirthDateVer ificationconfirmed ByMoe Boolean Read-only 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 ResidentialStatus VerifiedBy ResidentialStatus VerifiedDate ResidentialStatus VerificationConfir medbymoe Alphanumeric (1) Alphanumeric (10) Read-only Date/Time (20) Read-only Boolean Read-only The method used to verify the residential status. Values can be: Unverified (U) Passport (P) Birth certificate (B) Birth Register (M) Other (O) The provider code of the provider that verified the Residential status. The date and time the Residential status verification was set for the student record Format: yyyy-mmddthh:mm:ss.mss e.g T14:35: 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 Guide to National Student Index - GINS 6 9 final.docx Page 36 of 162

37 Field Type/Length Description RecordStatus Alphanumeric (1) Read-only RecordStatusReas on Alphanumeric (100) Read-only CreatedDate Date/Time (20) Read-only CreatedByUserId Alphanumeric (200) Read-only CreatedByProvide rcode AltNameList Alphanumeric (10) Read-only The status of the record. Values can be: Active (A) Inactive (I) Description of record status. Values can be: In Use Deceased Created in error Do not use The date and time the record was created. Format: yyyy-mm-ddthh:mm:ss e.g T14:35:24 The User ID of the user that created the record. The associated provider code of the user that created the record See Field Definitions Alt Name The following are only displayed for student search (including Add prerequisite search): MatchScore Numeric (10) Read-only MatchIndicator Numeric (10) Read-only 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. 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. Guide to National Student Index - GINS 6 9 final.docx Page 37 of 162

38 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: AltNameBirthDate Verification Alphanumeric (1) true false 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 9 final.docx Page 38 of 162

39 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 ESAAAccessTok en <Defined by ESAA not an NSI field> Format: yyyy-mm-dd e.g ESAA Access Token as retrieved from OAuth. Guide to National Student Index - GINS 6 9 final.docx Page 39 of 162

40 4.7 REST Function Details The following sections specify the requirements for each function available for the REST interface 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 162

41 Create NSI Session Function - Inputs 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> } Input Data Fields Field Type/Length Description Requirement Content-Type ESAAAcessToken <Defined by ESAA not an NSI field> Indicates the "type" associated with the message body's byte sequence. Must read application/json ESAA Access Token as retrieved from OAuth. Mandatory Message #789 Mandatory Message #257 Message #513 OrgID Alphanumeric (10) Organisation ID of User logging in Mandatory Message #257 Message #339 Guide to National Student Index - GINS 6 9 final.docx Page 41 of 162

42 Create NSI Session Function Outputs 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 Create NSI Session HTTP Code Response Successful login 200 NSISessionToken <none> Response Header Response Body (JSON) Message Not authenticated 401 Result message details section 4.5 Message #513 Not authorised 403 Result message details section 4.5 Message #515 Message #521 Bad request 400 Result message details section 4.5 Message #257 Message #339 Message #1283 Bad syntax 500 Result message details section 4.5 Message #789 Guide to National Student Index - GINS 6 9 final.docx Page 42 of 162

43 4.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 Search Function Inputs Input Data Syntax (NSN Search) Operation REST Verb Resource URL Header payload Body Payload (JSON) Search GET Student/<NSN> NSISessionToken <none> 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 9 final.docx Page 43 of 162

44 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 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 9 final.docx Page 44 of 162

45 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 Unknown When a date is entered, format must meet the following format: yyyy-mm-dd e.g Optional, but can only be used if name is submitted Message #304 Message #305 Message #945 Message #951 Guide to National Student Index - GINS 6 9 final.docx Page 45 of 162

46 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 Matched Records 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) Message 200 NSISessionToken { Students : [ {Student Resource section 4.6.3} ], MessageList : [NULL] } Guide to National Student Index - GINS 6 9 final.docx Page 46 of 162

47 Operation Status Search Successful more than 100 matches found HTTP Code Response Response Header Response Body (JSON) Message 200 NSISessionToken { Students : [ {Student Resource section 4.6.3} ], MessageList : [ {Result message details section 4.5} ] } Message #784 Guide to National Student Index - GINS 6 9 final.docx Page 47 of 162

48 Errors 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 { Students : [NULL], MessageList : [ {Result message details section 4.5} ] } Bad request 400 NSISessionToken { Students : [NULL], MessageList : [ {Result message details section 4.5} ] } Message #785 Message #012 Message #257 Message #272 Message #304 Message #305 Message #337 Message #945 Message #951 Guide to National Student Index - GINS 6 9 final.docx Page 48 of 162

49 Operation Status HTTP Code Response Response Header Response Body (JSON) Message Not Authorised 401 NSISessionToken { Students : [NULL], MessageList : [ {Result message details section 4.5} ] } Message #257 Message #528 Guide to National Student Index - GINS 6 9 final.docx Page 49 of 162

50 4.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 Add Student Record Function Inputs Input Data Syntax Operation REST Verb Resource URL Header payload Body Payload (JSON) AddStudent POST Student/ Optional:?OverrideCode= <override code> Content-Type NSISessionToken { "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)>, Guide to National Student Index - GINS 6 9 final.docx Page 50 of 162

51 Operation REST Verb Resource URL Header payload Body Payload (JSON) "AltGiven2Name": <alternative given name (2)>, "AltGiven3Name": <alternative given name (3)>, "PreferredName": <alternative preferred name indicator>, "AltNameBirthDateVerification": <alternative name birth date verification> } ] } Input Data Fields Field Type/Length Description Requirement Content-Type 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 Guide to National Student Index - GINS 6 9 final.docx Page 51 of 162

52 Field Type/Length Description Requirement Given1Name Alphanumeric (100) The first given name of the student. Mandatory Message #257 Message #272 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 Gender Alphanumeric (1) The gender of the student. Values can be: Male (M) Female (F) Unknown (U) Mandatory Message #257 Message #409 Mandatory Message #257 Message #288 Guide to National Student Index - GINS 6 9 final.docx Page 52 of 162

53 Field Type/Length Description Requirement BirthDate Alphanumeric (20) The birth date of the student. Values can be: NameBirthDateVerific ation Alphanumeric (1) Date eg Unknown When a date is entered, format must meet the following format: Format: yyyy-mm-dd e.g The verification method used to verify the name and birth date. Values can be: Unverified (U) Passport (P) Birth certificate (B) Other (O) 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 #304 Message #305 Message #945 Message #951 Mandatory Message #257 Message #275 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) Mandatory Message #257 Message #409 Birth cert (B) Other (O) Guide to National Student Index - GINS 6 9 final.docx Page 53 of 162

54 Field Type/Length Description Requirement AltFamilyName Alphanumeric (100) The alternative family name for the student. Conditionally Mandatory if Alternative given name (1) is supplied Message #257 Message #272 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 Guide to National Student Index - GINS 6 9 final.docx Page 54 of 162

55 Field Type/Length Description Requirement PreferredName Boolean Value specifying that this name is the preferred name. Values can be: AltNameBirthDateVer ification Alphanumeric (1) true false The verification method used to verify the name and birth date. Values can be: Unverified (U) Passport (P) Birth certificate (B) Other (O) 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. Conditionally Mandatory. if Alternative family name is supplied Message #257 Message #409 Conditionally Mandatory. if Alternative family name is supplied Message #257 Message #275 Optional Message #942 Guide to National Student Index - GINS 6 9 final.docx Page 55 of 162

56 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 Successful Addition of a Student Record Where a record has been added successfully, the fields returned are as follows: Guide to National Student Index - GINS 6 9 final.docx Page 56 of 162

57 Output Function Syntax Operation Status HTTP Code Response Response Header Response Body (JSON) Message Add Successful 200 NSISessionToken { NSN : <NSN>, MessageList : [ {Result message details section 4.5} ] } Message #025 Message #939 Message #941 Guide to National Student Index - GINS 6 9 final.docx Page 57 of 162

58 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 Output Function Syntax Operation Status HTTP Code Response Response Header Response Body (JSON) Message Add Conflict 409 NSISessionToken { OverrideCode : <override code>, PossibleMatches : [ {Student resource see section 4.6.3} ], DefiniteMatchNSN : null, MessageList : [ {Result message details see section 4.5} ] } Message #021 Message #942 Guide to National Student Index - GINS 6 9 final.docx Page 58 of 162

59 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 Output Function Syntax Operation Status HTTP Code Response Response Header Response Body (JSON) Message Add Conflict 409 NSISessionToken { OverrideCode : null, PossibleMatches : null, DefiniteMatchNSN : <NSN>, MessageList : [ {Result message details see section 4.5} ] } Message #921 Guide to National Student Index - GINS 6 9 final.docx Page 59 of 162

60 Errors Output Function Syntax Operation Status HTTP Code Response Response Header Response Body (JSON) Message Add Bad request 400 NSISessionToken Result message details section 4.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 4.5 Forbidden 403 NSISessionToken Result message details see section 4.5 Bad syntax 500 NSISessionToken Result message details see section 4.5 Message #257 Message #528 Message #529 Message #789 Guide to National Student Index - GINS 6 9 final.docx Page 60 of 162

61 4.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 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 Input Data Syntax Operation REST Verb Resource URL Header payload Body Payload (JSON) Modify PUT Student/ Content-Type NSISessionToken { 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>, Guide to National Student Index - GINS 6 9 final.docx Page 61 of 162

62 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> } ] } Input Data Fields Field Type/Length Description Requirement Content-Type 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 Guide to National Student Index - GINS 6 9 final.docx Page 62 of 162

63 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 Gender Alphanumeric (1) The gender of the student. Values can be: Male (M) Female (F) Unknown (U) Optional Message #409 Optional Message #288 Guide to National Student Index - GINS 6 9 final.docx Page 63 of 162

64 Field Type/Length Description Requirement BirthDate Alphanumeric (20) The birth date of the student. Values can be: Date eg Unknown When a date is entered, format must meet the following format: yyyy-mm-dd e.g Optional Message #304 Message #305 Message #945 Message #951 *NameBirthDateVerifi cation Alphanumeric (1) The verification method used to verify the name and birth date. Values can be: Unverified (U) Optional Message #275 Passport (P) Birth certificate (B) Other (O) 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) Optional Message #409 Passport (P) Birth cert (B) Other (O) Guide to National Student Index - GINS 6 9 final.docx Page 64 of 162

65 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 9 final.docx Page 65 of 162

66 Field Type/Length Description Requirement PreferredName Boolean Value specifying that this name is the preferred name. Values can be: *AltNameBirthDateVe rification Alphanumeric (1) true false The verification method used to verify the name. Values can be: Unverified (U) Passport (P) Birth certificate (B) Other (O) *For more information on updating these fields see section 3.5 Update Conditionally Mandatory if Alternative family name is supplied Message #257 Message #409 Conditionally Mandatory if Alternative family name is supplied Message #257 Message #275 Guide to National Student Index - GINS 6 9 final.docx Page 66 of 162

67 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 Successful modification Where a record has been modified successfully, the fields returned are as follows: Output Function Syntax Operation Status HTTP Code Response Modify Successful 200 NSISessionToken { Response Header Response Body (JSON) Message } Student resource Section 4.6.3, MessageList : [ {Result message details section 4.5} ] Message #025 Message #938 Message #939 Message #941 Message #943 Guide to National Student Index - GINS 6 9 final.docx Page 67 of 162

68 Unsuccessful modification 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 4.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 9 final.docx Page 68 of 162

69 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 4.5 Message #257 Message #528 Forbidden 403 NSISessionToken Result message details section 4.5 Message #529 Bad Syntax 500 NSISessionToken Result message details section 4.5 Message #789 Guide to National Student Index - GINS 6 9 final.docx Page 69 of 162

70 4.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 Request to Merge Student Record Function Inputs 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> },...] } Input Data Fields Field Type/Length Description Requirement Content-Type Indicates the "type" associated with the message body's byte sequence. Must read application/json Guide to National Student Index - GINS 6 9 final.docx Page 70 of 162 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

71 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 9 final.docx Page 71 of 162

72 Request to Merge Student Record Function Outputs 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 Merge request Successful Merge automatically approved Successful Merge sent for Manual Intervention Response Header Response Body (JSON) Message 200 NSISessionToken Result message details section 4.5 Message # NSISessionToken Result message details section 4.5 Parent Message: Message #915 Sub-messages (wording only no codes): Message #817 Message #898 Message #899 Message #902 Message #903 Message #916 Message #944 Guide to National Student Index - GINS 6 9 final.docx Page 72 of 162

73 Operation Status HTTP Code Response Successful Merge Rejected Response Header Response Body (JSON) Message 200 NSISessionToken Result message details section 4.5 Parent message: Message #956 Sub-messages (wording only no codes): Message #897 Message #338 Bad request 400 NSISessionToken Result message details section 4.5 Message #257 Message #337 Message #353 Message #819 Message #956 Unauthorised 401 NSISessionToken Result message details section 4.5 Message #257 Message #528 Forbidden 403 NSISessionToken Result message details section 4.5 Message #529 Bad Syntax 500 NSISessionToken Result message details section 4.5 Message #789 Guide to National Student Index - GINS 6 9 final.docx Page 73 of 162

74 4.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 Create / Update Student-Provider Relationship Function Inputs 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> } Input Data Fields Field Type/Length Description Requirement Content-Type 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 Guide to National Student Index - GINS 6 9 final.docx Page 74 of 162

75 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 9 final.docx Page 75 of 162

76 Field Type/Length Description Requirement ActiveUntilDate Date/Time (20) Date student provider relationship will expire yyyy-mm-dd e.g 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 9 final.docx Page 76 of 162

77 Create / Update Student-Provider Relationship Function Outputs 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 Student Provider Relationship Successful 200 NSISessionToken <none> Response Header Response Body (JSON) Message Bad Request 400 NSISessionToken Result message details section 4.5 Message #060 Message #257 Message #304 Message #305 Message #337 Message #339 Message #409 Message #422 Unauthorised 401 NSISessionToken Result message details section 4.5 Message #257 Message #528 Forbidden 403 NSISessionToken Result message details section 4.5 Message #529 Bad Syntax 500 NSISessionToken Result message details section 4.5 Message #789 Guide to National Student Index - GINS 6 9 final.docx Page 77 of 162

78 4.7.7 Logout of the NSI via REST This function ends a session with the NSI system by logging the user out 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 Input Data Syntax Operation REST Verb Resource URL Header payload Body Payload (JSON) Logout DELETE session/ <NSISessionToken> none 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 9 final.docx Page 78 of 162

79 Logout Function Outputs 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 Response Header Response Body (JSON) Error Logout Successful logout 200 Result message details section 4.5 Message #088 Not Authorised 401 Result message details section 4.5 Message #257 Message #528 Guide to National Student Index - GINS 6 9 final.docx Page 79 of 162

80 5 Batch File Interface 5.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. 5.2 Accessing the Batch interface Base URL for all Batch queries: 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: o Compliance: To access the NSI Web UI (required to view Batch files available to be downloaded), use the following URL s: o Production: o Compliance: 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 162

81 5.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 File Naming Conventions 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 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 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 9 final.docx Page 81 of 162

82 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 Delimited File Footers Delimited file formats must include information in the footer as specified below 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 input filename The name of the file. UPI00001.txt date file created time file created file type long description The date the file was created in the format yyyymmdd. The time the file was created in the format hhmmss. 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 9 final.docx Page 82 of 162

83 Fieldname Description Example (where applicable) record count A total of all lines in the input file (including the footer record) 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 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 Education Service Desk. Please contact the Education Service Desk if you wish to automate either of these batch 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. 5.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 Education 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 9 final.docx Page 83 of 162

84 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 Education Service Desk to regain access to the system via or 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. 5.4 Batch File Functions 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 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 Education 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 9 final.docx Page 84 of 162

85 The following diagram shows the Update/Insert batch file process flow. NSN provided? Yes No ADD UPDATE Validate input for Add request Validation passed? Yes Validate input for Update request Validation passed? Yes Update Student Process Match Search Definite match found? No Possible match found? No Add Student and send new NSN Yes Yes Yes Return definite match in results Override code supplied? No Yes Validation passed? No Generate override code Return override code in results Guide to National Student Index gins Page 85 of 162

86 5.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 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 which have changed 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. 5.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 Education Service Desk. Similarly, it is possible for results files to be downloaded via HTTPS Download. Please contact the Education 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 2. Post files to 3. Logout by posting the Logout Request as per section 6 to Similarly, it is possible for results files to be downloaded via HTTPS Download. The basic steps required to be performed include: Guide to National Student Index - GINS 6 9 final.docx Page 86 of 162

87 1. Login by posting the Login Request as per section 6 to 2. Get list of files to download from 3. Get each file from 4. Logout by posting the Logout Request as per section 6 to For Compliance the URL s start with followed by the applicable function request Login to the NSI through Batch Interface 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 "?> <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 "?> 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. Guide to National Student Index - GINS 6 9 final.docx Page 87 of 162

88 org_id Character(10) The organisation the user is signing in on behalf of. Mandatory Outputs <?xml version="1.0" encoding="iso "?> <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 "?> Common XML header <result version="1.0"> Start of result record </result> End of result record Logout from the NSI through the Batch Interface 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 "?> <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 "?> Common XML header <logout/> logout record Guide to National Student Index - GINS 6 9 final.docx Page 88 of 162

89 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 Security Key Cookie from login response header containing the security key to be used in successive requests. Mandatory Outputs <?xml version="1.0" encoding="iso "?> <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 "?> Common XML header <result version="1.0"> Start of result record </result> End of result record 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: Successful Upload Output When you have uploaded a file successfully using the automated upload function, you will get the following output: Msg:<message description> Guide to National Student Index - GINS 6 9 final.docx Page 89 of 162

90 File: File Name : <uploaded filename> Size: File Length: <file size> Important note: A 200 OK response with a response body, indicates that the request was processed successful. A 200 OK response may be returned even though the upload was unsuccessful. Unsuccessful uploads can be identified by no response body. Recommendation is to treat 200 OK response, with no response body, as an unsuccessful upload 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> Automated Download of Batch Files 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: 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 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: interface/batch_download.asp?file={filename} The name of the file you wish to download will be populated in the {filename} field above. 5.6 Delimited Batch File Formats Encoding Delimited batch file results will be ANSI encoded. Guide to National Student Index - GINS 6 9 final.docx Page 90 of 162

91 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.) Search The following sections detail the input and output requirements for delimited Search batch files 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: or Joe Bloggs M C 1001 All delimited files require a footer record. Refer to section 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. Guide to National Student Index - GINS 6 9 final.docx Page 91 of 162

92 Parameter Type Description Requirement 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 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. Optional may only be used in conjunction with Name. residential_stat us Character (1) The residential status of the student. Valid values for Residential status: C (NZ citizen) Optional may only be used in conjunction with Name. P (NZ Permanent resident) A (Australian citizen) O (Other) U (Unknown) 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 9 final.docx Page 92 of 162

93 Outputs A new section starting with an S line will appear in the results file for each name submitted to the search 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 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 9 final.docx Page 93 of 162

94 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 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 Update/Insert The following sections detail the input and output requirements for delimited Update/Insert batch files 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 U C P Blogs Joseph 1001 All delimited files require a footer record. Refer to section Delimited File Footers for information on the file footer requirements. Guide to National Student Index - GINS 6 9 final.docx Page 94 of 162

95 When an invalid Alternative name on a record is submitted, the Alternative name will be ignored and not created, the record with the submitted primary details is still created. 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 gender Character (1) M, F or U. The gender of the student, where U stands for unknown preferred_nam e_indicator Character (1) Y or N specifying that this name is the preferred name. dob Character (8) The date of birth of the student in format yyyymmdd e.g name_dob_ver ification residential_stat us residential_stat us_verification alternative_sur name Character (1) Character (1) Character (1) Character (100) The verification method used to verify name/dob. Can be Unverified, Passport, Birth Cert, or Other primary id. The residential status of the student. NZ Citizen, NZ Permanent resident, Australian citizen, Overseas or Unknown. The residential status verification. Can be Unverified, Passport, Birth Cert, or Other primary id. The last name of an alternative name used by the student Optional Optional Mandatory for a Insert request Optional Optional. Optional Optional Guide to National Student Index - GINS 6 9 final.docx Page 95 of 162

96 Parameter Type Description Requirement alternative_for ename1 alternative_for ename2 alternative_for ename3 alternative_pre ferred_name_i ndicator Character (100) Character (100) Character (100) Character (1) The first name of an alternative name used by the student The second name of an alternative name used by the student The third name of an alternative name used by the student Y or N specifying whether this 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 provider_refer ence Character (30) A reference passed from an SMS to the NSI in order for it to be returned in the output Footer lines must be terminated with a Carriage Return (ASCII 13). Optional Optional Optional Optional Optional Optional Outputs 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 Guide to National Student Index - GINS 6 9 final.docx Page 96 of 162

97 alternate_name_dob_verification override_code provider_reference 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 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 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 Processing Statistics Below the results file footer, the batch file will contain statistics on the processing of the file: Guide to National Student Index - GINS 6 9 final.docx Page 97 of 162

98 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 Merge Request The following sections detail the input and output requirements for delimited Merge Request batch files, 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: Or All delimited files require a footer record. Refer to section 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 nsn2 nsn3 nsn4 32-bit signed Integer 32-bit signed Integer 32-bit signed Integer 32-bit signed Integer NSN of a record to be included in the set of records to be merged NSN of a record to be included in the set of records to be merged NSN of a record to be included in the set of records to be merged NSN of a record to be included in the set of records to be merged Mandatory Mandatory Optional Optional Guide to National Student Index - GINS 6 9 final.docx Page 98 of 162

99 Field Type/Length Description Requirement nsn5 nsn6 nsn7 nsn8 nsn9 nsn10 32-bit signed Integer 32-bit signed Integer 32-bit signed Integer 32-bit signed Integer 32-bit signed Integer 32-bit signed Integer NSN of a record to be included in the set of records to be merged NSN of a record to be included in the set of records to be merged NSN of a record to be included in the set of records to be merged NSN of a record to be included in the set of records to be merged NSN of a record to be included in the set of records to be merged NSN of a record to be included in the set of records to be merged Optional Optional Optional Optional Optional Optional Outputs The following sections define the syntax for all potential outcomes of a merge request in delimited format 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 forename 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 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 Guide to National Student Index - GINS 6 9 final.docx Page 99 of 162

100 E error code Manual Intervention Required reason text 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 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 Student-Provider Relationship (ATA) Add / Update The following sections detail the input and output requirements for delimited ATA batch files 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: All delimited files require a footer record. Refer to section 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 Data Fields Guide to National Student Index - GINS 6 9 final.docx Page 100 of 162

101 Parameter Type Description Requirement provider_code Character(10) The Ministry assigned provider code. nsn active_until_da te 32-bit signed Integer Character(8) The NSN of the student to search for. Valid date in format yyyymmdd e.g 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.) Mandatory 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 Outputs Successful Active At Creation For a successful Active At creation, no message is reported back to the user Errors Returned Error records are reported first: Guide to National Student Index - GINS 6 9 final.docx Page 101 of 162

102 E Error Code Error Description Input record (see inbound file) 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 Change Notifications The following sections detail the delimited Change Notification batch files. There are no related Change Notification inputs Inputs N/A Outputs The pipe character - ASCII 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 9 final.docx Page 102 of 162

103 5.7 XML Batch File Formats Encoding XML batch file results will be ISO 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.) Search The following sections detail the input and output requirements for XML Search batch files 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 ?> <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 <?xml version="1.0" encoding="iso "?> <student_list version= "1.0"> </student_list> Description Common XML header Start of list of students End of list of students Guide to National Student Index - GINS 6 9 final.docx Page 103 of 162

104 Tag <student> <student> </student> Description Start of student record within student list Start of student record within student list End of student record within student list 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 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 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. Optional may only be used in conjunction with Name. residential_stat us Character (1) The residential status of the student. Valid values for Residential status: C (NZ citizen) Optional may only be used in conjunction with Name. P (NZ Permanent resident) A (Australian citizen) O (Overseas) U (Unknown) 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 9 final.docx Page 104 of 162

105 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: Successful Match One Result Found <?xml version= 1.0 encoding= ISO ?> <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> Guide to National Student Index - GINS 6 9 final.docx Page 105 of 162

106 <dod></dod> <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> 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 9 final.docx Page 106 of 162

107 <dod/> <student_status/> <created_date/> <created_by_userid/> <created_by_provider_code/> <ranking/> <match_indicator/> <name_list/> Unsuccessful Search No Matches Found/Error Returned <?xml version= 1.0 encoding= ISO ?> <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 table 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 "?> Common XML header <result_list version= "1.0"> </result_list> <result> Start of result list End of result list Start of result record within results list Guide to National Student Index - GINS 6 9 final.docx Page 107 of 162

108 Tag </result> <criteria> </criteria> <student_list> </student_list> <student> </student> <name_list> </name_list> <name> </name> <error> </error> Description End of result record within results list Start of data input End of data input Start of list of students End of list of students Start of student record within student list End of student record within student list Start of list of names for student record End of list of names for student record Start of name record for student within name list End of name record for student within name list Start of error record for student End of error record for student Update/Insert The following sections detail the input and output requirements for XML Update/Insert batch files. When an invalid Alternative name on a record is submitted, the Alternative name will be ignored and not created, the record with the submitted primary details is still created Inputs <?xml version= 1.0 encoding= ISO ?> <student_list version= 1.0 > <student> <nsn></nsn> <surname></surname> <forename1></forename1> Guide to National Student Index - GINS 6 9 final.docx Page 108 of 162

109 <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 table 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 "?> Common XML header <student_list version= "1.0"> <student> </student> <alternate_name> </alternate_name > </student_list> Start of list of student records Start of student record within match list End of student record within match list Start of alternate name record within student record End of alternate name record within student record End of list of student records 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 9 final.docx Page 109 of 162

110 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 preferred_nam e_indicator Character (1) Y or N specifying that this name is the preferred name. dob Character (8) The date of birth of the student in format yyyymmdd e.g name_dob_ver ification residential_stat us residential_stat us_verification alternative_sur name alternative_for ename1 alternative_for ename2 Character (1) Character (1) Character (1) Character (100) Character (100) Character (100) The verification method used to verify name/dob. Can be Unverified, Passport, Birth Cert, or Other primary id. The residential status of the student. NZ Citizen, NZ Permanent resident, Australian citizen, Overseas or Unknown. The residential status verification. Can be Unverified, Passport, Birth Cert, or Other primary id. The last name of an alternative name used by the student The first name of an alternative name used by the student The second name of an alternative name used by the student Optional Optional Mandatory for an Insert request Optional Optional Optional Optional Optional Optional Guide to National Student Index - GINS 6 9 final.docx Page 110 of 162

111 Parameter Type Description Requirement alternative_for ename3 alternative_pre ferred_name_i ndicator Character (100) Character (1) The third name of an alternative name used by the student Y or N specifying whether this 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 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 Optional Optional Optional Outputs 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 ?> <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> Guide to National Student Index - GINS 6 9 final.docx Page 111 of 162

112 <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> </result> </result_list> 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 "?> <result_list version="1.0"> <result> <student> <nsn><nsn/> <surname></surname> <forename1></forename1> <forename2></forename2> <forename3> </forename3> <dob></dob> Guide to National Student Index - GINS 6 9 final.docx Page 112 of 162

113 <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> </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> Guide to National Student Index - GINS 6 9 final.docx Page 113 of 162

114 </student> </match_list> </result> </result_list> 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 ?> <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> <preferred_name_indicator></preferred_name_indicator> Guide to National Student Index - GINS 6 9 final.docx Page 114 of 162

115 <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> Processing Statistics The batch file will contain statistics on the processing of the file: <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 ?> <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> Guide to National Student Index - GINS 6 9 final.docx Page 115 of 162

116 <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) Merge Request The following sections detail the input and output requirements for XML Merge Request batch files Inputs <?xml version="1.0" encoding="iso "?> <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. Guide to National Student Index - GINS 6 9 final.docx Page 116 of 162

117 The following table 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 "?> Common XML header <student_list version= "1.0"> <student> </student> Start of list of student records Start of student record within list of students End of student record within list of students 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 nsn2 nsn3 32-bit signed Integer 32-bit signed Integer 32-bit signed Integer NSN of a record to be included in the set of records to be merged NSN of a record to be included in the set of records to be merged NSN of a record to be included in the set of records to be merged Mandatory Mandatory Optional Up to 10 NSN s can be included in a merge request. NSN s 4 10 will be validated as per NSN3 above Outputs The <request_string/> returned will contain the details previously submitted in the <student/> XML tag as shown above Records Merged Successfully <?xml version= 1.0 encoding= ISO ?> <result_list version= 1.0 > <result> <request_string> <nsn></nsn> <nsn></nsn> <nsn></nsn> Guide to National Student Index - GINS 6 9 final.docx Page 117 of 162

118 <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> 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> <nsn></nsn> <nsn></nsn> <nsn></nsn> </request_string> <error_code></error_code> <error_description></error_description> </result> Processing Statistics Below the result_list element, the batch file will contain statistics on the processing of the file: <stats> <successful_merge></successful_merge> Guide to National Student Index - GINS 6 9 final.docx Page 118 of 162

119 <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 "?> Common XML header <result_list version= "1.0"> </result_list> <result> </result> <stats> </stats> Start of result list End of result list Start of result record within results list End of result record within results list Start of statistics for batch file End of statistics for batch file Student-Provider Relationship (ATA) Add/Update The following sections detail the requirements for ATA Batch files in XML format Inputs XML files will be formatted as follows: <?xml version= 1.0 encoding= ISO ?> <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 "?> Common XML header Guide to National Student Index - GINS 6 9 final.docx Page 119 of 162

120 Tag <active_at version= "1.0"> <student> </student> </active_at > Description Start of list of active at records Start of active at record within list End of active at record within list End of list of active at records 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 provider_code Character(10) The Ministry assigned provider code. nsn 32-bit signed Integer The NSN of the student to search for. 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.) Mandatory. Guide to National Student Index - GINS 6 9 final.docx Page 120 of 162

121 Parameter Type Description Requirement active_until_da te Character(8) Valid date in format yyyymmdd e.g 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 Outputs Successful Active At Creation For a successful Active At creation, no message is reported back to the user 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 ?> <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> Processing Statistics Guide to National Student Index - GINS 6 9 final.docx Page 121 of 162

122 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> <total_records_processed></total_records_processed> </stats> Tags for XML formatting (not data fields) Tag Description <?xml version="1.0" encoding="iso "?> Common XML header <result_list version= "1.0"> </result_list> <result> </result> <criteria> </criteria> <error> </error> <stats> </stats> Start of result list End of result list Start of result record within results list End of result record within results list Start of active at record within list End of active at record within list Start of error record for student End of error record for student Start of statistics for batch file End of statistics for batch file Guide to National Student Index - GINS 6 9 final.docx Page 122 of 162

123 5.7.6 Change Notifications The following sections detail the XML Change Notification batch files. There are no related Change Notification inputs Inputs N/A 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> <nsn></nsn> Guide to National Student Index - GINS 6 9 final.docx Page 123 of 162

124 <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> <nsn></nsn> </merge_denied> </merge_denied_list> </notification_list> Guide to National Student Index - GINS 6 9 final.docx Page 124 of 162

125 6 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. ESAA Education Sector Access & Authorisation Use of the Education Sector Logon User accounts and/or machine accounts. HTTPS HyperText Transfer Protocol (Secure) 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 MoE Ministry of Education Also known now as Education Service Desk 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 Guide to National Student Index - GINS 6 9 final.docx Page 125 of 162

126 (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. 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 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 Markup 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 9 final.docx Page 126 of 162

127 7 Appendix C: Error Codes and Triggers The following table lists all errors that can be returned from the NSI from the external interfaces (XML, Batch and REST). This table is up to date as at 08/12/2014. 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 Guide to National Student Index - GINS 6 9 final.docx Page 127 of 162

128 Code Interface Message Value Trigger 0 Batch Success. Used for Batch Interface login, logout or merge request has been successfully submitted Returned for a successful Batch login request. 12 REST 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. Guide to National Student Index - GINS 6 9 final.docx Page 128 of 162 Name must be present if Birth date, Gender or Residential status are present. 13 Batch Type mismatch. Legacy: When org_id provided in login request through the Batch interface is invalid or missing. 21 REST Record(s) that closely match this record have been found. Please confirm whether you wish to add this record. Display warning if close match found. Close match will be determined by the Add Possible Match Threshold. 23 REST Name & birth date and Residential status verification cannot be set to anything other than 'Unverified' when 'Birth date' and / or Residential status is 'Unknown'. 25 REST Student record successfully saved. Successful submission of changes. 27 REST Names which exactly match another name on the student record cannot be added. 34 REST This record contains verified name and birth date information. If you wish to update this information please raise a challenge. 55 REST Student records have been automatically merged. The master record is {0}. If Birth date is not populated or set to "Unknown" or birth date entered is "11/11/1918" and Name & birth date verification is set to something other than Unverified. If Residential status is 'Unknown' and Residential status verification is set to something other than Unverified. Primary or Alternative name is added which exactly matches another name on the student record. Display message on load of Modify screen when student record contains verified name and birth date {0} = NSN of Master record Merge request is automatically approved once submitted

129 Code Interface Message Value Trigger 60 REST No such Provider exists. Please Provider code does not exist on the NSI database check and re-enter. 74 Batch Please ensure the file you are Selected file does not have a valid extension uploading has either a.txt or.xml extension. 75 Batch Please ensure the file you are Upload button pressed but file name is not valid uploading has either an ATA, SEA, MER, or UPI prefix. 76 Batch Please ensure the file you are Upload button pressed but file does not pass primary name validation uploading has an ATA, SEA, or MER or UPI prefix then 5 characters then a.txt or.xml extension. 88 REST You have been logged out of NSI. Exit NSI button is clicked 256 Batch {0} is invalid. {0} = name of field Displayed when invalid value for field has been submitted Guide to National Student Index - GINS 6 9 final.docx Page 129 of 162

130 Code Interface Message Value Trigger 257 Batch, REST Please enter values for the following mandatory field(s):\n{0} {0} = name of mandatory field Mandatory fields must be populated 259 Batch Name, DoB, Residential Status and Gender cannot be supplied as search criteria with NSN. Only triggered for alternative names where at least one field on the name has been populated LEGACY: XML and BATCH Login - Triggered when user id or password missing XML and BATCH (CSV and XML) Search: - Triggered when optional fields supplied for match search without at least one name. - Triggered when mandatory fields are not supplied (NSN, Name details or User) XML and BATCH (CSV and XML) Add: - Triggered when Surname, Forename1, Birth date or User missing - Triggered when conditionally mandatory fields are missing. XML Modify: - Triggered when surname and forname1 missing when alternative name being added - Triggered when 'User' missing - Triggered when conditionally mandatory fields are missing. BATCH (CSV and XML) Modify: - triggered when NSN missing XML Merge: - Triggered when 'User' missing - Triggered when conditionally mandatory fields are missing. Note - /n is interpreted on the Web UI as new line and bullet point Other parameters supplied with NSN when submitting a search request Guide to National Student Index - GINS 6 9 final.docx Page 130 of 162

131 Code Interface Message Value Trigger 272 Batch, REST {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. {0} = name of name field. Name fields can only contain alphabetic characters or a single ~ in Given name (1). '~' cannot be used in any other name field. Space, hyphen and apostrophe can only be used with another character and may not be repeated. Names must start with an apostrophe or an alphabetic character. Names must not include diacritic characters. Legacy: Batch (CSV and XML) Search, Add and Modify - returned when name fields exceed allowed length. 273 Batch Verification Flag cannot be set without corresponding data. Unknown residential status AND / OR Birth date cannot be verified by any method. 274 Batch Cannot modify verified data. Primary name details, birth date or Name and Birth date verification cannot be modified if Name & Birth date Verification has a value other than "Unverified". 275 Batch, REST Invalid verification flag. o Name & date of birth verification. Valid values are: o U (unverified) o P (passport) o B (birth cert) o O (other) o Residential status verification o U (unverified) o P (passport) o B (birth cert) o O (other) 276 Batch, REST Verification Flag cannot be set to BDM. Validation is case insensitive for external interfaces. NameDob, Residential & AltName verification can't be set to 'M'. (Can't be done by insert/update of whole record). Guide to National Student Index - GINS 6 9 final.docx Page 131 of 162

132 Code Interface Message Value Trigger 277 REST You cannot update {0} when {1} is 'Birth register'. 279 Batch, REST {0} cannot be changed from a verified value to 'Unverified'. {0} = name of field being updated {1} = name of field set to 'Birth register' i.e. You cannot update Residential status when Residential status verification is 'Birth register' When <verification type> is "Name and birth date" <field> can be: Primary Family name Primary Given name(1) Primary Given name(2) Primary Given name(3) Birth date Name & birth date verification. When <verification type> is "Residential status" <field> can be: Residential status Residential status verification. {0} = name of field Name & birth date verification and/or Residential status verification have been changed from a value not equal to 'Unverified' to equal 'Unverified'. Guide to National Student Index - GINS 6 9 final.docx Page 132 of 162

133 Code Interface Message Value Trigger 280 Batch 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 Batch BDM verification flags cannot be 288 Batch, REST 290 Batch, REST 304 Batch, REST changed. Invalid gender. Cannot change Ministry of Education verified data. Invalid date format. Modification by a User of Birth date and Primary Family name together with one or more of the Primary Given name fields. (With the exception of capitalisation changes) Legacy - triggered when user attempts to modify a BDM verification flag for Name & birth date verification AND/OR Residential status verification. Gender. Valid values are: o F (female) o M (male) o U (unknown) Validation is case insensitive for external interfaces. Name and birth date details and verification, and Residential status and verification may not be modified if they are verified by the Ministry of Education or "Verification confirmed by MOE" has been set to yes. When date format is not yyyymmdd For REST: Format: yyyy-mm-dd Legacy: Date fields must only contain numeric characters Guide to National Student Index - GINS 6 9 final.docx Page 133 of 162

134 Code Interface Message Value Trigger 305 Batch, REST 309 Batch, REST 320 Batch, REST 321 Batch, REST 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. Residential status is invalid. Preferred name indicator is invalid. Preferred name indicator set for more than one name. {0} = name of date field Date must be valid i.e.. 30/02/2013 is not a valid date For XML & BATCH (Legacy) - Date fields must be in a valid ISO 8601:1988 format: yyyymmdd or yymmdd. E.g. ( or will both represent 10 July Date cannot be later than current date. Date cannot be today's date. User does not have privileges to update birth date (user not associated to provider who created record, or user associated to provider who created the record but attempting to update outside of allowed time period). Residential status. Valid values are: o C (NZ citizen) o P (NZ permanent resident) o A (Australian citizen) o O (Overseas) o U (unknown) Validation is case insensitive for external interfaces. Preferred name indicator. Valid values are: o Y o N Validation for the above values is case insensitive. Must be one of true false (REST) Validation for the above is case sensitive. Preferred name indicator is set to 'Y' for more than one name Guide to National Student Index - GINS 6 9 final.docx Page 134 of 162

135 Code Interface Message Value Trigger 336 Batch, REST Invalid NSN. On retrieve of student record where an invalid NSN is included. On Generate of Merge status screen where an invalid NSN is included. On validation on Merge request where an invalid NSN is included. When SPR created/updated for inactive student. Method ValidateNSN defines it as - Not longer than 10 characters Legacy: this error is returned when: - NSN supplied in request is invalid (longer than 10 characters and/or contains non-numeric characters) - Merge request submitted through XML, Batch (CSV and XML) has a blank field - NSN supplied in the batch file does not exist on the database or is a slave NSN - NSN in active at file is invalid, missing or inactive When there is a blank field in a Batch Merge Request file (CSV and XML) 337 Batch, REST NSI record {0} does not exist. (eg. "13 " or "<nsn></nsn> " {0} = NSN entered NSN is valid but does not exist in the NSI database. Guide to National Student Index - GINS 6 9 final.docx Page 135 of 162

136 Code Interface Message Value Trigger 338 Batch, REST {0} is already a slave of record {1}. Slave records cannot be merged. 339 REST Invalid Provider Code. Only Standard characters (A-Z, 0-9) are permitted. Leading or trailing spaces are not permitted. 352 Batch Request failed to be lodged with NSI Unit - too few records identified in group (minimum is 2). 353 Batch, REST A maximum of ten unique student records can be included in a merge request. {0} = Slave record NSN entered {1} = Master record NSN of entered slave NSN On retrieve of student record where a slave NSN is entered. Student record is not retrieved. When validating a Merge request submitted via non UI interfaces. If multiple slave NSN's are in merge request, a message will display for each slave NSN. Displayed as sub message to #956 on merge decision screen Displayed as a sub message to #956 on merge entry screen (ONLY when slave has been retrieved and selected for merge. On 'retrieve' not displayed as a sub message). Legacy: Returned when NSN(s) supplied in merge request is a slave record. Must be: - Max 10 characters - Alpha Numeric ( Standard characters (A-Z,0-9)) - '-1' is permitted - Provider Code in the Active At input file is not equal to user s provider code and Provider Details On Behalf set to No for the user s provider code - Provider Code in the Active At input file does not exist - OrganisationID in REST request is blank of invalid. Displayed when NSN(s) missing in merge request submitted through the XML and Batch interface. Displayed as a sub message to #956 (Merge Entry screen) Displayed as a stand alone message on search screen) More than 10 records have been selected/submitted for merge Legacy: Triggered when more than 10 NSNs supplied in XML and Batch (CSV and XML) merge request. Guide to National Student Index - GINS 6 9 final.docx Page 136 of 162

137 Code Interface Message Value Trigger 369 Batch BDM verified fields cannot be modified. Primary name details, birth date or Name and Birth date verification cannot be modified if Name and Birth date verification is equal to Birth Register". Residential Status or Residential status verification cannot be modified if Residential Status verification is equal to Birth Register". If NSN supplied in modify request has a record status = 'Inactive'. 370 Batch, REST NSI Record is inactive and cannot be updated. 409 REST Unexpected validation Error. (Fallback message). 416 Batch Incorrect File Format. Batch XML: Triggered when XML batch file cannot be parsed. 417 Batch Incorrect Format for file footer When the footer in delimited batch files do not meet requirements. record. 418 Batch Incorrect Record Format. Things like empty lines, empty files, incorrectly delimited lines etc for delimited Batch files. 422 Batch, NSN found is a slave record. N/A. REST 423 Batch, Student Provider Relationship REST period is out of range. If until date supplied in ATA file/or the UI is greater than SPR Duration set in provider details, or date less than today's date, or date is less than created date of the Relationship, or date is less than created date of the student record. 424 Batch Invalid provider code. When provider code supplied in the active at file is; - invalid - does not exist 513 Batch, REST 515 Batch, REST Invalid user name or password. Organisation is not valid for user. - the organisation cannot upload on behalf of other organisations. When user name and/or password submitted through legacy interfaces (XML/Batch) login request is invalid or exceeds the specified field length. Can't determine organisation for user or organisation invalid for the user. Error code '400 invalid_scope' returned from Oauth. Provider is not provisioned against the user logging in ESAA. Guide to National Student Index - GINS 6 9 final.docx Page 137 of 162

138 Code Interface Message Value Trigger 521 Batch, REST 528 Batch, REST 529 Batch, REST The {0} interface is not enabled for you. Session has timed out, or session not established. Access denied. {0} = name of interface. '- When uploading and user doesn't have permissions for batch. Legacy: When login request is received through legacy interfaces and the relevant interface has not been set in the provider details for the organisation associated to the user attempting to login. Batch Upload, Batch Download list and Download file: when security key supplied is invalid, missing or expired. Returned when an invalid or expired session key is submitted. Checks the access before every action - Insert, Update, Merge, Search. Legacy: Returned when the NSI Go Live date has not been reached and the user is attempting to login to the NSI system. Batch: returned when user does not have privileges to upload file. 768 Batch Unexpected validation error. XML document fails parsing. (FALLBACK MESSAGE). Change Notifications - When downloaded file exceeds 100MB. Legacy: When XML document fails parsing eg. Invalid XML submitted or Version of XML request not supported or does not contain all required open and closed tags in the request or the XML command is not valid. Valid commands are: login, logout, search, insert, update, merge. e.g. <insert version="1.0> is valid whereas <insert version="1.0"> would trigger this message. BATCH - When uploaded file exceeds 2MB. 769 Batch {0} is not a valid XML command. BATCH XML: Triggered when XML batch file cannot be parsed. 784 REST More than {0} records have been found matching the search criteria. The top {0} records have been returned. Please refine your search criteria. 785 Batch, REST No search results found. {0} = upper threshold number for IQ office results returned per search More than xxx records are returned from IQ Office matching the search criteria. xxx is a parameter within IQ office which will be initially set to 100 No search results found based on user entered detail. Guide to National Student Index - GINS 6 9 final.docx Page 138 of 162

139 Code Interface Message Value Trigger 789 Batch, A system fault means that the NSI {FALLBACK ERROR} REST is temporarily unavailable. If the problem persists contact the MoE Service Desk. Please accept our apologies for any inconvenience. 800 Batch Update denied student has been Student being updated is a slave record. merged. 817 REST Your merge request has been forwarded to the NSI Team. Can you please forward supporting documentation through to nsi.unit@education.govt.nz 818 Batch {0} exist in the merge denied list. Merge request requires manual intervention. 819 REST At least two unique student records are required for merge. 820 Batch Merge request requires manual intervention. Update trigger for Message #817 to the following; Message displayed to user when reason for merge request requiring manual intervention is 'Provider set to Manual Merge Required'. Passed through the REST interface when merge request requires manual intervention. {0} = NSN of student(s) on the denied list. Add - Checks for all pairs being denied. Manual + process - Checks for merge denied pairs. Legacy: Returned when NSNs in merge request received through Batch Interface has previously been denied. Displayed as a sub message to #956. On click, 'Request merge' or 'Confirm request' when less that two student records have been selected for merging. On click of 'Merge' from merge decision where less than two student records are selected for inclusion in the merge. When request for merge is submitted through external interface and less than two unique students are specified. On submission of a merge request where the merge request includes one or more of the following: *Inactive students *Provider requesting the merge has 'Manual merge required' set to YES *Records in the merge request do not meet the MERGE MATCH threshold. *Records in the merge request have unresolved challenges associated to them. Guide to National Student Index - GINS 6 9 final.docx Page 139 of 162

140 Code Interface Message Value Trigger 821 Batch Merge request cannot be processed invalid status. 822 Batch 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 Batch Merge request includes BDM verified records. Merge request requires manual intervention. 897 REST The following NSN(s) are included in a merge request that is currently awaiting processing and cannot be merged. {0} 898 REST The following NSN(s) have been verified by the Birth register: {0} Before the main operation, the MergeRequest status must be: Archive - 'M' Manual - 'M', must have valid user Process - Must be 'S' Reject - Must be 'S' Returned when more than 1 record in a batch merge request has an SPR with NZQA. Returned when a record in batch merge request is verified by Birth Register. {0} = NSN(s) of student records including in unprocessed merge On load of Merge Entry screen when accessed from the search results screen where one or more NSNs included in the list of students are in a merge request awaiting processing (including those merge requests at manual intervention). When validating a Merge request submitted via non UI interfaces. {0} = NSN(s) of BDM verified records in the merge request. Displayed as a sub message to #915 (Request to Merge). On request of a merge when more than one record included in the merge has been verified by the Birth register. Displayed as a sub message to #928 (Merge Manual Decision Making). On load of merge decision screen when more than one record included in the merge has been verified by the Birth register. Guide to National Student Index - GINS 6 9 final.docx Page 140 of 162

141 Code Interface Message Value Trigger 899 REST The following NSN(s) have been previously denied: {0} 902 REST Records in the merge group are not a close enough match for automatic merging. 903 REST The following NSN(s) have current challenges: {0} 915 REST Merge request requires manual intervention for the following reason(s). Please contact the MoE Service Desk if you require more information. {0} = NSN(s) of student record on denied list. Displayed as a sub message to #915 (Request to Merge). On request of a merge when at least one record included in the merge has been previously denied. Displayed as a sub message to #928 (Merge Manual Decision Making). On load of merge decision screen when at least one record included in the merge has been previously denied. Displayed as a sub message to #915 (Request to Merge). On request of a merge when records are not above merge match threshold Displayed as a sub message to #928 (Merge Manual Decision Making). On load of merge decision screen when records are not above merge match threshold. {0} = NSN(s) of student records with current challenge records. Displayed as a sub message to #915 (Request to Merge). On request of a merge when Merge request includes at least one student with a current Challenge with a status of anything other than 'Challenge accepted' or 'Challenge rejected'. Displayed as a sub message to #928 (Merge Manual Decision Making). On load of merge decision screen when Merge request includes at least one student with a Challenge record with a status of anything other than 'Challenge accepted' or 'Challenge rejected'. Message displayed as parent message on merge entry screen with sub messages for each reason relevant to the merge request being sent to manual intervention. When reason(s) for merge request requiring manual intervention includes 'Provider set to Manual Merge Required' reasons will not be displayed as sub messages. Guide to National Student Index - GINS 6 9 final.docx Page 141 of 162

142 Code Interface Message Value Trigger 916 REST The following NSN(s) have an Inactive status: {0} 921 REST 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 . Supporting information can be forwarded separately to nsi.unit@education.govt.nz using the student NSN as a reference number. {0} = NSN(s) of student records with a status of 'Inactive' Displayed as a sub message to #915 (Request to Merge) On request of a merge when Merge request includes at least one student with a record status of 'Inactive' and a record status reason of anything other than 'Slave'. Displayed as a sub message to #928 (Merge Manual Decision Making) On load of merge decision screen when Merge request includes at least one student with a record status of 'Inactive' and a record status reason of anything other than 'Slave'. When a User requests to add a student record and at least one definite match is returned. Guide to National Student Index - GINS 6 9 final.docx Page 142 of 162

143 Code Interface Message Value Trigger 934 REST 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 . Supporting information can be forwarded separately to nsi.unit@education.govt.nz using the student NSN as a reference number. 938 REST This student is part of a merge request that is awaiting processing - Contact the MoE Service Desk if you require further information. 939 REST Student record successfully saved. Please note this record has an unknown birth date. 941 REST Student record successfully saved. Please note this record has 'Unverified' details. Modification by a User of Birth date and Primary Family name together with one or more of the Primary Given name fields (with the exception of capitalisation changes). On load of Modify Student screen where the student being viewed is included in an unprocessed Merge request. On submission of a add student request through REST where the students birth date is unknown. On submission of a add student request through REST where the students the name and birth date verification or the residential status verification is 'Unverified'. 942 REST Invalid override code. When submitted override code in REST add request is invalid. 943 REST Student record successfully saved. Please note verified Residential status details have been updated. When an Update request through REST has been received where the 'Residential status verification' has been updated and the 'Residential status' has not been updated. When an Update request through REST has been received where the 'Residential status' has been updated and the 'Residential status verification' has not been updated when it was and is currently verified. Guide to National Student Index - GINS 6 9 final.docx Page 143 of 162

144 Code Interface Message Value Trigger 944 REST The following NSN's have student provider relationships with NZQA: {0}. The following NSN's don t have student provider relationships with NZQA: {1} Displayed as sub message to #915. Displayed when merge request includes at least two students which have an active SPR with NZQA AND at least one student record does not. {0} populated with the NSN's of student records with a SPR with NZQA. {1} populated with the NSN's of student records without an SPR with NZQA. 945 REST Birth date cannot be today's date. Displayed when Birth date entered is today's date. 951 REST {0} cannot be later than current date. {0} = name of date field. Birth date, Date of death, Start date, End date, Go live date cannot be later than current date (Go live date will only be validated if it has changed), Name & birth date verification date, Residential status verification date. 953 Batch Unknown File Type {0} Triggered by the batch interface when the file prefix is not ATA, SEA, MER or UPI. {0} is the name of the file being loaded. 954 Batch Incorrect file extension (.xml/.txt) Triggered by the batch interface when the file type is not '.txt' or '.xml'. 955 Batch Your file name should have 1 to 5 characters after the 3 letter prefix. {0} Triggered by the batch interface when the provider reference in the file name is longer than 5 characters. (0) is the name of the file being loaded. 956 REST Merge request has been rejected. On submission of a merge request where the merge has been rejected. 957 REST Birth date cannot be modified. Birth date is updated where user is not the provider who created the record OR it is greater than X business days since the record was created REST NSN record has not been modified REST You cannot access the NSI. Your organisation's Go Live date has not yet been reached. Please contact the MoE Service Desk Batch FILE SUCCESSFULLY UPLOADED (Warning) Update Student shows no fields were actually updated (changed) NSI live date for the Provider the user has selected to log in under (if multiple Providers linked to the user id) has no NSI live date or NSI live date is a date in the future. Returned when a file is successfully uploaded through the Batch Interface. Guide to National Student Index - GINS 6 9 final.docx Page 144 of 162

145 8 Appendix D: Related Documents The following is a list of links to documents which relate to integration with the NSI. 8.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 the Education Service Desk to request a copy; Service.Desk@education.govt.nz or phone 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. 8.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. 8.4 ESAA/ESL Request Access Information about the Education Sector Logon can be found here; Guide to National Student Index - GINS 6 9 final.docx Page 145 of 162

146 9 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. 9.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== 9.2 Get Authentication Token from ESAA Obtain Authentication token using User ID and the Encoded string - calling ESAA //Obtain access token using (var client = new HttpClient()) { Guide to National Student Index - GINS 6 9 final.docx Page 146 of 162

147 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(" //Building the Uri var builder = new UriBuilder(theUriHost.ToString()); var query = HttpUtility.ParseQueryString(builder.Query); //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: 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); awaiting a reponse from the server } //await allows you to do parallel processing while the application is Guide to National Student Index - GINS 6 9 final.docx Page 147 of 162

148 The response will include an access token which is used for the login request. An example is shown below. { } "token_type": "Bearer", "access_token": "N0Y1HGVCRjUtMERFDC1BN0Y0LTY2MDUtCzRFQjMyAzIyMDQ3" 9.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(" //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> { { "EsaaAccessToken", responsetokens["access_token"]}, //Using the access token from the reponse in step 2 { "OrgId", "-1" } }; } var content = new FormUrlEncodedContent(parameters); var response = await client.postasync(theuri, content); Guide to National Student Index - GINS 6 9 final.docx Page 148 of 162

149 The response 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: d-b059-12f2-bd1f-39d0114a7e 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 = " + 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. 9.5 Logout using NSI Session Token in Request Header using (var client = new HttpClient()) { Guide to National Student Index - GINS 6 9 final.docx Page 149 of 162

150 Uri theuri = new Uri(" client.defaultrequestheaders.accept.clear(); client.defaultrequestheaders.accept.add(new MediaTypeWithQualityHeaderValue("application/json")); 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 9 final.docx Page 150 of 162

151 9.6 Common Function Calls to ESAA and NSI Using REST The following section contains REST URL format examples showing how to call the NSI REST API service for the specific functions. The samples below contain parameters which will need to be replaced with your actual data. The parameters are indicated by << >> either side of the value. These parameters show either: the format of the data: ("BirthDate": "<<YYYY-MM-DD>>") a sample of the data: ( NameBirthDateVerification : <<U>> ) a description of the data: ( FamilyName : <<FamilyName>> ) Compliance and Production URL s are represented with <<NSI address>>. The relevant URL information can be found in section Accessing the API. An example of a populated Student Provider Relationship call: POST { NSN : , ProviderCode : 7006, ActiveUntilDate : } Get Auth ESAA Token POST - e.g. Guide to National Student Index - GINS 6 9 final.docx Page 151 of 162

152 9.6.2 Create NSI Session POST URL>>/api/v1/session { "EsaaAccessToken": "<<Token generated from ESAA>>", "OrgId": "<<Org ID>>" } e.g Search Request NSN GET URL>>/api/v1/student/<<NSN>> e.g. Guide to National Student Index - GINS 6 9 final.docx Page 152 of 162

153 9.6.4 Search Request Match Search (Name and DOB) GET GivenNameTwo>>&Given3Name=<<GivenNameThree>>&BirthDate=<<YYYY-MM-DD>> e.g Add Student Record Primary Record Details Only POST address>>/api/v1/student/?overridecode= { FamilyName : <<FamilyName>>, Given1Name : <<GivenNameOne>>, Given2Name : <<GivenNameTwo>>, Given3Name : <<GivenNameThree>>, PreferredName : <<false/true>>, Gender : <<M/F>>, BirthDate : <<YYYY-MM-DD>>, NameBirthDateVerification : <<U>>, ResidentialStatus : <<U>>, ResidentialStatusVerification : <<U>>, AltNameList : [] } Guide to National Student Index - GINS 6 9 final.docx Page 153 of 162

154 e.g. Guide to National Student Index - GINS 6 9 final.docx Page 154 of 162

155 9.6.6 Add Student Record Primary and Alternate Name/s POST address>>/api/v1/student/?overridecode= { FamilyName : <<FamilyName>>, Given1Name : <<GivenNameOne>>, Given2Name : <<GivenNameTwo>>, Given3Name : <<GivenNameThree>>, PreferredName : <<false/true>>, Gender : <<M/F>>, "BirthDate": "<<YYYY-MM-DD>>", "NameBirthDateVerification": "<<U>>", "ResidentialStatus": "<<U>>", "ResidentialStatusVerification": "<<U>>", "AltNameList": [ { "AltFamilyName": "<<AltFamilyName>>", "AltGiven1Name": "<<AltGivenNameOne>>", "AltGiven2Name": "<<AltGivenNameTwo>>", "AltGiven3Name": "<<AltGivenNameThree>>", "PreferredName": <<true/false>>, "AltNameBirthDateVerification": "<<U>>" } ] } Guide to National Student Index - GINS 6 9 final.docx Page 155 of 162

156 e.g Modify - Primary Record Details Only PUT - address>>/api/v1/student { "NSN": <<NSN>>, "FamilyName": "<<FamilyName>>", "Given1Name": "<<GivenNameOne>>", "Given2Name": "<<GivenNameTwo>>", "Given3Name": "<<GivenNameThree>>", "PreferredName": <<false/true>>, Guide to National Student Index - GINS 6 9 final.docx Page 156 of 162

157 } e.g. "Gender": "<<M/F>>, "BirthDate": "<<YYYY-MM-DD>>", "NameBirthDateVerification": "<<U>>", "ResidentialStatus": "<<U>>", "ResidentialStatusVerification": "<<U>>", "AltNameList": [] Modify - Primary and Alternate Name/s PUT - address>>/api/v1/student { "NSN": <<NSN>>, "FamilyName": "<<FamilyName>>", Guide to National Student Index - GINS 6 9 final.docx Page 157 of 162

158 ] } e.g. "Given1Name": "<<GivenNameOne>>", "Given2Name": "<<GivenNameTwo>>", "Given3Name": "<<GivenNameThree>>", "PreferredName": <<true/false>>, "Gender": "<<M/F>>, "BirthDate": "<<YYYY-MM-DD>>", "NameBirthDateVerification": "<<U>>", "ResidentialStatus": "<<U>>", "ResidentialStatusVerification": "<<U>>", "AltNameList": [ { "AltFamilyName": "<<AltFamilyName>>", "AltGiven1Name": "<<AltGivenNameOne>>", "AltGiven2Name": "<<AltGivenNameTwo>>", "AltGiven3Name": "<<AltGivenNameThree>>", "PreferredName": <<true/false>>, "AltNameBirthDateVerification": "U" } Guide to National Student Index - GINS 6 9 final.docx Page 158 of 162

159 Guide to National Student Index - GINS 6 9 final.docx Page 159 of 162

160 Modify example below shows only the mandatory required inputs along with the modified fields. For further information on modifying records can be found in section { ] "NSN": <<NSN>>, "AltNameList": [ { "AltFamilyName": "<<AltFamilyName>>", "AltGiven1Name": "<<AltGivenNameOne>>", "AltGiven2Name": "<<AltGivenNameTwo>>", "AltGiven3Name": "<<>>", "PreferredName": <<true/false>>, "AltNameBirthDateVerification": "U" } } Guide to National Student Index - GINS 6 9 final.docx Page 160 of 162

161 9.6.9 Request to Merge Student Records POST - address>>/api/v1/mergerequest/ { "NSNList": [ {"NSN": (<<NSN>>)}, {"NSN": (<<NSN>>)} ] } e.g Create/Update Student Provider Relationship POST - address>>/api/v1/studentproviderrelationship { "NSN": <<NSN>>, "ProviderCode": "<<4 digit provider code>>", "ActiveUntilDate": "<<YYYY-MM-DD>>" } e.g. Guide to National Student Index - GINS 6 9 final.docx Page 161 of 162

162 Logout of NSI DELETE - address>>/api/v1/session e.g. [END of GINS Document]. Guide to National Student Index - GINS 6 9 final.docx Page 162 of 162