Technical deployment

First read the introduction of the service on the Service description page. The functionalities provided in the service are discussed in the Functionalities section. On the Technical description page, you can read about how Suomi.fi Messages works in practice and what interface options there are for using Suomi.fi Messages.

In addition to general familiarisation, your organisation must ensure that the technical preconditions for using Suomi.fi Messages are met. Take into account at least the following matters:

• To be able to send an electronic message, your organisation must have at least the recipient’s personal identity code or business ID, which is used to allocate the message to the correct electronic mailbox.
• When sending paper mail, your organisation must have at least the recipient's address details because Suomi.fi Messages does not have an integration with a register containing address data from the Population or Business Information System.
• Suomi.fi Messages does not have a user interface for organisations. User interfaces for the service are only offered to end users.
• Your organisation or the provider you have selected must have a system that is capable of sending messages.
• Your integration must be implemented in a secure manner. The REST interface uses secure encryption algorithms according to the TLS protocol, which must be supported by the systems you use. In the future, we will require support for TLS 1.3 encryption. We recommend enabling TLS 1.3 support in your systems already now.
• Authentication of REST requests is performed with an authentication token, which can be obtained from the REST interface with your organization’s credentials (username and password). The temporary password assigned to your organization must be changed before using the REST interface. We recommend automating this password change as part of a regular process. The authentication token has a limited validity period and must be refreshed when needed.

Possible contacts with the Digital and Population Data Services Agency are handled as part of the administrative deployment process. If necessary, participate in the meetings concerning the deployment together with the persons responsible for the administration of the deployment.

Identify the current state of your systems and what changes or integrations are required in them to initiate the use of Suomi.fi Messages.
Support the persons responsible for the administration of the deployment in the preparation of the project.

Support the administrative deployment with the completion of the access licence application form if needed.

The details of the access licence application form are discussed on the page Administrative deployment.

Support the administrative deployment also with the completion of the service information form. The expertise of a technical expert is required especially when the service information form is completed. The details of the service information form are discussed on the page Administrative deployment.

After you have returned the forms, the Digital and Population Data Services Agency will open the test and production environment for the IP addresses you have provided. The address of the test environment is api.messages-qa.suomi.fiOpens in a new window. and the instructions for using it are described in the interface documentation of the test environment (api.messages-qa.suomi.fi)Opens in a new window.. The address of the production environment is api.messages.suomi.fiOpens in a new window. and the instructions for using it are described in the interface documentation of the production environment (api.message.suomi.fi)Opens in a new window..

In addition to opening the environments, the Digital and Population Data Services Agency will send the test personal identity codes, the system ID, the service ID and a temporary password for the test environment to your organisation in encrypted email. The temporary password must be changed into a password chosen by your organisation as follows:

1. Authenticate yourselves in the token endpoint of the test environment by using the identifiers you received. The address of the endpoint is api.messages-qa.suomi.fi/v1/token. The username is the system ID you received and the password is the temporary password you received.
2. The endpoint returns an authentication token to you.
3. Change the temporary password into your desired password in the change-password endpoint with the authentication token you received in step 2. The address of the endpoint is api.messages-qa.suomi.fi/v1/change-password.
4. Store the password you have chosen securely.

To test the functioning of the password you have set, follow these steps:

1. Authenticate yourselves in the token endpoint of the QA environment. The address of the endpoint is api.messages-qa.suomi.fi/v1/token. The username is the system ID you received and the password is the temporary password you have chosen.
2. The endpoint returns an authentication token to you.
3. Use the authentication token you received to call some other endpoint in the QA environment. For example, the endpoint events returns code 200 if the identifiers work.

You can now start building the connection and test it in the test environment. Please note that the authentication token received in the manner described above is required for using all the endpoints of the interface, both in the test environment and in the production environment.

If your organisation wants to deploy the printing, enveloping and distribution service (TKJ service), familiarise yourselves with section 3 on the page Administrative deployment and with the page Deployment of the printing, enveloping and distribution service. The TKJ service provider Posti Messaging Oy will send the identifiers required for paper mailing to your organisation in a letter.

The actual technical development will now take place.

Implement the possible integrations or changes to your own service system according to the specifications drawn up by your organisation. If you join through standard software, take care of the implementation together with the producer of the software concerned. Familiarise yourself with the technical descriptions in the Interface documentation of the test environment (api.messages-qa.suomi.fi)Opens in a new window..

We recommend that you implement the changes one interface at a time and already test the implementation in connection with the development. You should also take into account possible network errors and momentary interruptions so that you keep sending the message for a sufficient number of times and for long enough.

In the testing phase, it is ensured that Suomi.fi Messages as a whole works as it should when you use it. Your organisation must test all the test cases that are essential for its connection as well as their different stages.

The instructions for the different test cases have been compiled on the page Testing instructions. Testing is carried out by using the test personal identity codes delivered to your organisation by the Digital and Population Data Services Agency,

Please note that material containing personal data or confidential information must not be sent to the test environment. The test environment is shared by all.

If you conduct performance testing with a larger volume and need a larger number of test personal identity codes or business IDs, contact viestit-kayttoonotot@dvv.fi.

If you use standard software, discuss the required extent of testing with your provider. Your organisation is responsible for ensuring appropriate testing of the connection.

Ensure that you have taken into account all important matters concerning the deployment by completing Suomi.fi Messages Deployment Checklist (see Administrative Deployment section 7. Switch to production use and finish the project).

When your access licence has been accepted, submit the completed checklist to the Digital and Population Data Services Agency and notify the exact date on which you intend to switch to production use. After having checked the checklist completed by you, the Digital and Popular Data Services Agency will send you the password for the production environment. You must change the password in the change-password endpoint. 

• The system ID and service ID that you received earlier will continue to work also in the production environment.

The address of the production environment is api.messages.suomi.fiOpens in a new window.. Its descriptions have been compiled in the Interface documentation in the production environment (api.messages.suomi.fi)Opens in a new window..

Also use real data to ensure the functionality of the entire service pipeline in the production environment. In the production environment, you can no longer use test personal identity codes to perform tests, so limit the verification of production functionality to the necessary tests.

The technical deployment of Suomi.fi Messages is now complete and you can start to use Suomi.fi Messages.

The technical work required for using Suomi.fi Messages does not end with the deployment. Your organisation must also take care of the technical maintenance of the connection during its entire life cycle. We recommend that your organization changes the REST interface password at least every six months, preferably more often. Familiarise yourselves with technical maintenance on the page Technical maintenance.