Additional information for implementers of the IN-integration

PTV is currently undergoing an architectural reform, which will include the release of API version 12 and, after a transition period, the shutdown of the version 11. Please take this change into account when planning your new integration!

API and architecture reform

FSC user permit

The deployment of the IN-interface requires applying for a user permit.

How to deploy the IN-interface

Instructions for implementing the integration

When the Digital and Population Data Services Agency has accepted the access licence application, your organisation can begin to implement the integration by using the FSC’s Customer Test Environment. For the details of the Customer Test Environment, see the end of this page.

• IN interface methods in SwaggerOpens in a new window.
• IN-interface methods, interface version 11 Digital and Population Data Services Agency (Excel) (XLSX, 222.06 kB)Opens in a new window.

The integration must be implemented in such a way that changes made in the source system are imported to the FSC at least once a day. Information deleted from the source system must also be archived in the FSC at least once a day.

Identification in the interface

The implementation of the IN-integration is always organisation-specific. The organisation-specific user ID and the password are sent to the access management server of Suomi.fi Service Management, which returns the token required for identification. The validity of the token is limited. The validity period is indicated in the information inside the token.

Authentication to production environment

Token link: https://palveluhallinta.suomi.fi/api/auth/api-loginOpens in a new window.

Parameters for token

Headers:

• Content-Type:application/json

Body:

• username: user
• password: pwd
• apiUserOrganisation: organisation ID (optional)

Request returns the serviceToken parameter

If the API account is connected to multiple organisations, the user should define Palveluhallinta organisation ID by using the apiUserOrganisation parameter. If parameter is not given, the token return authentication for the active organization (this can be checked from Palveluhallinta UI)

Request example 1, the API organization ID is not given:

  "username":"username@domain.fi",

  "password":"validpassword"

}

Request example 2, the organization ID is given:

{

  "username":"username@domain.fi",

  "password":"validpassword",

  "apiUserOrganisation": "9cb2abc6-5458-4811-bbdd-83f75ceeed25"

}

Response

{

  "serviceToken":"eyJhlsdlksd...."

}

Please note that the Finnish Service Catalogue's production environment and Customer Test Environment differ in the authentication (token) structure of the interface. The production environment has an apiUserOrganisation field that does not exist in the Customer Test Environment.

If an API ID is associated with more than one organisation, the apiUserOrganisation field can be used to assign the authentication request to the desired organisation. The ID returned by Suomi.fi Service Management is entered in the field.

Testing technical readiness

When the integration has been implemented in the Customer Test Environment, your organisation must test the functioning of the interface connection (firewall openings, access rights, etc.) in the Customer Test Environment. The interface connection is tested with material that has not previously been brought to the Customer Test Environment, for example, via a user interface. Technical readiness testing includes

• addition and modification of new sub-organisations, new services and new service channels
• addition and modification of connections and additional connection information
• testing of the correctness of data fields (data formats, lengths, requirements, etc.).
• archiving of data that has been deleted from the source system

Your organisation must prepare a test report and submit it to the following address: ptv-tuki@dvv.fi.

Testing the content

For you to be able to test the IN-integration and take it into production, the content must also be up to date and meet the quality requirements of the FSC. We require a test report indicating the quality of the data and compliance with the data model. The FSC Main user of the FSC’s client organisation is responsible for testing the quality of the information.

Read more about testing the content

Make the possible repairs and perform production installation

Based on the test reports, the Digital and Population Data Services Agency assesses whether your organisation can be granted IN-interface production IDs. This may require several iteration rounds.
Once the test reports have been approved, the Digital and Population Data Services Agency will, as separately agreed, send the API user rights for the FSC's production environment to the client organisation or the application supplier to the address specified in the access licence application. You can then perform the production installation.