SID:Servicebeschrijvingen: verschil tussen versies
k (→Response) |
|||
(26 tussenliggende versies door 2 gebruikers niet weergegeven) | |||
Regel 1: | Regel 1: | ||
+ | = Services = |
||
+ | |||
+ | == Create Stem Pseudonym == |
||
+ | |||
+ | {|class="wikitable" |
||
+ | ! SERVICE DESCRIPTION |
||
+ | ! retrieveStempseudonym |
||
+ | |- |
||
+ | | CONTEXT |
||
+ | | This service is called by allowed LAS systems to obtain a stem pseudonym for, for instance, a just enrolled student. This function is called during the process of enrollment, and its availability is business critical. |
||
+ | |- |
||
+ | | INPUT |
||
+ | | |
||
+ | * hpgn: HPgn, oblig, hashed PGN; |
||
+ | |- |
||
+ | | VALIDATIONS |
||
+ | | |
||
+ | * The calling system, identified by its OIN in the SerialNumber field of the Certificate, is checked against the list of allowed callers (NotAllowedCallerException on failure) |
||
+ | * The calling school is identified from the OIN in the wsa:from SOAP header. If the school is not in the list of allowed schools, a NotAllowedCallerException will be thrown |
||
+ | * hashed PGN: format validations (InvalidHPgnException on failure) |
||
+ | |- |
||
+ | | OPERATION |
||
+ | | The service derives a stem pseudonym from the input. The derivation of a valid stem pseudonym is performed by a component that is specified in software configuration. |
||
+ | |- |
||
+ | | OUTPUT |
||
+ | | stempseudonym: The generated stem pseudonym |
||
+ | |- |
||
+ | | EXCEPTIONS |
||
+ | | |
||
+ | * NotAllowedCallerException |
||
+ | * HashOperationException (indicates server configuration error) |
||
+ | |- |
||
+ | | REMARKS |
||
+ | | |
||
+ | * |
||
+ | |- |
||
+ | | SAMPLE |
||
+ | | [[SID:SampleRetrieveStempseudonym|Sample request and response]] |
||
+ | |} |
||
+ | |||
== Create ECK ID == |
== Create ECK ID == |
||
− | {| |
+ | {|class="wikitable" |
! SERVICE DESCRIPTION |
! SERVICE DESCRIPTION |
||
! retrieveEckId |
! retrieveEckId |
||
Regel 10: | Regel 50: | ||
| INPUT |
| INPUT |
||
| |
| |
||
+ | * Stempseudonym: Stem pseudonym, obtained with ‘retrieveStempseudonym’ |
||
− | * hpgn: HPgn, oblig, hashed PGN; |
||
* chainID: xsd:string, oblig, Identifier for ECK chain |
* chainID: xsd:string, oblig, Identifier for ECK chain |
||
* sectorID: xsd:string, oblig, Identifier for educational sector |
* sectorID: xsd:string, oblig, Identifier for educational sector |
||
Regel 18: | Regel 58: | ||
* The calling system, identified by its OIN in the SerialNumber field of the Certificate, is checked against the list of allowed callers (NotAllowedCallerException on failure) |
* The calling system, identified by its OIN in the SerialNumber field of the Certificate, is checked against the list of allowed callers (NotAllowedCallerException on failure) |
||
* The calling school is identified from the OIN in the wsa:from SOAP header. If the school is not in the list of allowed schools, a NotAllowedCallerException will be thrown |
* The calling school is identified from the OIN in the wsa:from SOAP header. If the school is not in the list of allowed schools, a NotAllowedCallerException will be thrown |
||
− | * |
+ | * Stem pseudonym, SectorID, ChainID: format validations (Format Exception specific for argument on failure, e.g. InvalidStemPseudonymException, InvalidChainIdException and InvalidSectorIdException). |
* SectorID is one of the IDs of educational sectors (InvalidSectorIdException on failure). |
* SectorID is one of the IDs of educational sectors (InvalidSectorIdException on failure). |
||
* ChainID is one of the IDs in chains (InvalidChainIdException on failure) |
* ChainID is one of the IDs in chains (InvalidChainIdException on failure) |
||
Regel 27: | Regel 67: | ||
The service combines the three inputs and from the result derives a valid ECK ID. The derivation of a valid ECK ID is performed by a component that is specified in software configuration. |
The service combines the three inputs and from the result derives a valid ECK ID. The derivation of a valid ECK ID is performed by a component that is specified in software configuration. |
||
− | If the provided |
+ | If the provided stem pseudonymis in substitutionList.new and sectorID is equal to the substitutionlist.sectorID and today is later than substitutiontable.effectivedate, the previous stem pseudonym is used to derive the ECK ID from. |
|- |
|- |
||
| OUTPUT |
| OUTPUT |
||
Regel 35: | Regel 75: | ||
| |
| |
||
* InvalidSectorIdException InvalidChainIdException InvalidHPgnException |
* InvalidSectorIdException InvalidChainIdException InvalidHPgnException |
||
+ | * BlockedStempseudonymException |
||
− | * BlockedHPgnException |
||
* NotAllowedCallerException |
* NotAllowedCallerException |
||
* HashOperationException (indicates server configuration error) |
* HashOperationException (indicates server configuration error) |
||
Regel 41: | Regel 81: | ||
| REMARKS |
| REMARKS |
||
| |
| |
||
− | * hpgn is created using scrypt with the prescribed parameters. See the developer documentation on the wiki<ref>https://developers.wiki.kennisnet.nl/index.php?title=SID:Hoofdpagina</ref>. |
||
* chainID, sectorID are in the form of OBK URN’s. Retrieve these values using the retrieveChains, retrieveSectors operations respectively. |
* chainID, sectorID are in the form of OBK URN’s. Retrieve these values using the retrieveChains, retrieveSectors operations respectively. |
||
− | * eckID is in the form of a URL: |
+ | * eckID is in the form of a URL: <nowiki>https://id.school/201703/[128-char]</nowiki> hex string. |
+ | |- |
||
+ | | SAMPLE |
||
+ | | [[SID:SampleRetrieveECKID|Sample request and response]] |
||
|} |
|} |
||
− | == |
+ | == Substitute PGN for Stem pseudonym == |
− | {| |
+ | {|class="wikitable" |
! SERVICE DESCRIPTION |
! SERVICE DESCRIPTION |
||
+ | ! replaceStempseudonym |
||
− | ! replaceEckId |
||
|- |
|- |
||
| CONTEXT |
| CONTEXT |
||
− | | This service is called when a school administration needs to indicate that a student is assigned a new PGN by the authorities. A change of PGN number is handled as follows: |
+ | | This service is called when a school administration needs to indicate that a student is assigned a new PGN by the authorities. A change of PGN number is handled as follows: |
+ | # The old and the new stem hashed PGN are recorded in the database. |
||
+ | # Subsequent requests for the old hashed PGN are rejected. |
||
+ | # For requests with the new stem hashed PGN, the old hashed PGN is used to derive the stem pseudonym from. |
||
+ | See also service description Create stempseudonym. |
||
|- |
|- |
||
| INPUT |
| INPUT |
||
| |
| |
||
− | * |
+ | * hPGNOld, hPGNNew: oblig, resp. previous hashed PGN and new hashed PGN |
+ | * effectiveDate: Date and time that the change should take effect. Date <b>in full gregorian calendar format</b>, like "2017-01-01T11:26:30.806+01:00". Optional, 'now' if not given. |
||
− | * chainID: xsd:string, oblig, Identifier for ECK chain |
||
+ | |||
− | * sectorID: xsd:string, oblig, Identifier for educational sector |
||
− | * effectiveDate: xsd:date, optional, ‘now’ if not given, date and time that the change should take effect |
||
|- |
|- |
||
| VALIDATIONS |
| VALIDATIONS |
||
Regel 67: | Regel 112: | ||
* The calling school is identified from the OIN in the wsa:from header. If the school is not in the list of allowed schools, a NotAllowedCallerException will be thrown |
* The calling school is identified from the OIN in the wsa:from header. If the school is not in the list of allowed schools, a NotAllowedCallerException will be thrown |
||
* Format validations on input arguments (format Exception specific for argument on failure). |
* Format validations on input arguments (format Exception specific for argument on failure). |
||
+ | * Old hPGN is not already in the substitution table (old and new) (BlockedPGNException otherwise) |
||
− | * SectorID is one of the IDs of educational sectors (InvalidSectorIdException on failure). |
||
+ | * New hPGN is not already in the substitution table (old and new) (BlockedPGNException otherwise) |
||
− | * ChainID is one of the IDs in chains (InvalidChainIdException on failure) |
||
+ | * Old and new hPGN are different (substitutionOperationException otherwise) |
||
− | * Old hashed pgn is not already in the substitution table (old and new) (InvalidPgnException otherwise) |
||
+ | * Effective date: if given, is valid and in the future (xml parse error in case of invalid date format) |
||
− | * New hashed pgn is not already in the substitution table (old and new) (InvalidPgnException otherwise) |
||
− | * Effective date: if given, is valid and in the future(xml parse error in case of invalid date format)) |
||
|- |
|- |
||
| OPERATION |
| OPERATION |
||
− | | Old |
+ | | Old hPGN, new hPGN are recorded in the substitution table, and a stem pseudonym for the new hPGN is derived using function ‘Create stem pseudonym’. |
|- |
|- |
||
| OUTPUT |
| OUTPUT |
||
− | | |
+ | | stem pseudonym: The stem pseudonym for the new hpgn |
|- |
|- |
||
| EXCEPTIONS |
| EXCEPTIONS |
||
| |
| |
||
+ | * InvalidhPGNException with information on which stem pseudonym is invalid, and why |
||
− | * InvalidSectorIdException |
||
+ | * SubstitutionOperationException |
||
− | * InvalidChainIdException |
||
− | * InvalidPgnException with information on which hashed PGN is invalid, and why |
||
− | * BlockedHPgnException |
||
* NotAllowedCallerException |
* NotAllowedCallerException |
||
* HashOperationException (indicates server configuration error) |
* HashOperationException (indicates server configuration error) |
||
− | * |
||
|- |
|- |
||
| REMARKS |
| REMARKS |
||
| |
| |
||
+ | * Stem pseudonym is in the form of a URL: <nowiki>https://id.school/201703/[128-char hex string]</nowiki>. |
||
− | * hpgnOld, hpgnNew is created using scrypt with the prescribed parameters. See the developer documentation on the wiki<ref>https://developers.wiki.kennisnet.nl/index.php?title=SID:Hoofdpagina</ref>. |
||
+ | |- |
||
− | * chainID, sectorID are in the form of OBK URN’s. Retrieve these values using the retrieveChains, retrieveSectors operations respectively. |
||
+ | | SAMPLE |
||
− | * eckID is in the form of a URL: [https://id.school/2015-09/%5b128-char https://id.school/2015-09/[128-char] hex string]. Currently this url resolves to a static page containing info about the ECK ID. |
||
+ | | [[SID:SampleReplaceStempseudonym|Sample request and response]] |
||
+ | |} |
||
+ | |||
+ | == Batch creation of stem pseudonyms == |
||
+ | |||
+ | {|class="wikitable" |
||
+ | ! SERVICE DESCRIPTION |
||
+ | ! submitStempseudonymBatch |
||
+ | |- |
||
+ | | CONTEXT |
||
+ | | This service is called by allowed LAS systems to submit a list of stem pseudonyms, for a single Sector and a single Chain. The system processes the list and makes a corresponding list of stem pseudonyms available for retrieval (see retrieveEckBatch). |
||
+ | |- |
||
+ | | INPUT |
||
+ | | |
||
+ | * stempseudonymList: a list of 1..20.000<ref>The size of the array is comfigured in software. Actual limit may differ.</ref> |
||
+ | ** int: xsd:int, oblig, sequence number |
||
+ | ** hPgn: HPgn hashed PGNs |
||
+ | |- |
||
+ | | VALIDATIONS |
||
+ | | |
||
+ | * The calling system identified by its OIN in the Certificate is checked against the list of allowed callers (NotAllowedCaller Exception on failure) |
||
+ | * The calling school is identified from the OIN in the wsa:from header. If the school is not in the list of allowed schools, a NotAllowedCallerException will be thrown |
||
+ | * The system validates the size of the input (TemporaryBannedException if too many hPgns are submitted) |
||
+ | * All indexes are unique (DuplicateIndexBatchListException otherwise) |
||
+ | |- |
||
+ | | OPERATION |
||
+ | | The service creates a stem pseudonym for each hashed PGN in the input list and adds it to the list of generated stem pseudonyms for output. If the list does not contain a hashed PGN or if the hashed PGN was previously indicated as changed, no stem pseudnym will be created and a message to indicate the nature of the failure will be added to the list of failed items for output. |
||
+ | |- |
||
+ | | OUTPUT |
||
+ | | |
||
+ | * batchIdentifier: xsd:string, identifier of the batch request. This identifier can be used to obtain the result, using retrieveEckBatch |
||
+ | |- |
||
+ | | EXCEPTIONS |
||
+ | | |
||
+ | * InvalidSectorIdException InvalidChainIdException InvalidHPgnException |
||
+ | * NotAllowedCallerException |
||
+ | * HashOperationException (indicates server configuration error) |
||
+ | * DuplicateIndexBatchListException |
||
+ | |- |
||
+ | | REMARKS |
||
+ | | |
||
+ | The use of this service is limited to prevent abuse: |
||
+ | |||
+ | * A batch may contain at most 20.000 hashed PGNs |
||
+ | * A batch operation may be submitted at most 3 times per 24 hours |
||
+ | |||
+ | These limits are configured in the software and can be modified. Schools that exceed these limits are temporarily banned from submitting batch requests. Schools may contact Kennisnet servicedesk for information and for lifting of the bans. Schools may submit multiple batch requests, as long as the limits are observed. Batches are processed in the order in which they occur. |
||
+ | |||
+ | A batch result is available within one hour after submission of the request. Batch results are removed after successful retrieval. The system may remove batch results that are not retrieved within 24 hours. |
||
+ | |- |
||
+ | | SAMPLE |
||
+ | | [[SID:SampleRetrieveBatchStempseudonym|Sample request and response]] |
||
|} |
|} |
||
== Batch creation of ECK IDs == |
== Batch creation of ECK IDs == |
||
− | {| |
+ | {|class="wikitable" |
! SERVICE DESCRIPTION |
! SERVICE DESCRIPTION |
||
! submitEckIdBatch |
! submitEckIdBatch |
||
|- |
|- |
||
| CONTEXT |
| CONTEXT |
||
− | | This service is called by allowed LAS systems to submit a list of |
+ | | This service is called by allowed LAS systems to submit a list of stem pseudnyms, for a single Sector and a single Chain. The system processes the list and makes a corresponding list of ECK IDs available for retrieval (see retrieveEckBatch). |
|- |
|- |
||
| INPUT |
| INPUT |
||
| |
| |
||
− | * |
+ | * stempseudonymList: a list of 1..20.000<ref>The size of the array is comfigured in software. Actual limit may differ.</ref> |
** int: xsd:int, oblig, sequence number |
** int: xsd:int, oblig, sequence number |
||
+ | ** stempseudonym: Stem pseudonym |
||
− | ** hPgn: HPgn hashed PGNs |
||
* chainID: xsd:string, oblig, Identifier for ECK chain |
* chainID: xsd:string, oblig, Identifier for ECK chain |
||
* sectorID: xsd:string, oblig, Identifier for educational sector |
* sectorID: xsd:string, oblig, Identifier for educational sector |
||
Regel 117: | Regel 210: | ||
* The calling system identified by its OIN in the Certificate is checked against the list of allowed callers (NotAllowedCaller Exception on failure) |
* The calling system identified by its OIN in the Certificate is checked against the list of allowed callers (NotAllowedCaller Exception on failure) |
||
* The calling school is identified from the OIN in the wsa:from header. If the school is not in the list of allowed schools, a NotAllowedCallerException will be thrown |
* The calling school is identified from the OIN in the wsa:from header. If the school is not in the list of allowed schools, a NotAllowedCallerException will be thrown |
||
− | * The system validates the size of the input (TemporaryBannedException if too many |
+ | * The system validates the size of the input (TemporaryBannedException if too many stem pseudonyms are submitted) |
+ | * All indexes are unique (DuplicateIndexBatchListException otherwise) |
||
* SectorID is one of the IDs of educational sectors (InvalidSectorIdException on failure). |
* SectorID is one of the IDs of educational sectors (InvalidSectorIdException on failure). |
||
* ChainID is one of the IDs in chains (InvalidChainIdException on failure) |
* ChainID is one of the IDs in chains (InvalidChainIdException on failure) |
||
− | * |
+ | * Stempseudonyms is not in substitutionList.old (offending stem pseudonym is added to the failed list for output) |
|- |
|- |
||
| OPERATION |
| OPERATION |
||
Regel 135: | Regel 229: | ||
* NotAllowedCallerException |
* NotAllowedCallerException |
||
* HashOperationException (indicates server configuration error) |
* HashOperationException (indicates server configuration error) |
||
+ | * DuplicateIndexBatchListException |
||
− | * |
||
|- |
|- |
||
| REMARKS |
| REMARKS |
||
Regel 141: | Regel 235: | ||
The use of this service is limited to prevent abuse: |
The use of this service is limited to prevent abuse: |
||
− | * A batch may contain at most 20.000 |
+ | * A batch may contain at most 20.000 entries |
* A batch operation may be submitted at most 3 times per 24 hours |
* A batch operation may be submitted at most 3 times per 24 hours |
||
Regel 147: | Regel 241: | ||
A batch result is available within one hour after submission of the request. Batch results are removed after successful retrieval. The system may remove batch results that are not retrieved within 24 hours. |
A batch result is available within one hour after submission of the request. Batch results are removed after successful retrieval. The system may remove batch results that are not retrieved within 24 hours. |
||
+ | |- |
||
+ | | SAMPLE |
||
+ | | [[SID:SampleBatchECKID|Sample request and response]] |
||
|} |
|} |
||
+ | =Batch results retrieval= |
||
− | {| class="wikitable" |
||
+ | |||
+ | {|class="wikitable" |
||
! SERVICE DESCRIPTION |
! SERVICE DESCRIPTION |
||
+ | ! retrieveBatch |
||
− | ! retrieveEckIdBatch |
||
|- |
|- |
||
| CONTEXT |
| CONTEXT |
||
Regel 165: | Regel 264: | ||
* The calling school is identified from the OIN in the wsa:from header. If the school is not in the list of allowed schools, a NotAllowedCallerException will be thrown |
* The calling school is identified from the OIN in the wsa:from header. If the school is not in the list of allowed schools, a NotAllowedCallerException will be thrown |
||
* The system validates the frequency of calls (SchoolTemporaryBlockedException or BatchTemporaryBlockedException if there are too many calls registered) |
* The system validates the frequency of calls (SchoolTemporaryBlockedException or BatchTemporaryBlockedException if there are too many calls registered) |
||
+ | * The batch result can be retrieved at most once; ContentAlreadyRetrievedException is returned if the batch was retrieved earlier |
||
− | * If the batch indicated by the input is purged, already retrieved, or not ready yet, a BatchRetrieveException is returned |
||
+ | * If the batch indicated by the input is purged, already retrieved, or not ready yet, a NotFinishedException is returned |
||
|- |
|- |
||
| OPERATION |
| OPERATION |
||
+ | | The service retrieves the batch result (either StempseudonymBatch or EckIdBatch), if available, and returns it to the caller. If an error during check or processing occurs, the error is returned. |
||
− | | The service creates a ECK ID for each hashed PGN in the input list and adds it to the list of generated ECK IDs for output. If the list does not contain a hashed PGN or if the hashed PGN was previously indicated as changed, no ECK ID will be created and a message to indicate the nature of the failure will be added to the list of failed PGNs for output. |
||
|- |
|- |
||
| OUTPUT |
| OUTPUT |
||
| |
| |
||
* Success: an optional list of 1..20000<ref>Limit is set in in software configuration; actual values may differ</ref>: |
* Success: an optional list of 1..20000<ref>Limit is set in in software configuration; actual values may differ</ref>: |
||
− | ** Index: int, the sequence number of the corresponding |
+ | ** Index: int, the sequence number of the corresponding entry from the input |
− | ** EckId: EckId, the ECK ID of the |
+ | ** EckId: EckId, the ECK ID of the entry indicated by the sequence number from the input |
* Failed: an optional list of 1..20000<ref>Idem</ref>: |
* Failed: an optional list of 1..20000<ref>Idem</ref>: |
||
− | ** Index: int, the sequence number of the corresponding |
+ | ** Index: int, the sequence number of the corresponding entry from the input |
** errorMessage: string, indication of the error that occurred when computing the ECK ID |
** errorMessage: string, indication of the error that occurred when computing the ECK ID |
||
|- |
|- |
||
Regel 188: | Regel 288: | ||
* HashOperationException (indicates server configuration error) |
* HashOperationException (indicates server configuration error) |
||
* SchoolTemporaryBlockedException, BatchTemporaryBlockedException |
* SchoolTemporaryBlockedException, BatchTemporaryBlockedException |
||
+ | * ContentAlreadyRetrievedException |
||
− | * BatchRetrieveException |
||
+ | * NotFinishedException |
||
+ | * |
||
|- |
|- |
||
| REMARKS |
| REMARKS |
||
Regel 197: | Regel 299: | ||
In the output of this function, both success and failure are optional arrays. If none of the input fail, the response will contain only ‘success’ values. If none of the input succeed, the response will contain only ‘failure’. |
In the output of this function, both success and failure are optional arrays. If none of the input fail, the response will contain only ‘success’ values. If none of the input succeed, the response will contain only ‘failure’. |
||
+ | |- |
||
+ | | SAMPLE |
||
+ | | [[SID:SampleRetrieveBatch|Sample request and response]] |
||
|} |
|} |
||
== Retrieving chains and sectors == |
== Retrieving chains and sectors == |
||
− | {| |
+ | {|class="wikitable" |
! SERVICE DESCRIPTION |
! SERVICE DESCRIPTION |
||
! retrieveChains |
! retrieveChains |
||
|- |
|- |
||
| CONTEXT |
| CONTEXT |
||
− | | This service is called by allowed LAS systems to obtain the |
+ | | This service is called by allowed LAS systems to obtain the value of the ECK chain ID, for which an ECK ID can be derived. As this list changes rarely, this service will not be called often, probably not more than once per day per LAS. |
|- |
|- |
||
| INPUT |
| INPUT |
||
Regel 236: | Regel 341: | ||
|} |
|} |
||
− | {| |
+ | {|class="wikitable" |
! SERVICE DESCRIPTION |
! SERVICE DESCRIPTION |
||
! retrieveSectors |
! retrieveSectors |
||
Regel 278: | Regel 383: | ||
== Ping operation == |
== Ping operation == |
||
− | {| |
+ | {|class="wikitable" |
! SERVICE DESCRIPTION |
! SERVICE DESCRIPTION |
||
! pingRequest |
! pingRequest |
||
Regel 309: | Regel 414: | ||
* |
* |
||
|} |
|} |
||
− | |||
− | = Sample Messages = |
||
− | |||
− | Please note, input arguments are provided as sample only and may not be valid in production environments. |
||
− | |||
− | == RetrieveEckID == |
||
− | |||
− | === Request === |
||
− | <syntaxhighlight lang="xml"> |
||
− | <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" |
||
− | xmlns:v1="http://id.school/eck/schemas/v1_0" |
||
− | xmlns:a="http://www.w3.org/2005/08/addressing"> |
||
− | <soapenv:Header> |
||
− | <a:Action soapenv:mustUnderstand="1"> |
||
− | http://id.school/eck/schemas/v1_0/retrieveEckId |
||
− | </a:Action> |
||
− | <a:From soapenv:mustUnderstand="1"> |
||
− | <a:Address> |
||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 12345678901234567890 |
||
− | </a:Address> |
||
− | </a:From> |
||
− | <a:MessageID soapenv:mustUnderstand="1"> |
||
− | uuid:218f8239-9952-4e19-8176-38f629967e3c |
||
− | </a:MessageID> |
||
− | <a:To soapenv:mustUnderstand="1"> |
||
− | https://service-a.id.school/eck/ws/201509 |
||
− | </a:To> |
||
− | </soapenv:Header> |
||
− | <soapenv:Body> |
||
− | <v1:retrieveEckIdRequest> |
||
− | <v1:hpgn>123456789</v1:hpgn> |
||
− | <v1:chainId> |
||
− | http://purl.edustandaard.nl/begrippenkader/e7ec7d3c-c235-4513-bfb6-e54e66854795 |
||
− | </v1:chainId> |
||
− | <v1:sectorId> |
||
− | http://purl.edustandaard.nl/begrippenkader/512e4729-03a4-43a2-95ba-758071d1b725 |
||
− | </v1:sectorId> |
||
− | </v1:retrieveEckIdRequest> |
||
− | </soapenv:Body> |
||
− | </soapenv:Envelope> |
||
− | </syntaxhighlight> |
||
− | |||
− | === Response === |
||
− | <syntaxhighlight lang="xml"> |
||
− | <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> |
||
− | <soap:Header> |
||
− | <Action xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | http://id.school/eck/schemas/v1_0/SchoolID/retrieveEckIdResponse |
||
− | </Action> |
||
− | <MessageID xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | urn:uuid:f80d16f5-e526-4754-b3f8-76995138de7c |
||
− | </MessageID> |
||
− | <To xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 12345678901234567890 |
||
− | </To> |
||
− | <RelatesTo xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | uuid:7b44c0c9-a8eb-45ae-9aa1-2af9599f3375 |
||
− | </RelatesTo> |
||
− | <From xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | <Address> |
||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 00000003272400000000 |
||
− | </Address> |
||
− | </From> |
||
− | </soap:Header> |
||
− | <soap:Body> |
||
− | <retrieveEckIdResponse xmlns="http://id.school/eck/schemas/v1_0"> |
||
− | <eckId> |
||
− | https://id.school/pilot/8078d3...28bc85 |
||
− | </eckId> |
||
− | </retrieveEckIdResponse> |
||
− | </soap:Body> |
||
− | </soap:Envelope> |
||
− | </syntaxhighlight> |
||
− | |||
− | === Example error response === |
||
− | |||
− | <syntaxhighlight lang="xml"> |
||
− | <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> |
||
− | <soap:Header> |
||
− | <Action xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | http://id.school/eck/schemas/v1_0/SchoolID/retrieveEckId/Fault/NotAllowedCallerException |
||
− | </Action> |
||
− | <MessageID xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | urn:uuid:f8a78500-5e82-4fe5-9853-eaab78d819aa</MessageID> |
||
− | <To xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 12345678901234567890 |
||
− | </To> |
||
− | <RelatesTo xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | uuid:218f8239-9952-4e19-8176-38f629967e3c</RelatesTo> |
||
− | <From xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | <Address> |
||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 00000003272400000000 |
||
− | </Address> |
||
− | </From> |
||
− | </soap:Header> |
||
− | <soap:Body> |
||
− | <soap:Fault> |
||
− | <faultcode>soap:Server</faultcode> |
||
− | <faultstring> |
||
− | Uw Bevoegd Gezag is nog niet geautoriseerd voor het gebruik van de Nummervoorziening. |
||
− | </faultstring> |
||
− | </soap:Fault> |
||
− | </soap:Body> |
||
− | </soap:Envelope> |
||
− | </syntaxhighlight> |
||
− | |||
− | == Replace EckID == |
||
− | |||
− | <syntaxhighlight lang="xml"> |
||
− | <soapenv:Envelope |
||
− | xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" |
||
− | xmlns:v1="http://id.school/eck/schemas/v1_0"> |
||
− | <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"> |
||
− | <wsa:Action soapenv:mustUnderstand="1"> |
||
− | http://id.school/eck/schemas/v1_0/replaceEckId |
||
− | </wsa:Action> |
||
− | <wsa:From soapenv:mustUnderstand="1"> |
||
− | <wsa:Address> |
||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 12345678901234567890 |
||
− | </wsa:Address> |
||
− | </wsa:From> |
||
− | <wsa:MessageID soapenv:mustUnderstand="1"> |
||
− | uuid:bb3af1a4-55fe-418f-9d65-87217ebe4cc7 |
||
− | </wsa:MessageID> |
||
− | <wsa:To soapenv:mustUnderstand="1"> |
||
− | https://service-a.id.school/eck/ws/201509 |
||
− | </wsa:To> |
||
− | </soapenv:Header> |
||
− | <soapenv:Body> |
||
− | <v1:replaceEckIdRequest> |
||
− | <v1:hpgnOld>Antoinette</v1:hpgnOld> |
||
− | <v1:hpgnNew>Beatrijs</v1:hpgnNew> |
||
− | <v1:chainId> |
||
− | http://purl.edustandaard.nl/begrippenkader/e7ec7d3c-c235-4513-bfb6-e54e66854795 |
||
− | </v1:chainId> |
||
− | <v1:sectorId> |
||
− | http://purl.edustandaard.nl/begrippenkader/2a1401e9-c223-493b-9b86-78f6993b1a8d |
||
− | </v1:sectorId> |
||
− | </v1:replaceEckIdRequest> |
||
− | </soapenv:Body> |
||
− | </soapenv:Envelope> |
||
− | </syntaxhighlight> |
||
− | |||
− | <syntaxhighlight lang="xml"> |
||
− | <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> |
||
− | <soap:Header> |
||
− | <Action xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | http://id.school/eck/schemas/v1_0/SchoolID/replaceEckIdResponse |
||
− | </Action> |
||
− | <MessageID xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | urn:uuid:d906b6fd-3806-45e8-b9c9-d8775fbb6fd7 |
||
− | </MessageID> |
||
− | <To xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 12345678901234567890 |
||
− | </To> |
||
− | <RelatesTo xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | uuid:bb3af1a4-55fe-418f-9d65-87217ebe4cc7 |
||
− | </RelatesTo> |
||
− | <From xmlns="http://www.w3.org/2005/08/addressing"> |
||
− | <Address> |
||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 00000003272400000000 |
||
− | </Address> |
||
− | </From> |
||
− | </soap:Header> |
||
− | <soap:Body> |
||
− | <replaceEckIdResponse xmlns="http://id.school/eck/schemas/v1_0"> |
||
− | <eckId> |
||
− | https://id.school/pilot/8a8781...96260e |
||
− | </eckId> |
||
− | </replaceEckIdResponse> |
||
− | </soap:Body> |
||
− | </soap:Envelope> |
||
− | </syntaxhighlight> |
||
− | |||
− | == Batch == |
||
− | |||
− | === Submit batch request === |
||
− | |||
− | <'''soapenv''':Envelope |
||
− | |||
− | '''xmlns''':soapenv="http://schemas.xmlsoap.org/soap/envelope/" |
||
− | |||
− | '''xmlns''':v1="http://id.school/eck/schemas/v1_0" |
||
− | |||
− | '''xmlns''':a="http://www.w3.org/2005/08/addressing"> |
||
− | |||
− | <'''soapenv''':Header> |
||
− | |||
− | <'''a''':Action '''soapenv''':mustUnderstand="1"> |
||
− | |||
− | '''http'''://id.school/eck/schemas/v1_0/submitEckIdBatch |
||
− | |||
− | </'''a''':Action> |
||
− | |||
− | <'''a''':From '''soapenv''':mustUnderstand="1"> |
||
− | |||
− | <'''a''':Address> |
||
− | |||
− | '''http'''://www.w3.org/2005/08/addressing/anonymous?oin=12345678901234567890 |
||
− | |||
− | </'''a''':Address> |
||
− | |||
− | </'''a''':From> |
||
− | |||
− | <'''a''':MessageID '''soapenv''':mustUnderstand="1"> |
||
− | |||
− | '''uuid''':47d17105-5aae-4c36-98ed-fe1147f89ee6 |
||
− | |||
− | </'''a''':MessageID> |
||
− | |||
− | <'''a''':To '''soapenv''':mustUnderstand="1"> |
||
− | |||
− | '''https'''://service-a.id.school/eck/ws/201509 |
||
− | |||
− | </'''a''':To> |
||
− | |||
− | </'''soapenv''':Header> |
||
− | |||
− | <'''soapenv''':Body> |
||
− | |||
− | <v1:submitEckIdBatchRequest> |
||
− | |||
− | <!--1 or more '''repetitions''':--> |
||
− | |||
− | <v1:hpgnList> |
||
− | |||
− | <v1:index>1</v1:index> |
||
− | |||
− | <v1:hPgn>Alexa</v1:hPgn> |
||
− | |||
− | </v1:hpgnList> |
||
− | |||
− | <v1:hpgnList> |
||
− | |||
− | <v1:index>3</v1:index> |
||
− | |||
− | <v1:hPgn>Bernadette</v1:hPgn> |
||
− | |||
− | </v1:hpgnList> |
||
− | |||
− | <v1:hpgnList> |
||
− | |||
− | <v1:index>5</v1:index> |
||
− | |||
− | <v1:hPgn>Christina</v1:hPgn> |
||
− | |||
− | </v1:hpgnList> |
||
− | |||
− | <v1:hpgnList> |
||
− | |||
− | <v1:index>7</v1:index> |
||
− | |||
− | <v1:hPgn>Delaney</v1:hPgn> |
||
− | |||
− | </v1:hpgnList> |
||
− | |||
− | <v1:chainId>'''http'''://purl.edustandaard.nl/begrippenkader/e7ec7d3c-c235-4513-bfb6-e54e66854795</v1:chainId> |
||
− | |||
− | <v1:sectorId>'''http'''://purl.edustandaard.nl/begrippenkader/f3ac3fbb-5eae-49e0-8494-0a44855fff25</v1:sectorId> |
||
− | |||
− | </v1:submitEckIdBatchRequest> |
||
− | |||
− | </'''soapenv''':Body> |
||
− | |||
− | </'''soapenv''':Envelope> |
||
− | |||
− | === Submit batch response === |
||
− | |||
− | '''<soap:Envelope''' xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"'''>''' |
||
− | |||
− | '''<soap:Header>''' |
||
− | |||
− | '''<Action''' xmlns="http://www.w3.org/2005/08/addressing"'''>''' |
||
− | |||
− | http://id.school/eck/schemas/v1_0/SchoolID/submitEckIdBatchResponse |
||
− | |||
− | '''</Action>''' |
||
− | |||
− | '''<MessageID''' xmlns="http://www.w3.org/2005/08/addressing"'''>''' |
||
− | |||
− | urn:uuid:add7a36a-ceac-41f9-a9fc-1c2fd54543d0 |
||
− | |||
− | '''</MessageID>''' |
||
− | |||
− | '''<To''' xmlns="http://www.w3.org/2005/08/addressing"'''>''' |
||
− | |||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 12345678901234567890 |
||
− | |||
− | '''</To>''' |
||
− | |||
− | '''<RelatesTo''' xmlns="http://www.w3.org/2005/08/addressing"'''>''' |
||
− | |||
− | uuid:47d17105-5aae-4c36-98ed-fe1147f89ee6 |
||
− | |||
− | '''</RelatesTo>''' |
||
− | |||
− | '''<From''' xmlns="http://www.w3.org/2005/08/addressing"'''>''' |
||
− | |||
− | '''<Address>''' |
||
− | |||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 00000003272400000000 |
||
− | |||
− | '''</Address>''' |
||
− | |||
− | '''</From>''' |
||
− | |||
− | '''</soap:Header>''' |
||
− | |||
− | '''<soap:Body>''' |
||
− | |||
− | '''<submitEckIdBatchResponse''' xmlns="http://id.school/eck/schemas/v1_0"'''>''' |
||
− | |||
− | '''<batchIdentifier>''' |
||
− | |||
− | 2016062216374691e0ed3ba7544c71ac7856be9279f15f |
||
− | |||
− | '''</batchIdentifier>''' |
||
− | |||
− | '''</submitEckIdBatchResponse>''' |
||
− | |||
− | '''</soap:Body>''' |
||
− | |||
− | '''</soap:Envelope>''' |
||
− | |||
− | === Retrieve batch request === |
||
− | |||
− | '''<soapenv:Envelope''' |
||
− | |||
− | xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" |
||
− | |||
− | xmlns:v1="http://id.school/eck/schemas/v1_0" |
||
− | |||
− | xmlns:a="http://www.w3.org/2005/08/addressing"'''>''' |
||
− | |||
− | '''<soapenv:Header>''' |
||
− | |||
− | '''<a:Action''' soapenv:mustUnderstand="1"'''>''' |
||
− | |||
− | http://id.school/eck/schemas/v1_0/retrieveEckIdBatch |
||
− | |||
− | '''</a:Action>''' |
||
− | |||
− | '''<a:From''' soapenv:mustUnderstand="1"'''>''' |
||
− | |||
− | '''<a:Address>''' |
||
− | |||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 12345678901234567890 |
||
− | |||
− | '''</a:Address>''' |
||
− | |||
− | '''</a:From>''' |
||
− | |||
− | '''<a:MessageID''' soapenv:mustUnderstand="1"'''>''' |
||
− | |||
− | uuid:4e2a772e-6b6b-4dcf-ab15-58193678e69a |
||
− | |||
− | '''</a:MessageID>''' |
||
− | |||
− | '''<a:To''' soapenv:mustUnderstand="1"'''>''' |
||
− | |||
− | https://service-a.id.school/eck/ws/201509 |
||
− | |||
− | '''</a:To>''' |
||
− | |||
− | '''</soapenv:Header>''' |
||
− | |||
− | '''<soapenv:Body>''' |
||
− | |||
− | '''<v1:retrieveEckIdBatchRequest>''' |
||
− | |||
− | '''<v1:batchIdentifier>'''2016062216374691e0ed3ba7544c71ac7856be9279f15f'''</v1:batchIdentifier>''' |
||
− | |||
− | '''</v1:retrieveEckIdBatchRequest>''' |
||
− | |||
− | '''</soapenv:Body>''' |
||
− | |||
− | '''</soapenv:Envelope>''' |
||
− | |||
− | === Retrieve batch response === |
||
− | |||
− | '''<soap:Envelope''' xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"'''>''' |
||
− | |||
− | '''<soap:Header>''' |
||
− | |||
− | '''<Action''' xmlns="http://www.w3.org/2005/08/addressing"'''>''' |
||
− | |||
− | http://id.school/eck/schemas/v1_0/SchoolID/retrieveEckIdBatchResponse |
||
− | |||
− | '''</Action>''' |
||
− | |||
− | '''<MessageID''' xmlns="http://www.w3.org/2005/08/addressing"'''>''' |
||
− | |||
− | urn:uuid:5cd37eef-cb58-4b2c-b8bc-6ccf4cc479ea |
||
− | |||
− | '''</MessageID>''' |
||
− | |||
− | '''<To''' xmlns="http://www.w3.org/2005/08/addressing"'''>''' |
||
− | |||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 12345678901234567890 |
||
− | |||
− | '''</To>''' |
||
− | |||
− | '''<RelatesTo''' xmlns="http://www.w3.org/2005/08/addressing"'''>''' |
||
− | |||
− | uuid:4e2a772e-6b6b-4dcf-ab15-58193678e69a |
||
− | |||
− | '''</RelatesTo>''' |
||
− | |||
− | '''<From''' xmlns="http://www.w3.org/2005/08/addressing"'''>''' |
||
− | |||
− | '''<Address>''' |
||
− | |||
− | http://www.w3.org/2005/08/addressing/anonymous?oin= 00000003272400000000 |
||
− | |||
− | '''</Address>''' |
||
− | |||
− | '''</From>''' |
||
− | |||
− | '''</soap:Header>''' |
||
− | |||
− | '''<soap:Body>''' |
||
− | |||
− | '''<retrieveEckIdBatchResponse''' xmlns="http://id.school/eck/schemas/v1_0"'''>''' |
||
− | |||
− | '''<success>''' |
||
− | |||
− | '''<index>'''1'''</index>''' |
||
− | |||
− | '''<eckId>'''https://id.school/pilot/bcd2a9...12b5b3'''</eckId>''' |
||
− | |||
− | '''</success>''' |
||
− | |||
− | '''<success>''' |
||
− | |||
− | '''<index>'''3'''</index>''' |
||
− | |||
− | '''<eckId>'''https://id.school/pilot/6f4411...fb2cbb'''</eckId>''' |
||
− | |||
− | '''</success>''' |
||
− | |||
− | '''<success>''' |
||
− | |||
− | '''<index>'''5'''</index>''' |
||
− | |||
− | '''<eckId>'''https://id.school/pilot/50e115...212395'''</eckId>''' |
||
− | |||
− | '''</success>''' |
||
− | |||
− | '''<success>''' |
||
− | |||
− | '''<index>'''7'''</index>''' |
||
− | |||
− | '''<eckId>'''https://id.school/pilot/742668...b6cb4'''</eckId>''' |
||
− | |||
− | '''</success>''' |
||
− | |||
− | '''</retrieveEckIdBatchResponse>''' |
||
− | |||
− | '''</soap:Body>''' |
||
− | |||
− | '''</soap:Envelope>''' |
||
= Common types = |
= Common types = |
||
Regel 829: | Regel 473: | ||
<references /> |
<references /> |
||
− | [[Category: |
+ | [[Category:Nummervoorziening]] |
+ | [[Category:Interface]] |
||
+ | [[Category:Software]] |
Versie van 26 okt 2017 12:04
Services
Create Stem Pseudonym
SERVICE DESCRIPTION | retrieveStempseudonym |
---|---|
CONTEXT | This service is called by allowed LAS systems to obtain a stem pseudonym for, for instance, a just enrolled student. This function is called during the process of enrollment, and its availability is business critical. |
INPUT |
|
VALIDATIONS |
|
OPERATION | The service derives a stem pseudonym from the input. The derivation of a valid stem pseudonym is performed by a component that is specified in software configuration. |
OUTPUT | stempseudonym: The generated stem pseudonym |
EXCEPTIONS |
|
REMARKS |
|
SAMPLE | Sample request and response |
Create ECK ID
SERVICE DESCRIPTION | retrieveEckId |
---|---|
CONTEXT | This service is called by allowed LAS systems to obtain a ECK ID for, for instance, a just enrolled student. This function is called during the process of enrollment, and its availability is business critical. |
INPUT |
|
VALIDATIONS |
|
OPERATION |
The service combines the three inputs and from the result derives a valid ECK ID. The derivation of a valid ECK ID is performed by a component that is specified in software configuration. If the provided stem pseudonymis in substitutionList.new and sectorID is equal to the substitutionlist.sectorID and today is later than substitutiontable.effectivedate, the previous stem pseudonym is used to derive the ECK ID from. |
OUTPUT | eckID: EckID, The derived ECK ID |
EXCEPTIONS |
|
REMARKS |
|
SAMPLE | Sample request and response |
Substitute PGN for Stem pseudonym
SERVICE DESCRIPTION | replaceStempseudonym |
---|---|
CONTEXT | This service is called when a school administration needs to indicate that a student is assigned a new PGN by the authorities. A change of PGN number is handled as follows:
See also service description Create stempseudonym. |
INPUT |
|
VALIDATIONS |
|
OPERATION | Old hPGN, new hPGN are recorded in the substitution table, and a stem pseudonym for the new hPGN is derived using function ‘Create stem pseudonym’. |
OUTPUT | stem pseudonym: The stem pseudonym for the new hpgn |
EXCEPTIONS |
|
REMARKS |
|
SAMPLE | Sample request and response |
Batch creation of stem pseudonyms
SERVICE DESCRIPTION | submitStempseudonymBatch |
---|---|
CONTEXT | This service is called by allowed LAS systems to submit a list of stem pseudonyms, for a single Sector and a single Chain. The system processes the list and makes a corresponding list of stem pseudonyms available for retrieval (see retrieveEckBatch). |
INPUT |
|
VALIDATIONS |
|
OPERATION | The service creates a stem pseudonym for each hashed PGN in the input list and adds it to the list of generated stem pseudonyms for output. If the list does not contain a hashed PGN or if the hashed PGN was previously indicated as changed, no stem pseudnym will be created and a message to indicate the nature of the failure will be added to the list of failed items for output. |
OUTPUT |
|
EXCEPTIONS |
|
REMARKS |
The use of this service is limited to prevent abuse:
These limits are configured in the software and can be modified. Schools that exceed these limits are temporarily banned from submitting batch requests. Schools may contact Kennisnet servicedesk for information and for lifting of the bans. Schools may submit multiple batch requests, as long as the limits are observed. Batches are processed in the order in which they occur. A batch result is available within one hour after submission of the request. Batch results are removed after successful retrieval. The system may remove batch results that are not retrieved within 24 hours. |
SAMPLE | Sample request and response |
Batch creation of ECK IDs
SERVICE DESCRIPTION | submitEckIdBatch |
---|---|
CONTEXT | This service is called by allowed LAS systems to submit a list of stem pseudnyms, for a single Sector and a single Chain. The system processes the list and makes a corresponding list of ECK IDs available for retrieval (see retrieveEckBatch). |
INPUT |
|
VALIDATIONS |
|
OPERATION | The service creates a ECK ID for each hashed PGN in the input list and adds it to the list of generated ECK IDs for output. If the list does not contain a hashed PGN or if the hashed PGN was previously indicated as changed, no ECK ID will be created and a message to indicate the nature of the failure will be added to the list of failed PGNs for output. If the provided hashed PGN is in substitutionList.new and sectorID is equal to the substitutionlist.sectorID and today is later than substitutiontable.effectivedate, the previous hashed PGN is used to derive the ECK ID from. |
OUTPUT |
|
EXCEPTIONS |
|
REMARKS |
The use of this service is limited to prevent abuse:
These limits are configured in the software and can be modified. Schools that exceed these limits are temporarily banned from submitting batch requests. Schools may contact Kennisnet servicedesk for information and for lifting of the bans. Schools may submit multiple batch requests, as long as the limits are observed. Batches are processed in the order in which they occur. A batch result is available within one hour after submission of the request. Batch results are removed after successful retrieval. The system may remove batch results that are not retrieved within 24 hours. |
SAMPLE | Sample request and response |
Batch results retrieval
SERVICE DESCRIPTION | retrieveBatch |
---|---|
CONTEXT | This service is called by allowed LAS systems to retrieve the status and result of a batch request. |
INPUT |
|
VALIDATIONS |
|
OPERATION | The service retrieves the batch result (either StempseudonymBatch or EckIdBatch), if available, and returns it to the caller. If an error during check or processing occurs, the error is returned. |
OUTPUT |
|
EXCEPTIONS |
|
REMARKS |
The use of this service is limited to prevent abuse: a batch retrieval may be attempted at most once per 15 minutes (software configurable; actual limit may differ). In case this limit is exceeded, the offending school is temporarily banned from using this service. Schools may contact Kennisnet servicedesk for more information and to lift the ban. A batch result is available within one hour after submission of the request. Batch results are removed after successful retrieval. Batch results that are not retrieved can be removed after 24 hours. In the output of this function, both success and failure are optional arrays. If none of the input fail, the response will contain only ‘success’ values. If none of the input succeed, the response will contain only ‘failure’. |
SAMPLE | Sample request and response |
Retrieving chains and sectors
SERVICE DESCRIPTION | retrieveChains |
---|---|
CONTEXT | This service is called by allowed LAS systems to obtain the value of the ECK chain ID, for which an ECK ID can be derived. As this list changes rarely, this service will not be called often, probably not more than once per day per LAS. |
INPUT | none |
VALIDATIONS |
|
OPERATION | The service retrieves the list of active Chain Parties |
OUTPUT |
List of 1 or more :
|
EXCEPTIONS | NotAllowedCallerException |
REMARKS |
|
SERVICE DESCRIPTION | retrieveSectors |
---|---|
CONTEXT | This service is called by allowed LAS systems to obtain the list of school types for which an ECK ID can be derived. As this list changes rarely, this service will not be called often, probably not more than once per day per LAS. |
INPUT | none |
VALIDATIONS |
|
OPERATION | Retrieve the list of active SectorIDs from the database. |
OUTPUT |
List of 1 or more :
|
EXCEPTIONS | NotAllowedCallerException |
REMARKS |
The names, descriptions and values are taken from OBK. |
Ping operation
SERVICE DESCRIPTION | pingRequest |
---|---|
CONTEXT | This service is called by allowed LAS systems to verify the service is alive. |
INPUT | none |
VALIDATIONS |
|
OPERATION | Verify the database is available for operation |
OUTPUT |
|
EXCEPTIONS | NotAllowedCallerException |
REMARKS |
|
Common types
Name | HPgn |
---|---|
Fields | xsd:string |
Constraints |
|
Remarks | Contains the result of the prescribed hash function SCrypt |
Name | EckId |
---|---|
Fields | xsd:string |
Constraints |
|
Remarks |
Exceptions
Exceptions will be presented by the Nummervoorziening Service as Soap faults. To distinguish the cause Exception of an operation at the client, the element faultactor will hold the specific Exception. In the detail node, a message node is added with additional information regarding the Exception.
Example of a Soap fault as a response from the Nummervoorziening Service (omitting the Soap Headers):
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:SERVER</faultcode>
<faultstring>RetrieveEckIdBatch has thrown an exception while building the response</faultstring>
<faultactor>InvalidBatchIdentifierException</faultactor>
<detail>
<message>Batch with specified identifier does not exist</message>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
The reference clients will contain code in Java and C# to handle these faults and distinguish root causes.