DocumentationAEM 6.4Forms Guide

Set up and configure AEM Forms reference sites set-up-and-configure-aem-forms-reference-sites

Last update: Tue Mar 05 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • User
CAUTION
AEM 6.4 has reached the end of extended support and this documentation is no longer updated. For further details, see our technical support periods. Find the supported versions here.

AEM Forms provides reference site implementation to demonstrate how AEM Forms helps Financial Services Industry and Government organizations in transforming their complex transactions into simple and engaging digital experiences anywhere, anytime, on any device.

We.Finance and We.Gov reference sites draw real life use-cases to engage with existing and potential customers, right from the point of first touch to managing correspondences and transactions in a personalized and cost-effective manner.

The reference sites allow you to explore and showcase the following key capabilities of AEM Forms.

  • Simplified authoring experience of engaging and responsive adaptive forms and interactive communications.
  • Interactive Communications to create interactive, personalized, and responsive customer communications that adapt to the device setting and layout.
  • Data integration to connect to disparate data sources to prefill and submit form data through a form data model.
  • Forms workflow to automate business processes and workflows.
  • Advanced user data managing and processing capabilities.
  • Integration with Acrobat Sign to securely sign and submit adaptive forms.
  • Integration with Adobe Target to serve targeted recommendations and perform A/B testing to maximize the ROI from a form.
  • Integration with Adobe Analytics to measure the performance of a form or a campaign and take informed decisions.
  • Enhanced form filling experience.

The reference sites provide reusable assets that you can use as templates to create your own assets.

  • Integration with Acrobat Sign to securely sign and submit adaptive forms.

  • Integration with Acrobat Sign to securely sign and submit adaptive forms.

Prerequisites and steps to set up reference sites prerequisites-and-steps-to-set-up-reference-sites

Before you set up the reference site, ensure that you have the following:

  • AEM essentials

    AEM QuickStart, AEM Forms add-on package, and reference site packages. See AEM Forms releases for add-on and reference sites packages details.

  • An SMTP service
    You can use any SMTP service.

  • Acrobat Sign developer account and Acrobat Sign API application

    To use digital signing capabilities, Acrobat Sign developer account is required. See Acrobat Sign.

  • A running instance of Microsoft Dynamics 365 to integrate with AEM Forms. To run the reference site, you import the sample data into the Microsoft Dynamics instance to prefill the interactive communication used in the reference site.

  • A running instance of AEM 6.4 with Forms add-on package. For more information, see Installing and configuring AEM Forms.

Perform the following steps in the recommended sequence to set up and configure the reference sites.

Step
Configure
Notes
Install and configure AEM Forms
Author and Publish
Install and configure AEM Forms author and publish instances.
Configure SSL
Author and Publish
Enable HTTP over SSL for secure communications with Acrobat Sign.
Configure Day CQ Link Externalizer configuration
Author and Publish
Reference Site use cases deliver emails for different transactions. This setting is required for Newsletter delivery via email. It ensures that URLs and Images point to the publish instance.
Configure Day CQ Mail Service
Author and Publish
Required for email communication.
Override default XSS configuration
Publish
Used to override $, {, and } characters that are blocked by xss security.
Configure AEM DS settings
Author
Configure AEM DS for form submission on publish instance and processing workflows on the author instance.
Deploy reference sites packages
Author
Deploy reference sites packages on AEM Forms author instance.
Import sample data into Microsoft Dynamics
Author and Publish
Import sample data for credit card application, home mortgage application, and home insurance application walkthrough
Configure OAuth cloud service for Microsoft Dynamics
Author and Publish
Configure the OAuth cloud service in AEM Forms to enable communication between AEM Forms and Microsoft Dynamics.
Configure Acrobat Sign Scheduler
Author and Publish
Change the configuration of the scheduler to check status every two minutes.
Configure Reference Site Acrobat Sign Cloud Service
Author and Publish
A configuration that comes with reference sites packages and needs reconfiguration with valid credentials.
Configure Forms Common Configuration Service for anonymous users
Publish
The configuration allows submission, sign and Document of Record generation for anonymous users.
Modify Rest Service Swagger File for Form Data Model
Author and Publish
Modify the service for your environment.

Install and configure AEM Forms install-and-configure-aem-forms

Install and deploy AEM Forms as described in Installing and configuring AEM Forms on OSGi.

NOTE
Configure replication and reverse replication agents if there are more than one publish instances or author and publish instances are on different machines.

Configure SSL ssl

SSL configuration is required to communicate with Acrobat Sign servers. For detailed steps, see Enabling HTTP Over SSL.

CAUTION
Do not configure force SSL on /etc/map folder.

In AEM, the Externalizer is an OSGI service that allows you to programmatically transform a resource path (For example, /path/to/my/page) into an external and absolute URL (for example, https://www.mycompany.com/path/to/my/page) by prefixing the path with a pre-configured DNS. See Externalizing URLs.

CAUTION
Do not externalize to HTTPS URL if you are using self-signed certificate for SSL.
Also, use localhost instead of its hostname for local server.

Perform the following steps on both author and publish instances:

  1. Go to OSGi Configuration at https://<hostname>:<port>/system/console/configMgr.

  2. Find and tap Day CQ Link Externalizer configuration.

    The Day CQ Link Externalizer dialog opens for editing the configuration.

  3. In the Day CQ Link Externalizer dialog, in the Domains field:

    • On the author instance, specify a publish URL that can be accessed from an external system. For example, a hostname or a publishing web server.
    • On the publish instance, specify both the author and publish URLs.

  4. On both author and publish instances, ensure that the local server URL is specified in the Domains field.

  5. Tap Save. Wait for a while for all services to restart.

Configure Day CQ Mail Service cqmail

Reference site implementation requires emails to be sent to sample users when they fill and submit forms. Configuring Day CQ Mail Service lets you provide SMTP service details to send automated emails to customers. See Configuring Email Notifications.

Perform the following steps to configure mail service on the publish instance:

  1. Go to OSGi Configuration at https://<hostname>:<port>/system/console/configMgr.
  2. Find and tap Day CQ Mail Service to open it for configuration.
  3. Provide SMTP server hostname and port values.
  4. Tap Save.
NOTE
You can use your corporate SMTP service or public services like Gmail. For configuring SMTP service, see SMTP service documentation.

Override default XSS configuration xss

The email templates for We.Finance reference site contain personalized links in emails. These links have placeholder as ${placeholder}. These placeholders are replaced by actual values before sending emails. The default XSS protection configuration for AEM does not allow curly braces ({ }) in the URL in HTML content. However, you can override the default configuration by performing the following steps on publish instance:

  1. Copy /libs/cq/xssprotection/config.xml to /apps/cq/xssprotection/config.xml.

  2. Open /apps/cq/xssprotection/config.xml.

  3. In the common-regexps section, modify the onsiteURL entry as follows and save the file.

    <regexp name="onsiteURL" value="([\p{L}\p{N}\\\.\#@\$\{\}%\+&;\-_~,\?=/!\*\(\)]*|\#(\w)+)"/>

NOTE
Curly braces ({ }) are included as accepted characters in the URL in HTML content.

After configuring the SMTP server, try to fill a form using the Sarah Rose persona and save it as a draft. When you save as draft, you get an option to receive the draft using email. On tapping the Send Email button, if you receive an email with a link to the draft of the application, your email configuration is successful. Ensure that you log in using Sarah’s credentials to see the draft.

Configure AEM DS settings aemds

AEM DS Service settings are required on the Publish instance for email communications in the reference site use cases. For detailed steps to configure AEM DS Service setup on the Publish instance, see Configure AEM DS settings.

For AEM Forms reference sites, in the AEM DS Settings Service, specify URL of the publish server instead of the URL of the processing server.

CAUTION
Do not put /lc in the processing server URL if you are configuring it for AEM Forms OSGi.

Deploy reference sites packages refsite

Install the following reference sites packages using Software Distribution.

To learn more about how to use packages, see How to Work With Packages.

After you have installed the packages and started the author and publish instances, visit the following URLs in your browser:

  • https://[server]:[port]/wegov
  • https://[server]:[port]/wefinance

If your installation is successful, you can access the We.Gov and We.Finance reference sites landing pages.

(Optional) Import sample data into Microsoft Dynamics optional-import-sample-data-into-microsoft-dynamics

The home mortgage application and auto insurance application reference sites are configured to use records from Microsoft Dynamics. The reference site package installs a custom entity and sample records that you can import into Microsoft Dynamics to run the reference site. Perform the following steps to migrate and set up the sample data:

To import the custom entity for auto insurance application:

  1. Download the WeFinanceAutoInsurance_1_0.zip solution package from https://[server]:[port]/content/aemforms-refsite-collaterals/we-finance/auto-insurance/ms-dynamics/WeFinanceAutoInsurance_1_0.zip on your AEM author instance.
  2. In your Microsoft Dynamics instance, go to Solutions in the Settings menu and click Import. Select and import the package.

To import the custom entity for auto insurance application:

  1. Download the AEMFormsFSIRefsite_1_0.zip package from https://[author]:[port]/content/aemforms-refsite-collaterals/we-finance/home-mortgage/ms-dynamics/AEMFormsFSIRefsite_1_0.zip. Select and import the package.

  2. In your Microsoft Dynamics instance, go to Solutions in the Settings menu and click Import. Select and import the package.

To import the customer and insurance policy records:

  1. Download the We.Finance Customers.csv, We.Finance Auto Insurance Renewals.csv, and home mortgage data files from the following locations on your AEM author instance:

    • https://[server]:[port/content/aemforms-refsite-collaterals/we-finance/auto-insurance/ms-dynamics/We.Finance Customers.csv
    • https://[server]:[port/content/aemforms-refsite-collaterals/we-finance/auto-insurance/ms-dynamics/We.Finance Auto Insurance Renewals.csv
    • https://[server]:[port]/content/aemforms-refsite-collaterals/we-finance/home-mortgage/ms-dynamics/Sarah%20Rose%20Contact.csv

  2. In your Microsoft Dynamics instance, do the following:

    • Go to Sales > We.Finance Customers and click Import.
    • Go to Sales > We.Finance Auto Insurance and click Import.
    • Go to Sales > We.Finance Home Mortgage and click Import.

Configure OAuth cloud service for Microsoft Dynamics configure-oauth-cloud-service-for-microsoft-dynamics

Configure the OAuth cloud service in AEM Forms to enable communication between AEM Forms and Microsoft Dynamics. Perform the following steps to configure the OAuth Cloud Service on AEM author and publish instances:

  1. On AEM author instance, go to Tools > Cloud Services > Data Sources > global. Tap Refsite Dynamics Integration icon and tap Properties.
  2. Go to Microsoft Azure Active Directory account. Add the copied cloud service configuration URL in the Reply URL setting for your registered application. Save the configuration.
  3. In the Authentication Settings tab, specify Service Root, Client Id, Client Secret, and Resource URL for your Microsoft Dynamics instance. Click Connect to OAuth that redirects to the Microsoft Dynamics login page.
  4. Provide your login credentials. Once logged in, you are redirected to the AEM Forms cloud service configuration page. Click Save & Close. The cloud service configuration is saved.
  5. Go to Forms > Data Integrations > We.Finance. Select Auto Insurance (Dynamics) and click Edit. Microsoft Dynamics entities are listed under the Data Sources tab. Wait until all entities are fetched from Microsoft Dynamics and listed under the data sources tab.
  6. Select the AutoInsuranceRenewal entity and click Test Model Object. In the input request section, specify the value for customer ID as “900001” and click Test. The Output section displays the records fetched from Microsoft Dynamics for customer ID 900001.
  7. In the input request section, specify the value for customer ID as “900001” and click Test. The Output section displays the records fetched from Microsoft Dynamics for customer ID 900001.
  8. Repeat steps 1-6 on the publish instance.

Configure Acrobat Sign Scheduler scheduler

Do the following on both author and publish instances:

  1. Go to AEM Web Configuration console at https://[server]:[host]/system/console/configMgr.

  2. Find and tap Acrobat Sign Configuration Service to open it for configuration.

  3. Configure Status Update Scheduler Expression as 0 0/2 * * * ?.

    note note
    NOTE
    The above scheduler configuration checks the status of the Acrobat Sign service every two minutes.

  4. Tap Save.

Configure reference site Acrobat Sign cloud service sign-service

Do the following on both author and publish instances:

  1. Go to Tools > Cloud Services > Acrobat Sign > global. Select AEM Forms Reference Site Sign and tap Properties.

    note caution
    CAUTION
    Ensure that the https://[host]:[ssl_port]/mnt/overlay/adobesign/cloudservices/adobesign/properties.html URL is added to the redirect URL list of OAuth configuration of Acrobat Sign API application.

  2. Specify Client Id and secret of the Acrobat Sign application OAuth configuration.

  3. (Optional) Select the Enable Acrobat Sign for attachments also option, and tap Connect to Acrobat Sign. It appends the files attached to an adaptive forms to the corresponding Acrobat Sign document sent for signing.

  4. Tap Connect to Acrobat Sign and log in with your Acrobat Sign credentials.

Configure Forms Common Configuration Service anonymous

Do the following on the publish instance to allow access to anonymous users:

  1. Go to AEM Web Configuration console at https://[server]:[port]/system/console/configMgr.
  2. Find and tap Forms Common Configuration Service to open it for configuration.
  3. Configure the Allow field for All Users.
  4. Tap Save.

Modify Rest Service for Form Data Model fdm

Do the following on both author and publish instances:

  1. Go to CRXDE at https://[server]:[port]/crx/de/index.jsp.
  2. Navigate to /conf/global/settings/cloudconfigs/fdm/roi-rest/jcr:content/swaggerFile and open the swagger file.
  3. Update the host and port settings as per your environment.
  4. Save the settings.
  5. (Author instance only) Go to Tools > Cloud Services > Data Sources > global. Select roi-rest and tap Properties. Tap Authentication Settings and set Authentication Type to Basic Authentication. Specify admin/ adminas the username/password to access the service. Tap Save & Close.

Integrate with Marketing Cloud integrate-with-marketing-cloud

You can integrate the AEM Forms with Adobe Analytics and Adobe Target. While Adobe Analytics helps you generate reports and analyze performance of adaptive forms, Adobe Target helps you deliver personalized experiences and perform A/B testing for adaptive forms.

Do the following to configure Adobe Analytics and Adobe Target in AEM Forms.

Configure Adobe Analytics configure-adobe-analytics

AEM Forms integration with Adobe Analytics allows you to monitor and analyze how your customers interact with your forms and documents. It helps you identify and fix problem areas and act to increase the conversion rate.

To experience this functionality in reference site, configure your Analytics account as described in Configuring analytics and reports.

To generate a report, seed data is bundled with the reference sites. Before you use seed data, do the following:

  1. Ensure that We.Finance and We.Gov analytics configurations are available in the AEM Cloud Services. You can find cloud services in one of the following ways:

    • Navigate to Tools>Cloud Services>Legacy Cloud Services or browse to https://<host>:<port>/libs/cq/core/content/tools/cloudservices.html.
    • In the Cloud Services page, under Adobe Analytics section, click Show Configurations. You can see We.Finance and We.Gov configurations available. Click to open the configuration. In the configuration page, click Edit. Provide valid Company, Username, Shared Secret (Password) and Data Center and click Connect to Analytics. Once you get Connection successful dialog, click OK on the configuration dialog. Configure the framework under the Analytics configuration as described in the Configuring Analytics and Reports.

  2. Navigate to https://<host>:<port>/system/console/configMgr and do the following:

    • In the Web Console Configuration page, find and click AEM Forms Analytics Configuration.
    • In the SiteCatalyst Framework field of the AEM Forms Analytics Configuration dialog, select we-finance(we-finance) or we-gov(we-gov).
    • Click Save and let the page refresh.

  3. Navigate to forms manager at https://<host>:<port>/aem/forms and do the following:

    • Open the We.Finance or We.Gov folder, and select the form for which you want to see the report.
    • Click Enable Analytics in the Actions Toolbar. After you have enabled analytics for the form, click Analytics Report. You can see a blank report generated. After a blank report is generated, you have to provide seed data shipped with refsite package to generate analytics report for demo purpose.

    Reference sites provide analytics reporting with seed data for credit card, home mortgage, and child support use cases. For configuration of seed data, see We.Finance reference site walkthrough and We.Gov reference site walkthrough.

Configure Target configure-target

The reference site showcases the integration of AEM Forms with Adobe Target that allows you to include targeted and personalized content in adaptive documents. It also enables creating A/B tests for adaptive forms.

To experience the integration in the reference site, do the following to configure Target in AEM:

  1. Start the author quickstart with the jvm argument -Dabtesting.enabled=true to enable A/B testing on the server.

    Note: If the AEM instance is running on JBoss, which is started as a service from Turnkey installation, add the -Dabtesting.enabled=true parameter in the following entry in the jboss\bin\standalone.conf.bat file, :

    set "JAVA_OPTS=%JAVA_OPTS% -Dadobeidp.serverName=server1 -Dfile.encoding=utf8 -Djava.net.preferIPv4Stack=true -Dabtesting.enabled=true"

  2. Access https://<hostname>:<port>/libs/cq/core/content/tools/cloudservices.html.

  3. In the Adobe Target section, click Show Configurations. You can see the We.Finance Target Configuration available. Click to open the configuration. In the configuration page, click Edit. The Edit Component dialog for the configuration opens.

  4. Specify your Client Code, Email and Password associated with your Target account. Select API type as REST.

  5. Click Connect to Adobe target. Once the Target account is configured successfully, click OK. You can see the packaged configuration has a Target Framework.

  6. Go to https://<hostname>:<port>/system/console/configMgr.

  7. Click AEM Forms Target Configuration.

  8. Select a Target framework.

  9. In the Target URLs field, specify the URL to AEM Forms. For example: https://<hostname>:<port>.

  10. Click Save.

Credit Card Application and Home Mortgage Application use cases demonstrate how to perform A/B testing and showcase a report for demo purpose. For walkthroughs, see We.Finance reference site walkthrough.

Next step next-step

Now you are all set to explore the reference site. For more information about reference site workflow and steps, see:

recommendation-more-help
a6ebf046-2b8b-4543-bd46-42a0d77792da