CONTENTS. TESTING INSTRUCTIONS Appendix 1 to the Stakeholder testing plan. Project to establish the National Incomes Register 1(14)

Transcription

1 1(14) CONTENTS 1 Start of testing Testing agreement Testing addresses Instructions for generating a test certificate in the certificate service Requirements for generating a test certificate Certificate use in the 's interfaces Signature of records Authentication in Web Service channels Authentication in the SFTP channel Test records Customer records The 's test customer records Adding the stakeholder's own test customers to the 's stakeholder testing environment Generating the delivered records Earnings payment records Codes Stakeholder testing Recommended test cases for data providers Reporting observations Instructions for completing the fields on the observation form: Sample recorded observation Referring an observation for correction Errors that prevent testing Change request Delivery report Final release in the stakeholder testing environment Finishing testing Additional Information... 14

2 2(14) Version history Version Date Description /12/2017 Document published /2/2018 Specified the description of the term CSR. Chapter 1, figure 1: added information which will be sent after the testing agreement has been processed. Chapter 4: specified the instructions and description of retrieving a certificate. Chapter 5.1: specified information on the signature. Chapter 9.1: specified the instructions on the observation form: changed some field names added fields Channel and Services. KEY TERMS AND THEIR DEFINITIONS Abbreviation or term Customer data CSR (Certificate Signing Request) SMS message Test certificate Testing organisation Technical contact person Testing contact person Description Anonymised records consisting of test customer records and used in the 's stakeholder testing. A certificate signing request formed from a generated key pair (PKCS#10). A text message. A short message that only contains alphanumeric characters and special characters. A certificate granted by the 's certificate service for stakeholder testing. A company or organisation participating in the stakeholder testing of the. A person indicated by a testing organisation, to whom transfer credentials for retrieving a certificate are granted. The testing organisation's primary contact person in matters involving the testing of the. There can be several testers, but only one testing contact person. Notifications and questionnaires concerning the testing are sent to the testing contact person, as are the test records and addresses required for the tests.

3 3(14) Data users Actors who have a statutory right to obtain income or other data from the for the purpose of performing their duties. During the first stage, beginning from 1 January 2019, the data users will be the Tax Administration, the Social Insurance Institution of Finland Kela, the Unemployment Insurance Fund (TVR), the earnings-related pension providers and the Finnish Centre for Pensions ETK. In the second stage, beginning from 1 January 2020, the data users will also include Statistics Finland, the Education Fund, non-life insurance providers, unemployment funds, the administrative sector of the Ministry of Economic Affairs and Employment, the municipalities, and the labour protection authorities. Data providers All companies and other actors under the obligation to report wage, pension or benefit data to an data user in Finland. Certificate service Testing agreement XML signature The certificate provider used by the. An agreement concluded by a stakeholder with the Tax Administration on the testing of 's interfaces in the stakeholder testing environment. Data users will sign separate testing agreements. The data providers testing agreement is concluded when they accept the stakeholder testing environment's terms of use. An XML-format signature generated with a valid certificate. In the Incomes Register's stakeholder testing, the testing organisation signs the records sent by it with a test certificate granted by the 's certificate service. The signature ensures that the records are intact and unchanged.

4 4(14) 1 Start of testing Figure 1 presents the measures for initiating testing. Figure 1: Start of testing 2 Testing agreement The contents of testing agreements differ, depending on whether the testing agreement is signed as a data provider or data user. If the stakeholder functions in both roles, it will require separate agreements for provider testing and user testing. Testing and agreements will be discussed individually with data users. Data providers can sign up as testers for the by delivering the signed and scanned agreement to the address YHT_Tulorekisteri_testaus@vero.fi. The agreement template is available on the incomesregister.fi site (agreements are available only in Finnish and Swedish). The project will send an acknowledgement when it has received the agreement. After the Incomes Register Project has processed the agreement, the information required for testing will be sent to the testing contact person by and the information required to generate a certificate will be sent to the technical contact person by and SMS. The agreement must be concluded a minimum of two weeks before testing begins. The agreement can be signed in February 2018.

5 5(14) 3 Testing addresses The Project will deliver the certificate service's testing address and the testing addresses of the interfaces to the testing contact person, in accordance with the services and technical interfaces the stakeholder has agreed to test in the agreement. 4 Instructions for generating a test certificate in the certificate service The tester can begin requesting and retrieving test certificates after it has delivered the testing agreement to the Project, the testing agreement has been processed and the technical contact person has received the credentials required for retrieving the test certificate. The testing contact person will receive a feedback message about the valid testing agreement from the Project. An artificial business ID (Customer- ID) and an organisation name linked to it (CustomerName) will be delivered to the testing contact person for generating the certificate. If the stakeholder has signed a testing agreement in the roles of both provider and user, it will also need two certificates. The test certificate is temporary and is valid for two years from the date of issue. If problems occur when retrieving or using the certificate, the testing organisation should read the instructions on the certificate service interface implementation as well as the frequently asked questions and answers to them. When needed, the organisation can fill in and send an observation form. The Project will take measures to resolve the issue on the following business day at the latest. 4.1 Requirements for generating a test certificate 1. The testing agreement has been completed and delivered to the Incomes Register Project, and the terms of use have been accepted. 2. The following details of the technical contact person have been indicated in the testing agreement: First name Last name Mobile number (with the country code, e.g ) 3. The technical contact person will receive a secure containing two individual credentials: the transfer ID (TransferId) and one-time password (TransferPassword). This can only be opened with the PIN code sent in an SMS message. These messages will be delivered within two weeks of the stakeholder delivering the agreement to the Project. The technical contact person will attach the transfer ID and one-time password to the generated certificate request and send it to the certificate service for the generation of the retrieval ID (RetrivalId). 4. The certificate service receives the certificate request (SignNewCertificateRequest), generates a retrieval ID and delivers it to the recipient.

6 6(14) 5. In the acknowledgement of receipt, the technical contact person receives the retrieval ID that the contact person can use to send the certificate request (GetCertificateRequest). 6. The certificate service receives the certificate request and returns a test certificate (GetCertificateResponse) to the technical contact person. 7. The technical contact person receives the test certificate and saves it in the software. 8. Interface testing can now begin. Figure 2: Technical course of the certificate process for generating certificates. Test certificates are generated according to the WS descriptions. The Incomes Register certificate service documentation site has more detailed instructions on technical implementation. 5 Certificate use in the 's interfaces The various ways of using the certificate are documented in the document Technical interface Application instructions (PDF). The test certificate is used for the signature of records and authentication of parties.

7 7(14) 5.1 Signature of records The testing organisation signs the record with an XML signature in the test certificate granted by the certificate service. Before the record is sent to the Incomes Register, the signature is generated in accordance with the interface description and attached to the record according to the interface description schema. Client authentication and signature must be done with the same certificate. In addition, the same artificial business ID which was used in the signing certificate, must appear in the Creator role in the message which is sent to the. 5.2 Authentication in Web Service channels In Web Service channels, the sending organisation is authenticated with a certificate. The organisation uses the certificate as an SSL/TLS client certificate with which the authenticates the sending organisation. 5.3 Authentication in the SFTP channel 6 Test records In the SFTP channel, the organisation is authenticated with a public-private key pair linked to the certificate. In other words, the certificate is not directly used for authentication, which is done with the keys linked to the certificate. The organisation uses its own private key, while the holds the organisation's corresponding public key. 6.1 Customer records The 's test customer records The 's test customer records consist of personal identity codes with linked first and last names, along with business IDs and the legal entity's (e.g. LLC, PLC) name data. The test customer records have been anonymised so that they cannot be restored to their original form with a certain value or, for example, an encryption key. The test customer records are thus compliant with the GDPR's (= the EU-wide General Data Protection Regulation 2016/679 entering into force on 25 May 2018) requirements, and natural persons cannot be identified from the records by adding data. The personal identity codes and business IDs of the test customers have been anonymised in a manner that keeps them formally correct and able to pass checks. For instructions on the anonymisation of test records, see Appendix 7. After the testing agreement has been processed, the anonymised business IDs and personal identity codes and their name data will be sent by (PDF) to the testing contact person indicated by the stakeholder. Earnings payment reports will be accepted even if the names are changed, but use of the names provided by the Project is nevertheless recommended. Each testing organisation will be provided with 40 business IDs and 200 personal identity codes. The IDs and codes will be picked at random. Stakeholders are free to choose the number of income earners per payer with a business ID. Personal identity codes can also be linked to business IDs as desired. The Project will provide more test customers if necessary. Testing organisations that would like more test customers should send their requests to YHT_Tulorekisteri_testaus@vero.fi. The requested test customers will be sent to the contact person by the third business day from receipt of the request.

8 8(14) Adding the stakeholder's own test customers to the 's stakeholder testing environment If necessary, the Project can import the stakeholder s own anonymised test customers into the 's stakeholder testing environment, in addition to the test customers provided by the Project at the start of the project. Stakeholders may submit a reasonable number of their own test customers, such as 10 business IDs and 40 personal identity codes. Customer data must be delivered to the Project in CSV format. The files should be sent to YHT_Tulorekisteri_testaus@vero.fi. The test customers sent in the file will be usable by the third business day from receipt. If a test customer sent by a stakeholder already exists in the 's stakeholder testing environment (e.g. the same business ID or personal identity code with a different name), data on the existing test customer will not be imported into the 's test environment. The ID or code will continue to be available based on the data with which it was first added. The stakeholder will be notified of which test customers were added to the 's stakeholder testing environment and which, if any, were already found in the stakeholder testing environment. To facilitate the management of the test customer records, please include the name of the sending organisation in the name of the file being sent. Compose the file name as follows: organisation's name type of identifiers test customers. For example: Kela_personalIDcodes_testcustomers1.csv / Arek_busID_testcustomers1.csv Assign a number to the file being sent so that you can send additional test customer files of the same type in the future Generating the delivered records The personal identity codes and business IDs for generating the stakeholder's own test record are delivered as separate files. The files are in CSV format with UTF-8 characters. The data of each test customer is provided on its own row (line break = CRLF) in the following order: ASTUNNUS = test customer's business ID or personal identity code NIMI = name of the corporation/company (only used for companies with a business ID) ETUNIMI = test customer's first name SUKUNIMI = test customer's last name TONIMI = business name of the entrepreneur/self-employed person LUONN_LY = natural person's business ID (e.g. for self-employed persons) Fields that do not contain data are marked as empty separator characters. For the structure to remain intact, each row must include all data fields. If the field will not contain data, this must be indicated by two quotation marks separated by a comma. Individual customers Only the following data is reported for test customers with a personal identity code: ASTUNNUS ETUNIMI

9 9(14) SUKUNIMI TONIMI (if known, can also be left empty) LUONN_LY Sample personal identity codes: ASTUNNUS,"NIMI","ETUNIMI","SUKUNIMI","TONIMI","LUONN_LY" B,"","Aarno Ilmari","Pokkanen","","" E,"","Helmi","Tahti","","" A818U,"","Maria","Päki","","" Corporate customers The following data is reported for test customers with a business ID: ASTUNNUS NIMI Sample business IDs: ASTUNNUS,"NIMI","ETUNIMI","SUKUNIMI","TONIMI","LUONN_LY" ,"Çlpo Testifirma OY","","","","" ,"Huuli Testifirma OY","","","","" ,"Ennajajoottii Testifirma KY","","","","" ,"Vacaret Testifirma Muu kiint.oy","","","","" 6.2 Earnings payment records 6.3 Codes Data users will require various earnings payment records for testing. As a rule, the 's stakeholder testing will use earnings payment reports generated by the data providers. In addition to these, the Project can generate earnings payment records in the 's stakeholder testing environment if required by users. Earnings payment reports must be generated with the Excel sheet offered by the Incomes Register Project. A sample sheet will be delivered as a file attachment to data users who need it. In the initial phase, the Excel template will contain a simple example of an earnings payment report. The Excel will be expanded as testing proceeds and needs are clarified. Updated versions of the Excel sheet will be delivered to all parties using it. The Excel sheet can be requested from the address YHT_Tulorekisteri_testaus@vero.fi, and the completed sheet must be returned to the same address. Earnings payment records delivered on the Excel sheet will be available by the third business day from receipt, provided that the data is free of errors. Feedback on erroneous data will be sent by the third business day from receipt. Feedback on the successful generation of earnings payment records and possible errors will be delivered by to the party that sent the sheet. The codes used in stakeholder testing are provided in the Codes document (PDF). A listing of the codes for the various income types can be found in the Codes Income types document (PDF). Production versions of external codes will be used in the stakeholder testing phase. Codes used in various situations are specified in the schema content descriptions. Schema content descriptions can be found in the documentation for the incomesregister.fi website.

10 10(14) 7 Stakeholder testing When measures required for initiating stakeholder testing have been taken, the stakeholder is free to begin testing. Figure 3 depicts the progress of testing as stakeholder testing proceeds. Figure 3: Stakeholder testing process 8 Recommended test cases for data providers In the stakeholder testing environment, the interface services used by the software that generates earnings payment data for the should be tested in each channel through which records will be sent. The available channels for sending data through the interface are real-time and deferred Web Service and SFTP. It is the testing party's responsibility to design and implement the testing of its own software. The required test scenarios include the following: - Earnings payment data o New earnings payment record for one income earner o New earnings payment record for several income earners o New earnings payment record with different payer IDs o Replacement of earnings payment record o Cancellation of earnings payment record o Reporting methods 1 and 2 o Cases related to social insurance o Exceptions to insurance o International situations - Employer's separate report o New employer's separate report o Replacing an employer's separate report o Cancellation of an employer's separate report - Sending erroneous records and reports and processing the processing feedback and response message containing the error message o Schema errors o Errors in business rule checks - Sending messages

11 11(14) 9 Reporting observations Testing observations are submitted to the Project on the observation form. The form is one-way, and further communication regarding the observation takes place by . Detailed information on using the form will be shared with the testing party after the agreement has been signed. 9.1 Instructions for completing the fields on the observation form: Disturbance, which prevents use of the system (yes): If you observe a severe problem in the stakeholder testing of the, mark yes. The testing oganisation of the will assess the severity of the problem. In severe disturbances the stakeholder testing is discontinued. The will notify the testing stakeholder organisations of the scope and repair schedule of the problem. Title: Use a descriptive title for the observation. Error category: A four-step scale describing the criticality of the error. Instructions for using the error categories can be found in the Error categorisation chapter of the Stakeholder testing plan document (PDF). Name of the person who made the observation: Name of the tester. address of the person who made the observation: The address of the recorder of the observation. Time when the observation was made: The date and time when the situation was observed. Channel: Select the channel which was used in the testing (Real-time Web Service / Deferred Web Service / SFTP). Services: Select the service which was tested. Attachment: The XML of the sent message. If a message or error message was returned in the situation, also attach that here. Description of the observation: Which service was being tested? (E.g. earnings payment report, new/replacement/cancellation) Which channel was being tested? (real-time/deferred Web Service, SFTP) What did the tester do? What happened during the test? What was the expected result, what should have happened? 9.2 Sample recorded observation Title: A new earnings payment report with the income type 404 Tax at source will not accept a negative value Error category: 3 Medium Name of the person who made the observation: Dude Tester Name of the organisation: Software firm X address of the person who made the observation: dude.tester@softwarefirmx.com Time when the observation was made: 9 November 2017, 16:20 Channel: Deferred Web Service Services: Attachment: 404_palkkatietoilmoitus.xml, 404_response.xml Description of the observation: We tested sending a new earnings payment report through the deferred Web Service interface. We sent a new earnings payment report with the sum for income type 404 = The StatusResponse message returned the response "Negative value not permitted in amount field".

12 12(14) The earnings payment report should have been received by the. A negative sum is allowed for income type 404. The maker of the observation will be notified of receipt of the observation in 1 2 business days. If the observation was an error, the will also include the error identifier (ID). After this, the maker of the observation will send any further comments related to the observation by , including the error ID in the subject field. 9.3 Referring an observation for correction Observations will be processed by the Project. Errors are processed in accordance with the project's error management process. All observations categorised as errors and sent to the Project will be discussed by the error panel, which determines the order of correction for errors. If the 's error panel changes the error category or requires additional information on the observation, the Project will contact the maker of the observation. Errors with an impact on stakeholder testing will be published on the incomesregister.fi site. 9.4 Errors that prevent testing If an observation is an error that prevents proceeding with stakeholder testing, the maker of the observation must select 1 Critical/Kriittinen as the error category. The Project will then prioritise the processing of that error. If the error panel maintains the error category, the critical error will be referred to the appropriate party for correction. Critical errors are corrected outside the normal error management process. The party that observed the error will receive notification that the error is being corrected and an estimated correction schedule. There will also be information on the error situation on the incomesregister.fi website. Alternatively, the Project can lower the error category from 1, in which case the error will be addressed according to the normal error management process. In such a case, the Project will notify the maker of an observation of a change in error category. Sample critical error (error category 1): Earnings payment reports cannot be sent through the real-time Web Service interface. Justifications: the error is critical, because it completely prevents the sending of earnings payment reports through one channel. It completely prevents testing by those earnings payment data providers that use the realtime Web Service interface. Sample non-critical error (error categories 2 4): Earnings payment report: An earnings payment report cannot be cancelled with the payer's report reference, but can be cancelled using the Incomes Register's report reference. Justifications: the error is not critical, because it does not prevent proceeding with testing. The cancellation can be performed with the 's report reference, and testing can continue.

13 13(14) 9.5 Change request 9.6 Delivery report If a change requirement is noticed during testing, the tester should complete a change request form and send it to the Project by . The Incomes Register Project will send the maker of the change request an stating that the change request is being processed. A change request form can be requested by from YHT.Tulorekisteri_toiminnallinen@vero.fi, and the completed form must be returned to the same address. When an error has been corrected and tested by the Project, the patch will be deployed in the stakeholder testing environment in the next release. The Project will draw up a delivery report before installing the new version. The report lists the corrections and changes included in the version. Delivery reports will be sent to the stakeholder's testing contact person on the Thursday before release. The delivery reports will also be published on the incomesregister.fi website. The version release schedule can be found in Appendix 8 to the Stakeholder testing plan: Release schedule (PDF) 9.7 Final release in the stakeholder testing environment 10 Finishing testing Error reports on the that a stakeholder wishes to be processed and corrected prior to the deployment on 1 January 2019 must be delivered to the Project no later than 1 October The final correction package will be installed in the stakeholder testing environment on 1 November After this date, only critical errors preventing the deployment of production will be corrected. The stakeholder testing environment will also remain available after this date and observations may still be delivered to the Project. Observations reported after 1 October 2018 will be processed, but the corrections will be scheduled at a time to be separately reported after deployment. When a stakeholder has finished its interface testing, it should notify the Incomes Register Project of this by sending an to YHT_Tulorekisteri_testaus@vero.fi. Testing can be considered complete once the stakeholder has verified the functionality of the interfaces between its system and the, and the stakeholder is unaware of any errors that would prevent putting the system into production. After issuing this notification, the stakeholder may continue testing in the Incomes Register's stakeholder testing environment, e.g. in connection with regression testing, new system development or lower-priority error corrections. The purpose of the 'testing complete' message is to notify the Project of the fact that, from the perspective of the testing stakeholder, the implemented interfaces are ready for production. This information will assist in assessing the project's degree of completion.

14 14(14) 11 Additional Information Stakeholder testing plan (PDF) Codes Income types (PDF) Release schedule (PDF) Codes (PDF) documentation Certificate service General description (PDF) Certificate service Interface description (PDF) Certificate service's technical interface ZIP For application developers Technical interface Application instructions (PDF)