Sample Project: Basic Email

The Basic Email Sample Project creates an OL Connect project that sends emails with two attachments: a Return and Refund Policy (PDF) which is the same for all emails, and a delivery note (PDF) which is attached to the email dynamically. The email has a mailto link.

For an introduction to this Sample Project, see Sample Projects overview video on the OL Learn website (start at 21:07) or on Youtube: Email.

Installing the project

To start the Sample Project, select File > New > Sample Projects > Basic Email from the menu. (See also: Basic Email - Sample Project.)

Alternatively, open the Welcome screen, click New at the left, then Project at the right and select the correct type of project.

Tip: Click the Home icon icon at the top right to reopen the Welcome screen.

Note: In order to use the project, OL Connect Server and OL Connect Workflow must be installed on the local machine.

The wizard lets you select the folder in which you want the solution to be installed. Since Sample Projects are versioned (see Versioned projects), the software suggests to store it in the OL Connect folder that is located in your Documents folder. By default, all versioned project have their own folder under Documents/Connect.

In the selected folder, the Sample Project will create two subfolders: Configurations and Workspace.
The project's resource files are saved to the Configurations folder.
The Workspace folder is used for debugging or running the solution. It has an In folder that may be used to monitor incoming data and an Out folder to write output files to.

The selected folder's path is saved to a global variable in the Workflow configuration (see The Workflow configuration).

The variable is used in the data mapping configuration (see Project details).

In addition you have to make the settings for outgoing mail (for the details see Basic Email - Sample Project).
These settings are copied to the Create Email Content task in the Workflow process.

Finally, enter the username and password that will allow the software to access the Connect Server.

Testing and running the project

Once the Sample Project has finished the installation, the project is ready to be tested.

  1. If the templates and data mapping configurations haven't been sent to Workflow yet, do that first (see Sending files to Workflow). This requires that the Workflow service is running (see Starting the Workflow service in Workflow's Online Help).

  2. Locate the Workflow configuration in the project folder and open it in OL Connect Workflow.

  3. Select the em_basic_sending_email process

  4. Open the Debug ribbon and click Run.

The process should send the email messages along with a delivery note and the Return and Refund Policy to the email address entered in the Sample Project. This is the sender's address.

Running the project

Having tested the project, you will be ready to send it to Workflow; see Saving and sending a Workflow Configuration in Workflow's Online Help.
The project will run when you copy the Sample Data.xml file from the Configurations\Data folder to the Workspace\In folder.

By default the project will still send all the emails to the sender's address. To change this:

  1. Open the Create Email Content task and select the Email Info tab; then uncheck the Send emails to sender (test mode) option.

  2. Replace the test data with real data:

    1. Open the Sample Data.xml file. You will find it in the Configurations\Data folder.

    2. Replace the email addresses in this file by real email addresses that you have access to.

    3. Copy the modified sample data file from the Configurations\Data folder to the Workspace\In folder.

The emails should now be sent to the email addresses that you entered in the sample data file.

Project details

The email template

The email's design is in the EM_BASIC Email Message template. It contains one Email section (see Email templates).

Styling is done via style sheets (see Local formatting versus style sheets). The style rules are in the context_htmlemails_styles.css file. Note how they use HTML tags, IDs and classes to select elements. (See also: Selectors in OL Connect.)
The @media rules make the email responsive (see also: Designing an Email template).

Note: Even though email clients do not read CSS files, CSS files can be used with the Email context in the Designer. See Using CSS files with HTML email.

Two attachments are added to the email, in different ways.

  • The Return and Refund Policy PDF is stored in the template (in the Images folder). Right-click the Email section and select Attachments to see how this is attached to the email.
  • The delivery note is a dynamic attachment, based on a data field. It is attached to the email by the Attachment script. To learn how to create dynamic attachments, see Dynamic attachments: creating file names based on data fields.

All scripts are listed on the Scripts pane. You can double-click to open them.

Tip: Hover over the name of a script in the Scripts pane to highlight parts of the template that are affected by the script.

  • Some data are added to the email via simple text scripts. Such scripts search the template in order to replace a certain text that is surrounded by @ (e.g. @First@) by the correct data. (See: Variable data in text: scripts and placeholders.)

  • The To and Subject scripts apply to email fields. (Click Email Fields at the top of the email to expand all email fields.) For information about this kind of scripts, see: Email header settings.

  • Finally, there are two custom scripts:

    • The Personalize Support link script adds the order number to the 'support team' link (which is a mailto link).

    • The Year script puts the current year in the footer.

    For more information about writing custom scripts, see: Writing your own scripts.

The Workflow configuration

The project's Workflow configuration, Sending Email, contains just one process. It is a simple OL Connect Email process (see Email processes with OL Connect tasks).

To open the configuration, open Workflow, click the Workflow button, select Open and browse to the project's Configurations\Resources folder.

Double-click on a task to see its properties.

  • The Folder Capture task reads the project's Workspace path from a global variable. The value of that variable is set by the Sample Project when it installs the project.

  • The Execute Data Mapping task extracts data from the sample data file and outputs them in the Metadata.

  • The Create Email Content task creates the emails, using the Metadata as data source.
    Note that it sends the emails in test mode, which means it will send the emails to the sender.
    The settings on the Email Info tab are taken from the Sample Project.

  • The Delete task is an Output task that does nothing, actually; it doesn't even remove anything. This step is sometimes useful when running a project step by step in Debug mode, as it forces preceding tasks to return their output to the Workflow process. The Create Email Content task, however, does not return the generated emails to the Workflow process.

The data mapping configuration

The Workflow process uses a data mapping configuration, made with The DataMapper: EM_BASIC Data.

To open the data mapping configuration, open the Designer, select File > Open from the menu and browse to the Configurations\Resources folder.

This data mapping configuration will of course only work with the appropriate data files. It was designed for XML files that are structured like this file: Sample Data.xml (in the Configurations\Resources\Data folder).
The sample data yields 5 records with customer data including a detail table with invoice details.

Much of the information in the extracted records isn't used in the email, but was used to create the delivery notes.

The email addresses are used in the template (in the To field), but ignored in the Workflow process because it sends emails in test mode (see The Workflow configuration).

Using a Workflow variable

The path to the delivery note is constructed via JavaScript:
automation.variables.em_basic_workspace + '\\Delivery Notes\\' + record.fields.OrderNumber + '.pdf';

The script uses a property: automation.variables.em_basic_workspace, which is defined in the Preprocessor step. (See also: Properties and runtime parameters.)
In this case, the variable holds the project's path. The order number in the path is extracted from the sample data.

Note: In order to use the value of a Workflow variable - an 'Automation variable' - as a property in the Preprocessor step, the property and the Workflow variable must have the exact same name.

To see the script, click on the DeliveryNote field in the Data Model pane at the right; then take a look at the Step Properties pane (in the middle).

To see where the property is defined, click the Preprocessor step on the Steps pane (at the left); then look at the Properties section on the Step Properties pane.

Customizing the project

A project is a great starting point for building an OL Connect solution. This part explains how to make changes to the project.

Do you intend to expand the project into a solution where Workflow runs on a different machine that also has a different regional setting? Then indicate the desired encoding in the Designer preferences (see Sample Project deployment settings) before installing the project.

Input data

If your input data is in a file, but the file is of a different type or has a different structure, create a new data mapping configuration to match it. (See Creating a new data mapping configuration.)
When it's finished, send the new data mapping configuration to Workflow (see Sending files to Workflow).
Then open the Workflow configuration, double-click the Execute Data Mapping task to open it and select the new data mapping configuration.

To capture input data from a different source:

  1. Replace the Folder Capture Input task by the appropriate Input task. See: Input tasks in Workflow's Online Help.

  2. Add a Send to Folder task directly after the new Input task and set its output folder to the Workspace\Debug folder (%{global.pr_prom_workspace}\Debug). This task writes the job file to a file, which can then be used as sample data file when creating a data mapping configuration and debugging the Workflow process.

  3. Run the process once (see Testing and running the project) to capture the job file that contains the input data.

  4. Use that file to create a new data mapping configuration, send the data mapping configuration to Workflow, and adjust the Workflow configuration, as described above.

Note: If the input data is JSON, you don't need a data mapping configuration: JSON data can be used in a template as is. See: Adding JSON sample data.
However, if you want the data to be saved in the OL Connect database, put the XML/JSON Conversion plugin before the Send to Folder task to convert the JSON to XML, and create an XML data mapping configuration to extract the data.

The email

Often this type of email has a Call to Action button which redirects the user to the website of the vendor, where the user could log on to the site and follow an online payment process, for instance.
To get an example (or to start over) you could use one of the template wizards that start an 'action email'; see Email Template Wizards.

You could add text, images and other elements to the email (see Content elements) and change the layout (see Styling and formatting). Keep in mind though that there are special design standards for HTML email (see Designing an Email template).

In order to further personalize the email, open your data mapping configuration (or JSON data, if the input data will be in that format; see Adding JSON sample data) and use the data fields to personalize the email. (See: Personalizing content.)

Tip: The Designer can have one data mapping configuration and one template open at the same time. Use the tabs at the top of the workspace to switch between the two. Click the synchronize button on the Data Model pane to make sure that the Data Models are the same in both.

Once the template is ready, send it to Workflow (see Sending files to Workflow).

Finally, in Workflow, adjust the process: double-click the Create Email Content task to open it, and select the new template. This is only necessary when the file name has changed.

Workflow configuration

The current Workflow configuration is very simple. In reality, a process that generates email output will be part of a larger project, in which, for example, invoices are produced in a separate process, stored in a folder and attached to an email at a later time.

For general information about processes in Workflow see About Processes and Subprocesses, in the Online Help of Workflow.