INTEGRATE
Disclaimer
This document is a prelimary version how to integrate your application with the GDPR authority,
Details discussed in this document will be subject to future modifications.
Nomenclature
The term "application" is used to cover the different use case of application, process, database as defined by the GDPR.
if 2 different processes are working on the same database
you need to obtain consent from the contact for each of these 2 applications,
and so, you need to register 2 applications as requested by the GDPR.
Register your Application
This is the very first step to start the process of conformance to GDPR by opening an account, fill-up the form.
You will obtain a FDB_SESSION along with the email (FDB_EMAIL) you entered in order to authenticate automation requests against the GDPR authority service.
Registering a pool of applications
Conforming to GDPR requires every application/process to obtain consent from a contact,
meaning: when 2 applications (or 2 processes) in your information system are storing/processing personal infos of a contact,
the contact needs to approve consent for each application/process of your information system,
in order to facilitate management of your applications, you will first register a generic application as being your company name,
let's call it the Application pool (AppPool), it is a group of applications,
the email you will use is the email address of the integrator (or system administrator).
From the GDPR authority registration portal, you will add for this company (AppPool) every application/process,
every application will be assigned a different email address, in order to identify each application/process,
your system administrator will assign 1 email address per application/process, such as app1@mycorp.com, app2@mycorp.com.
you will obtain FDB_SESSION foreach FDB_EMAIL, to be registered foreach connector to your application/database,
this is required in order to identify consent for each application/process, and maintain expiration/revokation for each application.
Protocol
All communications are based on the HTTP protocol conforming to HTTP/1.1.
For clarity of this documentation, all HTTP requests are POST application/x-www-form-urlencoded
Requests containing file to be uploaded are POST multipart/form-data.
All content encoding are utf-8 : headers, parameters of the request, content of the response.
GDPR authority servers can be accessed by primary URL (priority should be given to this URL), and secondary URL (fail-safe).
Authentication to invoke the GDPR authority servers are provided with 3 parameters:
- FDB_EMAIL the email address you provided in the registration form
- FDB_SESSION obtained once registration process has been completed.
- XMLC_ScopeID is provided with FDB_SESSION
Common parameters to submit are:
- XMLC_OutputFormat=XML to obtain a XML response document
- XMLC_StandardParams=0 to obtain a stripped document
- XMLC_Culture=en to obtain date formatted as m/d/yyyy (fr will format date as dd/mm/yyyy)
- XMLC_Language=ENGLISH
In case an error occurs, the response is formatted as follow:
<?xml version="1.0" encoding="utf-8"?><Error><Code>ERR_BLANK_CONTACT_ID</Code><Message>Parameter ContactID is blank</Message></Error>
You should not rely on the HTTP 500 error code since h2 implementation does not provide support for server code.
Declare your license template
At the GDPR authority server, you will declare the license template which will be submitted for approval to the contacts of your application. This license defines the terms and conditions engaging your application to protect the personal data of the contacts:
- storing securely the contact infos in database
- processing contact infos by your application
- transmitting/exchanging contact infos with other in-house applications
You can access a sample of a permissive license.
Declare your Access Control List
At the GDPR authority server, you will declare all the fields of your application managing personal contact infos, such as lastname, firstname, email, address, URL, social security number.
Along with the license, the individual will grant access to your application the ACL (Access Control List) you have declared.
View managed ACL.
Declare the renewal policy
Your application may request consent for a one-time only,
you will declare the period of validity for a maximum of 3 years,
meaning, your application may be authorized to store the personal infos of the contact for a maximum of 3 years.
At any time the contact may revoke authorization that was previously granted to your application,
your application will be notified if you have setup a URL for the end-point connector,
otherwise, it is the duty of the application connection to request at a certain frequency to ensure that consent approval has not been revoked (and/or expired).
In this case the contact will not be invited to renew consent once the period of validity has expired.
This is the default policy for GDPR.
However, your application may need to keep record of personal infos for long period (over 3 years),
You have the possibility to configure periodic renewal,
the contact will be invited to renew consent when approaching expiration period.
In such situation, the recommended period should be lowered to maximum 1 year.
Notifications
You will be able to customize the end-point URL of every application connector,
the end-point will be used to communicate from the GDPR authority to your in-house application connector.
This feature is optional, if left to blank, then your application connector will not receive notification
from the GDPR authority on the different status updates made by the contact (Consent approval, Renewal approval, Revokation).
In this case, your application connector will request the GDPR authority on-demand in order to ensure
that your application is still granted authorization to access the personal infos of the contact.
Multi-tenants system
If your information system is a multi-tenant system with isolated and partitioned database scopes for every customer,
you will register every tenant using 1 unique email address per tenant (tenant1@@mycorp.com or gdpr@tenant1.com),
and then foreach tenant, you will register every application with 1 email address per application/process
ie: app1.tenant1@mycorp.com or app1.gdpr@tenant1.com
The GDPR authority will provide a FDB_EMAIL and FDB_SESSION foreach registration
Provisioning + Invite
Your application connector will invoke DirRegister for each contact in your database.
The GDPR authority server will store the contact infosand will trigger an email to invite the contact to approve consent to authorize your application to access his personal infos.
The contact will read the license provided for your application (permissive license you have chosen, or a custom restrictive license),
he will review the list of fields your application is requesting to have acccess to, with the actual values as stored in your application database.
Protected and secured infos will not be shown, and may have not been transmitted during the registration of the contact infos.
The contact will grant authorization for your application for a specified period with an explicit expiration date.
He will be noticed that your application is requesting consent for a one-time only or will be invited to renew consent when approaching expiration period.
? When should you register a contact ?
as soon as you store personal informations about any contact.
? What about existing contact ?
You need to obtain consent for every contact stored in your database
? What about contact not involved by all the different processing of the multiple applications ?
Consent need to be granted by each for each application processing personal infos.
let's say that 50% of your database is processed by App#1 and the other 50% are processed by App#2,
then you will have registered the first 50% of the contact for App#1 and the other 50% for App#2.
Action to invoke: DirRegister
with the common parameters (FDB_EMAIL, FDB_SESSION, XMLC_OutputFormat=XML, XMLC_StandardParams=0, XMLC_Culture=en, XML_Language=ENGLISH)
| Parameter | Description |
|---|---|
| CPSN_EMAIL | Email address to identify the individual, it is also its primary email address in order to communicate with this contact. |
| FDB_ID | Optional: Register the contact for this application if you used a generic FDB_EMAIL, FDB_SESSION for credentials. |
| CPSNKND_ID | Gender |
| CPSN_FIRST_NAME | First name |
| CPSN_LAST_NAME | Last name |
| CPSN_MIDDLE_NAME | Middle name |
| CPSN_NICKNAME | Nick name |
| CPSN_BIRTHDATE | Birth date |
| CPSN_PHONE | Phone number |
| CPSN_CELL | Mobile/Cell phone number |
| CPSN_INFO | Informations, comments Max 2KB |
| CLOC_NAME | Name of the organization or name of the address |
| CLOCKND_ID | Address type |
| CLOC_ADDRESS1 | First line of address |
| CLOC_ADDRESS2 | Second line of address |
| CLOC_ZIP | Zip code |
| CLOC_STATE | State when applicable |
| CLOC_CITY | City |
| CLOCCRY_ID | Country ID as obtained from reference table CLOCCRY |
| CLOC_COUNTRY | Name of the country to be lookup in reference table CLOCCRY to obtain CLOCCRY_ID |
| CLOC_PHONE | Phone number of the organization |
| CLOC_FAX | Fax number of the organization |
| CLOC_WEB | Web site URL |
| CLOC_DOMAIN | Domain of the mailserver of the organization |
| CLOC_INFO | Informations, comments |
| SkipInvite | Optional. Set to "1" if you want to skip email invitation to obtain consent from the contact. |
The GDPR authority will respond with an XML document:
<?xml version="1.0" encoding="utf-8"?> <document> <Code>OK</Code> <Status>Pending</Status> </document>
You can experiment with your credentials using DirRegister.htm form.
Authorization notification
If you have setup a URL end-point for your application connector in the GDPR Authority portal,
the GDPR authority will invoke this custom URL to notify your application connector
whenever a contact approves consent after initial invitation to authorize access to his personal infos,
or when he has been invited to renew access.
The contact may at any time revoke the authorization granted to your application, even before the expiration date,
the GDPR authority will invoke the end-point of your application connector as registered in the GDPR authority portal.
Action invoked on the application connector end-point URL: DirNotify
with the common parameters (FDB_EMAIL, FDB_SESSION) to identify that the GDPR authority is authorized to invoke your application connector.
| Parameter | Description |
|---|---|
| Email address to identify the individual, you will use this email address to lookup the contact into your database |
|
| Authorized | 1=True in case the contact has approved consent 0=False in case the contact refused consent for your application to process, store, transfer his personal informations |
| Expiration | Planned expiration date of the consent format: yyyymmdd example: 20181231 |
| Expired | 1=True in case the consent has expired Optional parameter in the request |
The application connector should reply with an XML document :
<?xml version="1.0" encoding="utf-8"?> <document> <Code>OK</Code> </document>
Probe authorization
Once completed the initial provisioning of all contacts into the GDPR authority,
your application will request on-demand if the contact approved consent for your application to process his personal contact infos as defined in the license.
Action to invoke: DirAuthorized
with the common parameters (FDB_EMAIL, FDB_SESSION, XMLC_OutputFormat=XML, XMLC_StandardParams=0, XMLC_Culture=en, XMLC_Language=ENGLISH)
| Parameter | Description |
|---|---|
| CPSN_EMAIL | Email address to identify the individual, you will use this email address to lookup the contact into your database |
the response is an XML document
<?xml version="1.0" encoding="utf-8"?> <document> <Code>OK</Code> <Authorized>1</Authorized> <Expiration>12/31/2018</Expiration> <ConsentDate>1/1/2017</ConsentDate> </document>
Output fields in the XML response are described in the following table:
| Field | Description |
|---|---|
| Authorized | 1=True in case the contact has approved consent 0=False in case the contact refused consent for your application to process, store, transfer his personal informations |
| Expiration | Planned expiration date of the consent Date is formatted depending on XMLC_Culture=en (or XMLC_Culture=fr) example: 12/31/2018 (31/12/2018) |
| ConsentDate | Date of the consent granted by the contact, or Date of the consent registered by the connector. Date is formatted depending on XMLC_Culture=en (or XMLC_Culture=fr) example: 12/31/2017 (31/12/2017) In case Revoked=1 this date needs to be interpreted as revocation date. |
| Expired | 1=True in case the consent has expired Optional field in the response |
| Pending | 1=True in case an invitation has been sent to the contact, but the contact has not yet processed this invitation either to approve or deny consent Optional field in the response |
| Invite |
In case of pending consent or renewing consent, it is the date of the invitation sent to the contact. |
| Revoked |
1=True in case the consent has been revoked |
In order to minimize the rate of requests against the GDPR authority to obtain confirmation of the consent of the contact for this application, the integrator may choose to store the Expiration date of the consent for this contact based on the network constraints:
- If the application connector has an end-point configured with an URL to be invoked from the GDPR for notifications,
the integrator can decide to store the Expiration date of the consent for this contact received through DirNotify (for each application),
- If the application connector cannot be invoked by the GDPR authority to be notified for consent approval, expiration or revokation,
then the application connector will probe authorization in background at regular frequency (every 30 days or 90 days), and store the expiration date for this contact per application.
You can experiment with your credentials using DirAuthorized.htm form.
Expiration
While probing authorization against GDPR authority for a specified contact, the application connector may receive a response with a status "Expired",
<?xml version="1.0" encoding="utf-8"?> <document> <Code>OK</Code> <Authorized>0</Authorized> <Expired>1</Expired> <Expiration>20180525</Expiration> </document>
The application connector can request the GDPR authority to renew the consent approval by this contact for this application.
The GDPR authority is in charge to invite the contact to renew its consent approval for this application.
Action to invoke: DirRenew
with the common parameters (FDB_EMAIL, FDB_SESSION, XMLC_OutputFormat=XML, XMLC_StandardParams=0, XMLC_Culture=en, XML_Language=ENGLISH)
| Parameter | Description |
|---|---|
| CPSN_EMAIL | Email address to identify the individual. |
the response is an XML document
<?xml version="1.0" encoding="utf-8"?> <document> <Code>OK</Code> <Status>Pending</Status> </document>
In the background, the GDPR authority will invite the contact to renew its consent approval for your application.
If you have setup a URL end-point for your application connector in the GDPR Authority portal,
the GDPR authority will invoke this custom URL to notify your application connector about approval of consent by the contact (or denial of consent),
please refer to section authorization notification.
You can experiment with your credentials using DirRenew.htm form.
Once consent has been approved/denied by the contact, your application connector can probe authorization against GDPR authority to obtain the status of consent.
Automatic invite to renew authorization when approaching expiration date
If you have setup automatic renewal policy for your application during the registration process,
when approaching the expiration date of the consent (30 days), the GDPR authority will initiate in the background a renewal invitation to the contact,
once the contact has approved to renew consent for the period you have setup, the new expiration will be extended.
If you have setup a URL end-point for your application connector in the GDPR Authority portal,
the GDPR authority will invoke this custom URL to notify your application connector about renewal of consent approval by the contact (or denial to renew consent).
please refer to section authorization notification.
On subsequent request to probe authorization, your application connector will obtain transparently the actual renewed consent and expiration extended for the new period as an XML document:
<?xml version="1.0" encoding="utf-8"?> <document> <Code>OK</Code> <Authorized>1</Authorized> <Expiration>20191231</Expiration> </document>
Pseudonymization
A secondary application may need to keep track of a Contact reference transfered from a primary applicaton,
the primary application will transfer a PseudonymID to the secondary application in order to conform too GDPR,
it is an obfuscated information linking to the ContactID (and contact infos) of the primary application, not revealing any details about the contact,
the primary application has obtained consent from the contact to store and process his personal infos,
but the secondary application has not obtained consent from the contact,
therefore, as long as this secondary application does not store personal infos of the contact, this reference of PseudonymID is acceptable.
At some time during the process performed by this secondary application, it may be necessary to process personal infos of the contact,
in this case, the secondary application will invoke the GDPR authority to request to resolve the contact details from this PseudonymID.
The secondary application connector will invoke action: DirResolve
with the common parameters specific to the secondary application (FDB_EMAIL, FDB_SESSION, XMLC_OutputFormat=XML, XMLC_StandardParams=0, XMLC_Culture=en, XML_Language=ENGLISH)
| Parameter | Description |
|---|---|
| PseudoID | the ID provided by the GDPR authority during the provisioning performed by the primary application |
when the secondary application has not yet been approved by the contact, the response is an XML document:
<?xml version="1.0" encoding="utf-8"?> <document> <Code>OK</Code> <Status>Pending</Status> </document>In the background, the GDPR authority will invite the contact to approve consent for your application to access his personal informations.
If you have setup a URL end-point for your application connector in the GDPR Authority portal,
the GDPR authority will invoke this custom URL to notify your application connector about approval of consent by the contact (or denial of consent),
please refer to section authorization notification.
Once consent has been approved by the contact, the contact will be registered for the secondary application seamlessly, similar to initial provisioning. Therefore the secondary application does not need to invoke DirRegister, the GDPR authority has subscribed your secondary application to this contact automatically.
The secondary application connector can retry to resolve the PseudoID, and will receive a response as XML document:
<?xml version="1.0" encoding="utf-8"?> <document> <Code>OK</Code> <CPSN_ID>1002</CPSN_ID> <CPSNKND_ID>-3005001</CPSNKND_ID> <CPSN_FIRST_NAME>John</CPSN_FIRST_NAME> <CPSN_LAST_NAME>Doe</CPSN_LAST_NAME> <CPSN_MIDDLE_NAME></CPSN_MIDDLE_NAME> <CPSN_NICKNAME>Jojo</CPSN_NICKNAME> <CPSN_BIRTHDATE>31/12/1980</CPSN_BIRTHDATE> <CPSN_EMAIL>john.doe@acme.com</CPSN_EMAIL> <CPSN_PHONE>+33123456789</CPSN_PHONE> <CPSN_CELL>+33612345678</CPSN_CELL> <CPSN_INFO>CEO</CPSN_INFO> <CLOC_ID>1001</CLOC_ID> <CLOC_NAME>ACME CORP</CLOC_NAME> <CLOCKND_ID>-3001</CLOCKND_ID> <CLOC_ADDRESS1>1 square round</CLOC_ADDRESS1> <CLOC_ADDRESS2>2nd floor</CLOC_ADDRESS2> <CLOC_ZIP>75000</CLOC_ZIP> <CLOC_STATE></CLOC_STATE> <CLOC_CITY>PARIS</CLOC_CITY> <CLOCCRY_ID>-3003001</CLOCCRY_ID> <CLOC_COUNTRY>France</CLOC_COUNTRY> <CLOC_PHONE>33123456789</CLOC_PHONE> <CLOC_FAX>+33123456789</CLOC_FAX> <CLOC_WEB>www.acme.com</CLOC_WEB> <CLOC_DOMAIN>acme.com</CLOC_DOMAIN> <CLOC_INFO>Best products of the world</CLOC_INFO> </document>
The secondary application connector will also be able to probe authorization against GDPR authority to obtain the status of consent and receive the response as an XML document:
<?xml version="1.0" encoding="utf-8"?> <document> <Code>OK</Code> <Authorized>1</Authorized> <Expiration>20181231</Expiration> </document>
Unregister a contact
Maintaining contact informations that are no longer in use for an application is costly and infrige GDPR.
In order to manage the life cycle of personal informations stored by an application, the GDPR authority offers the possibility to unregister a contact for one specific application.
Action invoked on the application connector end-point URL: DirUnregister
with the common parameters (FDB_EMAIL, FDB_SESSION, XMLC_OutputFormat=XML, XMLC_StandardParams=0, XMLC_Culture=en, XML_Language=ENGLISH).
| Parameter | Description |
|---|---|
| CPSN_EMAIL | Email address to identify the individual to be unregistered |
The response is an XML document :
<?xml version="1.0" encoding="utf-8"?> <document> <Code>OK</Code> </document>
The contact is now unregistered from the GDPR authority for this application (FDB_EMAIL+FDB_SESSION).
The GDPR authority will notify the contact that his personal informations are no longer stored for the application #1.
You can experiment with your credentials using DirUnregister.htm form.
Verification
This workflow is initiated by the contact during the initial period of adoption and conformance to GDPR by the enterprises.
The initial provisioning of the complete database of the application may take up to few months, meanwhile the GDPR offers the ability for a contact to request from an enterprise to provide what personal information is stored in their system.
A contact may initiate a request for validation.
This is the role of the GDPR authority to authenticate the request initiated from a contact,
the GDPR authority will forward this request to the application connector.
Action invoked on the application connector end-point URL: DirVerify
with the common parameters (FDB_EMAIL, FDB_SESSION) to identify that the GDPR authority is authorized to invoke your application connector.
| Parameter | Description |
|---|---|
| Email address to identify the individual, you will use this email address to lookup the contact into your database |
The application connector should reply with an XML document :
<?xml version="1.0" encoding="utf-8"?> <document> <Code>OK</Code> <Authorized>1</Authorized> <Expiration>20181231</Expiration> <CPSN_ID>1002</CPSN_ID> <CPSNKND_ID>-3005001</CPSNKND_ID> <CPSN_FIRST_NAME>John</CPSN_FIRST_NAME> <CPSN_LAST_NAME>Doe</CPSN_LAST_NAME> <CPSN_MIDDLE_NAME></CPSN_MIDDLE_NAME> <CPSN_NICKNAME>Jojo</CPSN_NICKNAME> <CPSN_BIRTHDATE>31/12/1980</CPSN_BIRTHDATE> <CPSN_EMAIL>john.doe@acme.com</CPSN_EMAIL> <CPSN_PHONE>+33123456789</CPSN_PHONE> <CPSN_CELL>+33612345678</CPSN_CELL> <CPSN_INFO>CEO</CPSN_INFO> <CLOC_ID>1001</CLOC_ID> <CLOC_NAME>ACME CORP</CLOC_NAME> <CLOCKND_ID>-3001</CLOCKND_ID> <CLOC_ADDRESS1>1 square round</CLOC_ADDRESS1> <CLOC_ADDRESS2>2nd floor</CLOC_ADDRESS2> <CLOC_ZIP>75000</CLOC_ZIP> <CLOC_STATE></CLOC_STATE> <CLOC_CITY>PARIS</CLOC_CITY> <CLOCCRY_ID>-3003001</CLOCCRY_ID> <CLOC_COUNTRY>France</CLOC_COUNTRY> <CLOC_PHONE>33123456789</CLOC_PHONE> <CLOC_FAX>+33123456789</CLOC_FAX> <CLOC_WEB>www.acme.com</CLOC_WEB> <CLOC_DOMAIN>acme.com</CLOC_DOMAIN> <CLOC_INFO>Best products of the world</CLOC_INFO> </document>
This response means that the contact has provided some previous consent for App#1 valid up to 31/12/2018 to use his personal infos. This consent may have been obtained through a web form or a previous contract/order. Anyhow the consent detained by the enterprise is not immutable and will expire in conformance to GDPR.
The following table summarizes the different fields and possible values in the response.
| Fields | Description |
|---|---|
| Authorized | 1=True in case the contact has approved consent 0=False in case the contact refused consent for the application to process, store, transfer his personal informations |
| Expiration | Planned expiration date of the consent format: yyyymmdd example: 20181231 |
| Expired | 1=True in case the consent has expired Optional parameter in the request |
The document contains the personal informations detained by the application (fields are described in the document ACL)
The GDPR authority will notify by email the contact who initiated the veriification request.
The GDPR authority will provide opportunity for the contact to review all these informations and finalize consent approval for this enterprise.
Questions
You may still have questions about the way your application will communicate with the GDPR authority,
feel free to ask your questions through the contact form.