The 5.7 branch of Magnolia reached End-of-Life on December 31, 2023, as specified in our End-of-life policy. This means the 5.7 branch is no longer maintained or supported. Please upgrade to the latest Magnolia release. By upgrading, you will get the latest release of Magnolia featuring significant improvements to the author and developer experience. For a successful upgrade, please consult our Magnolia 6.2 documentation. If you need help, please contact info@magnolia-cms.com.
Magnolia provides a sample implementation showing how you can collect leads (such as email addresses) on a web form, ask for consent, and push those leads to IBM Watson.
The example on this page makes use of the Privacy module, IBM Marketing cloud connector and External Forms modules.
In the sample implementation, the magnolia-external-forms-ibm
module (sub module of External Forms) provides a page called watsonFormSample
in the Pages app.
This page contains a simple email field form linked to IBM Watson. The form is processed using an out-of-the-box processor called XXX
The visitor consent tracking mechanism is provided using the default implementation of the magnolia‐privacy‐visitor‐manager module (sub module of Privacy module). A dedicated visitor references searcher called info.magnolia.extforms.consent.WatsonReferencesSearcher
processes GDPR-sensitive data from the forms.
Note that External Forms is an EE std module and is not bundled.
Configuring the sample
To enable the sample with your implementation of IMB Watson follow the steps in the sections below.
Connect to the database
- If you do not already have one, create a database in your Watson Campaign Automation account. Make sure that
Email
is one of the fields in your database. - Once created, open the additional details and copy the Database ID.
- In Magnolia, open the configuration of the
magnolia-privacy-visitor-manager
module: Configuration app >/modules/visitor-manager/config/visitorReferencesSearchers/watson/databasesIds
- Add a property node under
databaseIds
with the Database ID you copied previously as the value.
The name of the property node is unimportant. You can add as many database ids as required. - In Magnolia, open the configuration of the
magnolia-external-forms-ibm
module: Configuration app >/modules/external-forms-ibm/config
- Add your IBM Watson credentials for the three property nodes:
clientId
clientSecret
refreshToken
XXXWhere would a customer get these credentials?
Create a webform
- Go to the sample page http://localhost:8080/magnoliaAuthor/.magnolia/admincentral#app:pages:detail;/watsonFormSample:edit.
- Edit the external form component.
- Choose
Silverpop
as external form. - Choose a database from Silverpop.
- The form should be rendered from all columns of the chosen database.
- Add a field to the database from the Silverpop admin central.
- Go to http://localhost:8080/magnoliaAuthor/travel/subscribe.html. Your new field should be displayed.
- You probably don't want to show all the field of the database such as system ones and want to change the order of field on the page:
- Create a selection field called
LAYOUT
in the database. - Add the desired field names as values for selection.
- Create a selection field called
- Activate the page to the public instance.
- Go to the activated page, fill in some fields (http://localhost:8080/magnoliaPublic/travel/subscribe.html) and submit.
- Information will be stored in Silverpop.
- User identification:
- If the web tracking javascript is enabled and your browser allows to store cookies. Your submitted information should be pre-filled if you revisit the subscription page. You can change values and resubmit.
- Alternatively, you can allow login with email/password if you want to allow users to be logged in from another computers, mobiles...
- Add a field called
PASSWORD
to the Silverpop database. Set the databaseId against which you want to run authentication. This should be the same database as the one defined for the
SilverpopTraitsDetectorFilter
.SilverpopAuthenticationFilter
enabled
true
class
info.magnolia.silverpop.login.SilverpopAuthenticationFilter
databaseId
4014446
- Go to the subscription page.
Password
andPassword confirmation
fields should be there. - Fill the password and submit the form.
- You should now be able to log in with email/password: http://localhost:8080/magnoliaPublic/travel/subscribe/login.html.
- The password login has precedence to cookie identification.
- Add a field called
Form component that fetches data from external form (e.g. IBM)
When a visitor submits data in the form, consent is requested (same as JCR forms in Magnolia)
Email requests consent confirmation (double opt-in)
See visitors app - new item, stored in visitors workspace (same consent process).
You can also view dependencies from JCR and from external sources such as IBM Watson. Clickable link takes you to Watson campaign automation dashboard (contacts list), where you can see the an entry for the visitor along with the consent recorded.
Other gdpr features also interact with external source: send all data (export from JCR but also JSON from watson), forget me, delete all my data (request sent to watson).
Simple form processing compared to GDPR-compliant form processing
In an ordinary form, the data entered in the input field is usually processed directly upon hitting the submit button on the form.
A GDPR-compliant form needs to follow a more complex procedure called double opt-in:
- A form that contains personal data has to be submitted together with the user's consent for the processing of such data. This is usually done via checkboxes which the user has to tick off before submitting the form.
- In the second step, the user has to confirm the consent given. Typically the user receives an opt-in email with links to a web page where the user can finish the double opt-in procedure, that is confirm or reject the consent.
In the example below, we assume that we have a text input form field called fullname
that must be handled in compliance with GDPR.
Data storage
In the Magnolia EE Pro Travel Demo, the contacts
workspace is registered in the configuration of the Privacy module for demonstration purposes of dealing with personal data. This means the Visitors app interacts not only with the visitors
workspace but also with the contacts
workspace, which is otherwise primarily used by the Contacts app.
The record of consent for form-based data in the visitors
workspace is created on the public Magnolia instance, never on the author instance. This is also true for referenced content, for instance in the contacts
workspace.
You must synchronize the consent records stored if you use several public instances. The instances, or in our sample implementation at least the visitors
, pendingContacts
and contacts
workspaces, must be clustered in order to share accounts between the different instances. Alternatively, implement observation-based synchronization to replicate visitor and contact data across instances.
Creating a GDPR-compliant form
In this section, you create a new GDPR-compliant form. You need the knowledge gained here in the second section where you already have a form and want to adapt it for GDPR.
The Magnolia Travel Demo bundle comes with a sample form component template called (GDPR) Store data form, which is provided by the privacy-sample
submodule and designed for the purposes of GDPR.
This component template is preconfigured to:
- Ask for a user's consent before submitting the form by displaying consent checkboxes.
- Send the user an opt-in email.
Adding and configuring the form
- Make sure that the page in which you want to create the form uses the Travel Standard page template.
- Add a (GDPR) Store data form component to the page:
Please note that if you want to create the page in the root, the root level should be at least a site's root, not the root in the Pages app due to MGNLDEMO-292 - Getting issue details... STATUS . - Click Edit in the Action bar to edit the form component.
- On the Opt-in Email tab configure the parts of the email which will be sent to the user in the second phase of the opt-in procedure:
The largest text area in the dialog is where you can define with FreeMarker variables how the main message of the confirmation email will look like. The body of this email message should contain hyperlinks to a consent confirmation/rejection page. The Travel Demo comes with a sample of such a page at/travel/contact/confirmation
. - Copy and paste this path to the Confirmation page field of the dialog and save the changes.
Adding a GDPR-sensitive field
- Add a new GDPR-sensitive input field component to the beginning of the form's field set.
- In the input field's edit dialog label the field Full Name, name it
fullname
(this becomes the value of the internal JCRcontrolName
property). - On the Advanced tab, set Full Name field's type to
text.
- Open the edit dialog of the Consent definition component.
Configure the option in which the user chooses consent duration in the Expiration options field. Use the following format
<label>:<timeUnit>__<timeQuantifier>
where<label>
represents the label shown for the option.<timeUnit>
defines the time unit. Use1
for year,2
for month or10
for hour.<timeQuantifier>
defines the actual length of consent for the time unit specified.
For example, if you want to allow the user to choose from consent durations of 24 hours, 72 hours and 1 month, you need enter the following in the field:24 hours:10__24 72 hours:10__72 1 month:2__1
- To set a default value to be selected when the form is loaded, enter the part that follows the colon in the Default expiration value field, for example
2__1
.
The actual selection box is rendered like this:
Updating Privacy module configuration
Since this step is done in the Configuration app, you need the superuser
role to access the app and change the configuration.
Both the email
field, which comes preconfigured with the (GDPR) Store data form template, and the fullname
field, added to the form's field set, must be database names registered in the system for GDPR-compliant data processing. This is done in the configuration of the Privacy module.
Open the visitor-manager
module configuration at /modules/visitor-manager/config/personalFields
.
Add the newly added fullname
field name as a property (which is in fact arbitrary) and value under the name/fieldNames
node, which is already present in the configuration:
At this point, the newly created form is GDPR-compliant. The user is asked to give consent to process the data entered:
Making an existing form GDPR-compliant
In this section, we assume that we already have a form with a text input field labeled Full Name, internally fullname
, and we want to adapt to comply with GDPR:
Changing and configuring the component template
First you need to change the form's template to use one that is designed for GDPR. In this example, we use the template called (GDPR) Store data form again.
Select the form and change its template to (GDPR) Store data form:
In the next step, switch to the Opt-in Email tab and configure the parts of the opt-in email:
After saving the changes the form contains two field sets:
Relocating the text input field
Now you have to make the Full Name field in the first field set a member of the other field set. With superuser
role you can do that in the JCR Browser app:
After this operation, the Full Name field is located next to the Email field:
Updating Privacy module configuration
Again, the fullname
field, added to the form's field set, must be a database name registered in the system for GDPR-compliant data processing. Ask your system administrator to do this for you if don't have access to the Configuration app.
Open visitor-manager
module configuration at /modules/visitor-manager/config/personalFields
.
Make sure that the relocated field's
fullname
name is a property and value under the name/fieldNames
node, which is already present in the configuration. If it isn't there yet, add it there. The relocated field is now also subject to the logic of the (GDPR) Store data form template and hence the GDPR requirements. When submitting the page, the user is asked to give consent for both text input fields in the form, Full Name and Email: