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

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 Merge Request Change Notifications Changed Field Indicator Challenge Create/Update Student Provider Relationships Web Interface Overview Security and Authentication REST Interface Guide to National Student Index - GINS 6.8 final.docx Page 2 of 169

3 5.1 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 Search Request File Update/Insert Batch File Merge Request Batch File Change Notification Batch Files Student-Provider Relationship (Add / Update) Guide to National Student Index - GINS 6.8 final.docx Page 3 of 169

4 6.5 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 Application Form 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 Guide to National Student Index - GINS 6.8 final.docx Page 4 of 169

5 1 Introduction 1.1 Document Purpose This document explains the necessary requirements to enable your organisation / application to integrate with the National Student Index (NSI) system. It explains the NSI functionality and details each of the options available for integration with the NSI. 1.2 Document Audience This document is written for Organisations, their NSI users and those developing systems that interface with the NSI. The first part of this document deals with business processes and general matters relating to integration. This includes section 2 (Getting Started) through to section 3 (NSI Functional Overview). The final part of this document deals with the technical aspects of integrating the NSI with your systems. This includes section 4 Web Interface onwards. 1.3 Interface Support IMPORTANT NOTE: Please be aware that this Guide for Integrating with the NSI (GINS) is valid as at issue date. The Ministry reserves the right to upgrade interfaces to ensure compliance with current industry standards, and to meet future business requirements. We will provide notice to known users of the interfaces of changes impacting on them. Support for legacy interfaces will be withdrawn after a notified sundown period. The Ministry has made available a test version of NSI (Compliance) for use by Vendors / providers when testing their interface with NSI. The Compliance database is refreshed from Production on the 1 st Tuesday of every month. 1.4 Contacts Matters relating to the scope and nature of the NSI or requests for technical support in integrating with the NSI system should be addressed to: National Student Index c/- Ministry of Education Service Desk Ministry of Education Guide to National Student Index - GINS 6.8 final.docx Page 5 of 169

6 P O Box 1666 Wellington or ed to: service.desk@education.govt.nz or call the MoE Service Desk on 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 Guide to National Student Index - GINS 6.8 final.docx Page 6 of 169

7 Date Revision Sections Changed Description of Changes 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 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. Guide to National Student Index - GINS 6.8 final.docx Page 7 of 169

8 Date Revision Sections Changed Description of Changes 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 /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. Guide to National Student Index - GINS 6.8 final.docx Page 8 of 169

9 2 Getting Started 2.1 What is the National Student Index? The National Student Index (NSI) is a database system maintained by the Ministry of Education and is the education sector s core register of learner identity data. The NSI is used to allocate a unique identifier, a National Student Number (NSN) to every student in New Zealand. Each student should only be allocated one NSN which will be used throughout their early childhood, school and tertiary education. An NSN will be allocated to a student when they first enrol in early childhood education, a school or tertiary education in New Zealand. NSNs are required to be included for every student reported to the Ministry for example in the Single Data Returns (SDRs). This allows information about each student to be linked together. 2.2 National Student Index queries The day-to-day operation of the NSI is managed by the Ministry of Education's Service Desk. Specifically, the Service Desk is responsible for helping organisations to start using the National Student Index (NSI), establishing and maintaining access privileges, distributing documentation and informational material and providing ongoing technical and operational guidance. Organisations can contact the Ministry of Education's Service Desk with questions or requests. Phone 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, TEC and NZQA. Individuals can request a copy of their information held on the NSI. Where required, they can submit a request for their information to be corrected through the MoE Service Desk by providing appropriate documentation. Guide to National Student Index - GINS 6.8 final.docx Page 9 of 169

10 2.4 What is an NSI record? An NSI record is unique to a student and records basic identification details. The fields on an NSI record include: Family name Three Given names Birth date (DoB) Gender Residential status Record status Date of death Alternative names A preferred name indicator Verification indicators for the name & birth date fields and for the residential status field An NSI record can have one of two statuses with an associated Record status reason. These are: 1) Active the record is in use on the NSI application. a) In use the student record is used by the NSI application and can be Searched for and Updated. 2) Inactive the record has been made inactive for one of the following reasons: a) Slave following the receipt of a request to merge two or more student records. Once the merge request is processed, the duplicate record(s) will be marked as a Slave record and linked to the Master record. b) Deceased following the receipt of notification and supporting documentation of a student s death from an Organisation c) Created in error following the receipt of notification of an incorrectly created student. d) Do not use following the receipt of notification that this record should not be used. 2.5 Who needs an NSI record? NSI records will be created for individuals who: Enrol in a New Zealand Early Childhood Education provider. Enrol in a New Zealand school. Register for the NCEA Enrol or seek to enrol with a tertiary organisation All type D students (as defined in the Ministry of Education s Single Data Return manual) must have a corresponding NSI record with verified name, birth date and residential status to claim student achievement component (SAC) funding. Guide to National Student Index - GINS 6.8 final.docx Page 10 of 169

11 2.6 How do Organisations find out about changes to NSI data? To ensure that changes to NSI records are communicated to organisations that need to know, a record of a student s relationship with an organisation is maintained by the NSI system. When an NSI record is added or updated by an organisation, that NSN is marked as having a relationship with that organisation. Any changes made to an NSI record will be notified to all organisations that have requested to receive change notifications and have a current relationship with the student via the change notification process. Change notifications applicable to an organisation will be available for viewing on the NSI web interface. Files may be downloaded from the web interface or through the Batch Interface. For example, if a Student s Birth date is updated by an organisation, all the organisations which have a relationship with that student will be notified. If a student dies, the change notification process will also be used to inform all organisations that have either a current or expired relationship with the student. 2.7 How can the NSI system be accessed? The NSI system can be accessed only by authorised people from: ECE Services Schools (via the ENROL system) NZQA Tertiary Education Organisations Tertiary Education Commission (TEC) Ministry of Education support staff. Providers may wish to access the NSI through a chosen Student Management System (SMS). Individual SMS applications will integrate with the NSI through the REST and/or BATCH interfaces. The NSI system can be accessed in any of three different ways. These three methods are all offered so that you can choose the ones which are best suited to your organisation. Please note that all new providers will need to go through a go live process before they are given access to the NSI system. Login details and information about the go live process can be obtained from the Ministry of Education. MoE Service Desk ( 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 Guide to National Student Index - GINS 6.8 final.docx Page 11 of 169

12 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 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. Guide to National Student Index - GINS 6.8 final.docx Page 12 of 169

13 It should be noted that for functions available on multiple interfaces, the actions performed on the NSI system are the same, regardless of the interface method used. 2.9 What is the best NSI system interface option for you? The variety of interfaces means that a provider can utilise the method (or combination of methods) that fits best with their existing business processes. Most smaller organisations may use only the NSI web interface. However larger organisations may use more than one type of interface. For example, an organisation s staff interacting with students may use the NSI web interface but the batch process may be used during peak enrolment periods to send and receive NSI data for that organisation s students 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.8 final.docx Page 13 of 169

14 The following diagram sets out some of the key factors to consider when selecting the most appropriate interface(s) to use: It is suggested that the decision about which NSI interface(s) to use be made in consultation with your SMS vendor/developer. Guide to National Student Index - GINS 6.8 final.docx Page 14 of 169

15 2.11 What next? You will need to take the following steps to start using the NSI: Step 1: Contact MoE Service Desk Your organisation s CEO or Head of IT or Academic Registrar (or equivalent) should contact the MoE Service Desk to make arrangements for your organisation to start using the NSI. Please note that if you are intending to implement the batch or an online interface that you will need to contact the MoE Service Desk at least three months before you want to start using the NSI system. Step 2: Determine Interface and Make System and/or Business Process Changes (if required) The information in section 2.9 will help you to determine the best interface or interfaces for your organisation. This decision will need to be made in conjunction with considering your student administration business processes, and liaison with your SMS supplier or in-house IT developer. Depending on the interface(s) you implement, changes may need to be made to your SMS or the way in which you manage students personal information. The specifications for the online and batch interfaces are set out in the following sections: Web Interface refer to section 4 REST Interface refer to section 5 Batch File Interface refer to section 6 Before implementing any systems changes it is recommended that consideration be given to the points set out in section 2.10, and that a decision be made as to which staff within your organisation will use the NSI. Step 3: Perform Testing If you are using the REST or Batch interfaces then you will need to carry out testing prior to using the NSI. Your testing will need to include the sending of data or files. The MoE Service Desk will assist you through this process. If you are testing an integrated online interface you will also have to perform specific tests with the MoE Service Desk before being allowed live access to the system. Step 4: Data Load The final step in preparation before using the NSI is to load your existing records into the NSI system. This means that when you go live your students will already have NSI records. Again, the MoE Service Desk will help you with the data load to ensure that the process is successful. Guide to National Student Index - GINS 6.8 final.docx Page 15 of 169

16 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.8 final.docx Page 16 of 169

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 UI interfaces will return Unknown to represent an unknown birth date. A birth date of 11/11/1918 will be returned in batch and other legacy outputs from the NSI to the providers representing an unknown birth date. When a birth date of 11/11/1918 is received by the NSI, it will be treated by the NSI as an unknown birth date. 3.3 Search The search facility is used to search for students in the NSI database. Searches can be performed using only the NSN (NSN search) or using a student s name and other fields (Criteria search). It is highly recommended searches which do not include NSN, include the student s full name (Family and Given name(s)) and Birth date. NSN search: Direct lookup. The result will always be an exact match with one NSI record, unless it does not exist or is invalid. Criteria search: This will search for the student by the following parameters: Student name ( main name and alternative names will be searched); there will be some allowance for variance in spelling of names and additional given names. Guide to National Student Index - GINS 6.8 final.docx Page 17 of 169

18 Birth date, it is highly recommended the birth date is included in a criteria search to increase the reliability of search results. There will be some allowance for close birth dates (e.g. 01/10/1988 and 01/10/1989). The tilde symbol ~ can be used in addition to one single name when the student has only one name. 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: Guide to National Student Index - GINS 6.8 final.docx Page 18 of 169

19 Score NSI Name Date of Birth 100 Lyndon Neville Petersen 13/09/1978 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 Guide to National Student Index - GINS 6.8 final.docx Page 19 of 169

20 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 returned to the user who can either use that NSI record, or if you know the student record matched is a different student to the one you are trying to add to the NSI, you can raise a challenge against the matched student and submit supporting information to the MoE Service Desk who can add the record for you. Possible match - If a record already exists that the NSI considers a Possible match (a search result which has a score high enough to be over the NSI determined threshold for Possible matches but not high enough to be considered a Definite match ) a user must confirm the addition of the student record after reviewing the details of the possible matches. Through the Web Interface, this is achieved via a confirmation button, the BATCH interface and the REST service will provide the user with an override code which can be used to add the new record if the user is certain that they are dealing with a different student to the one which has been found on the NSI. The NSI will require this override code to be included in a subsequent request to add the record. No matching records - Where no matches are returned from the prerequisite search, the student record will be added and the new NSN will be returned to the user. The user ID, organisation code and date of creation are recorded with that record. 3.5 Update The update facility is used to update existing NSI records. Updating a record in the NSI requires that an NSN be provided to identify the record being changed. Updates will be initiated when, for example, a student changes their name or residential status. It is important to note that when entering a name in the NSI, the name will be saved in exactly the same case as entered. For example if the name is entered as John LaRose, it will be saved in NSI as John LaRose. The NSI system will not change the case of LaRose to Larose. Alternatively if the name is entered as john, it will be saved in NSI as john Alternate Name Updates Once an alternate name is added to the student record it cannot be updated. If an update request is received containing alternate name details, the system will attempt to add the alternate name as a new name. This update could fail as it will be seen as a duplicate name. Guide to National Student Index - GINS 6.8 final.docx Page 20 of 169

21 If your customer needs to change any details on an existing alternate name, they need to contact the Ministry of Education Service Desk and request that the alternate name is delated. They can then add the alternate name with its correct details. 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 MoE Service Desk with supporting documentation to get the birth date updated. Where a user attempts to update a birth date through the legacy interfaces (XML, SOAP, and Batch) and does not meet the rules to be able to do so, the NSI system will return error #305. Through the REST interface, the NSI system will return error #957. Verified NSI Records Users cannot update name and birth date information when it is verified on a student record (unless the birth date is being modified and it is in one of the scenarios given above). Residential status information can be modified unless it is verified by Birth register or by MoE. Where an organisation has evidence that the verified details of a student are incorrect, a challenge can be raised on the web interface and supporting documentation can be forwarded to the MoE Service Desk who can update the record. Where an NSI record already has a verified name and a user wishes to add another name by which the student is known, whether verified or not, this name can be added as an alternative name. Error messages Where a user attempts to modify either name or birth date and it is verified, the following message will be returned. Where Name & birth date verification is any verification other than Birth register and is not verified or verification is confirmed by MoE and a user is modifying name and/or Birth date and/or Name & birth date verification 274 Cannot modify verified data. Guide to National Student Index - GINS 6.8 final.docx Page 21 of 169

22 Where Name & birth date verification is Birth register and a user is modifying name and / or Birth date AND where Residential status verification is Birth register and a user is modifying Residential status 369 BDM verified fields cannot be modified. Where Name & birth date verification is any verification other than Birth register and is verified or verification is confirmed by MoE and a user is modifying name and / or Birth date AND where Residential status verification is verified or verification is confirmed by MoE and a user is modifying Residential status 290 Cannot change Ministry of Education verified data. Editable fields 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: Guide to National Student Index - GINS 6.8 final.docx Page 22 of 169

23 Editable fields Gender Preferred name indicator Record status and Reason (MoE only) Date of Death (MoE only) Insert-able fields Alternative name Alternative name verification (not M Birth register) 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 MoE Service desk to be considered and approved or declined as appropriate. (They may request supporting documentation to justify the Merge request, for example, a Guide to National Student Index - GINS 6.8 final.docx Page 23 of 169

24 copy of a marriage certificate may be supplied to support a merge of records with two very different names). Merge rejected: Where the submitted records are not appropriate for a merge request (e.g. too many NSNs submitted, Invalid NSNs submitted) the merge request will be rejected. The user will need to rectify the error and re-submit the request. 3.7 Change Notifications The change notification facility communicates NSI student data changes to organisations that have requested to know about the changes. Where an organisation has requested to receive change notifications (arrange this via MoE Service Desk), they will be able to receive notification of changes to NSI records that are recorded as having a Student-Provider relationship (SPR) with that organisation. 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 Decimal Value Guide to National Student Index - GINS 6.8 final.docx Page 24 of 169

25 Changed Field forename3 16 gender 32 preferred_name_indicator 64 dob 128 dod 256 name_dob_verification 512 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 MoE Service Desk 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. Guide to National Student Index - GINS 6.8 final.docx Page 25 of 169

26 The list of students SPR s is maintained within the NSI. When an NSI record is added or updated by an organisation, an SPR is created (or updated if it already exists) between the student and the organisation. The duration of an SPR for a student is determined by the SPR duration for each provider. The SPR duration specifies how long a Student-Provider relationship will exist between the provider and student. The default period is 1 year, any alteration to this period may be advised to the MoE Service Desk. When the SPR duration between the organisation and that student is reached, the relationship will be marked as expired but will not be deleted. This allows historical relationship information to be recorded. SPRs can be maintained through the REST and Batch Interfaces through the following services: REST: Create/update SPR Batch: ATA file upload. SPRs may be maintained for the following reasons: A provider re enrols a student, but has no updates to make to the student s details. Updating their SPR will ensure the provider receives Change Notifications about the student prior to the provider submitting their SDR information. A provider wishes to amend the default relationship period for a student. (Note if a different SPR duration is desired to be applied to all students for a provider it is recommended that the SPR duration for the provider is updated. This can be done by contacting MoE Service Desk.) Guide to National Student Index - GINS 6.8 final.docx Page 26 of 169

27 4 Web Interface 4.1 Overview The NSI web interface allows all of the NSI functions to be accessed over the Internet. Simply access the Ministry s NSI web interface, ( login using your Education Sector Authentication (ESAA) login. The following functions will be available to you via the Web Interface: Student search Add Student View Student (including History) Modify a Student Request merges View Merge Request status Raise a Challenge View or download change notification result files Upload or download batch files as required Access reports Actions performed against the NSI database using the web interface are effected immediately, with users performing NSI-based actions interactively. Transferring data from your SMS to the NSI and back again will be a manual operation via the web interface. The web interface is not designed to be integrated with an SMS. The NSI web interface Uniform Resource Locator (URL) could be integrated with your SMS to make the linking from your system to the NSI as seamless as possible, although this is not required. You may also choose to have the NSI web interface URL recorded as a favourite in your web browser. The NSI web interface URL is: Once you have launched a browser and have logged into the NSI web interface, the NSI functionality is there and ready to be used. The best place to learn more about how to use and navigate around the NSI web interface is the NSI Web Interface User Guide. See Appendix D for the link to this document. Guide to National Student Index - GINS 6.8 final.docx Page 27 of 169

28 The following browser versions were supported by the Ministry at the time this document was written 1 : Browser Internet Version Internet Explorer Version Firefox Current Version (mid 2014) Chrome Current Version (mid 2014) In order to use the site successfully, browsers will need to be JavaScript enabled. 4.2 Security and Authentication When entering the web interface, you will be prompted to enter your user name and password. The MoE Service Desk must have established this for you in order for you to gain access. If you require this to be set up for you, please either contact the MoE Service Desk ( or service.desk@education.govt.nz) Any NSI session will time out after 20 minutes of inactivity. Users will be required to log into NSI again in order to continue using the functionality. The 20 minutes starts from when the session token is issued and is reset each time there activity against the NSI database. 1 Here supported means that the browser or operating system has been tested and is known to enable the core functionality of the NSI system. Guide to National Student Index - GINS 6.8 final.docx Page 28 of 169

29 5 REST Interface This section explains the necessary requirements to enable your application to integrate with the National Student Index (NSI) system using the REST interface and the NSI functionality available through REST. 5.1 What is REST? REST (REpresentation State Transfer) is a common standard for online interfaces. It uses a definition of a resource (e.g. a student), and allows a range of actions for it. The HTTP protocol is leveraged to communicate more clearly: Different HTTP verbs are used (GET, PUT (update), POST (create), etc) HTTP response codes help differentiate success, security checking and validation responses. The URL helps describe which resource is being accessed (e.g. /student/13), HTTP headers are used to transmit auxiliary information not part of the resource e.g.: The security token. 5.2 Accessing the API Base URL for all API queries: 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.8 final.docx Page 29 of 169

30 5.3 Authentication ESAA OAuth Authentication to the NSI REST interface involves MoE s ESAA single sign-on (SSO) platform. To login to the NSI system, you are required to have signed in with the ESAA SSO, and have retrieved a valid ESAA token. Logging into the NSI system will return an NSI auth token, which will be required for all subsequent NSI API calls. This NSI token will be supplied in the HTTP header not part of the main body payload. See Appendix E for REST code examples. Diagram NSI Login sequence: Guide to National Student Index - GINS 6.8 final.docx Page 30 of 169

31 5.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 an Education Sector Authentication application Each user of NSI must have a user id in the Education Sector Authentication application and this user id controls their access to functions within NSI. The Education Sector Authentication application (ESAA as at 2016) allows the provisioning of machine accounts and Individual user accounts. If a user 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.8 final.docx Page 31 of 169

32 5.3.3 Privilege levels ESAA provides users with one of the following levels of 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) HTTP Code Response API details Naming standard MoE has chosen title case as its naming standard for entities and resource names. This simply means that names all start with a capital letter. E.g.: A hypothetical example: { FamilyName : <family name>, "Given1Name : <given name (1)>, "BirthDate": <birth date>, "NameBirthDateVerification: <name & birth date verification> } Guide to National Student Index - GINS 6.8 final.docx Page 32 of 169