Lab 2: Implementation - Check Email

Step 1: Connect to Windows EC2 Instance

Using your RDP client software, connect to your Windows Virtual Machine (VM) instance. Make sure you use the address and credentials provided for you by the instructor.

We recommend using 1680x1050 for the connection resolution. If you would like to use a higher resolution you can try, but be sure to keep the same resolution at all times.
The Windows VM image provided contains all necessary tools to run this workshop. In this lab, we will use MuleSoft RPA Builder to model and implement the Module 1 automation process.

Step 2: Configure RPA Builder and Open the Process

Locate the MuleSoft RPA Builder shortcut icon on the desktop and double click on it
The first time you open the RPA Builder, you will be prompted to enter your MuleSoft RPA Manager address and credentials. You should be given these by the instructor.

Enter the RPA Manager Address (no need to type the https:// prefix) and click Continue:

Then your User Name and your Password and click Sign In:
Once RPA Builder is opened, click on the Repository Explorer tab. In the explorer tab you should see a number of processes that are currently in Build phase. Locate your process and double click to open it.

Important

Make sure you locate and open YOUR process. Remember you should have used the following pattern to name it during module 1/step 2.3:

<your name and surname/initials>-Module 1-Automate Data Entry into Legacy App

If the Repository Explorer tab is not displayed, you can enable it by going to the View menu and clicking on Show Repository Explorer:
After double clicking your process, it will be downloaded from the server and stored locally in your Windows VM. Any changes you make will be local. Later we will see how you can upload your changes to the RPA Manager server.
Find below the final BPMN model definition of the Automation Process we are going to build in this module. Thanks to the BPMN model import you did in the previous lab, there are some activities that are in place already.
1. Check the INBOX mailbox to see if there’s any unread mail (read messages one by one).
2. If there’s an unread mail, continue the flow (YES condition).
3. If there are no pending mails, end the whole process (NO condition).
4. Read a mail and check if it contains an attachment. If YES continue to activity 5; if NO, go back to activity 1 to read the next mail, if any.
5. Extract the invoice data from the attachment (PNG file) using OCR technology and store it in variables.
6. Open the Financial System and enter the data through bot actions.

Step 3: Navigate the Financial System Legacy App

Before starting the development, let’s have a look at the Financial System we will be interacting with. Locate the Financial System shortcut on the Desktop and double click on it (if no shortcut is available the app can be found at this path C:\Users\workshop\Desktop\LegacyApps\Java and started double clicking start.bat).

In the logon window, enter any username and password and click the Login button.

The application has 3 tabs:
- Home
- Invoices: where you can check, refresh and delete all existing Invoices
- New Invoice: to enter a new invoice
Close the Financial System application for now. The bot will open it when it is needed.

Step 4: Import prebuilt model

In order to speed up the workshop, we’re going to import a prebuilt process with some of the needed assets already created for you. We will overwrite the existing process, but that’s fine.

In RPA Builder, go to the File menu and click on the Import Project option:

Click on Yes to confirm we’re going to overwrite the existing project.
Locate the Module_0-Automate_Data_Entry_into_Legacy_App.crpa file in the Windows machine where you previously unzipped the provided ZIP file and select it in the browse dialog.

After the import is completed, this is how it should look like:

The imported model also includes a number of Activity Parameters preconfigured for you. Activity Parameters are variables available throughout the Process scope. More on this later.

Step 5: Implement the Check Email Bot Task

The first Activity we need to implement is the mail check.

Double click on the existing Check Email activity and its configuration window will be opened below:
Now, let’s configure the necessary bot steps in such Check Email activity.

Open the Toolbox tab where you can find all the bot steps available to configure the process activities:

In the Activity properties (steps) window opened below, you can see it’s organized in three main elements:
- Workflow Initialization: contains additional elements that are not available in the Toolbox such as Activity Parameters that which will be used in a particular Activity.
- Activity Workflow: where all bot steps will be placed and will be executed in order (from top to bottom).
- Wokflow Finalization: where you can add specific bot steps depending on whether a Workflow has failed or has run successfully.
Make sure the Activity Workflow section is expanded. In the left hand side Toolbox, locate the Mail Operations section (you can scroll down or type mail in the Filter input box at the top) and drag and drop the Mail Session step into the Transaction empty section as follows:
Double click on the Mail Session step you just dropped to set it up:
1. Set the Operation Mode to Read mails from inbox
2. Use IMAP with SSL/TLS connection
3. Use the Server address, Server port, Username and Password provided by the instructor.
4. Click on Test Connection to test the settings
  
  Following gmail account specific settings.
  
  Setting name Value
  
  Protocol
  
  IMAP
  
  Encryption
  
  SSL/TLS
  
  Server Address
  
  imap.gmail.com
  
  Server Port
  
  993
  
  Following outlook account specific settings.
  
  Setting name Value
  
  Protocol
  
  IMAP
  
  Encryption
  
  SSL/TLS
  
  Server Address
  
  outlook.office365.com
  
  Server Port
  
  993
  
  If the test fails, let the instructor know.
Click OK to save the settings.
In the previous Mail Session setup, we used hardcoded settings, and that’s not good practice. We are going to leverage the Activity Parameters to correct that.

Activity Parameters are variables that can be used across the whole Automation Process. An Activity Parameter is also an input/output variable to the Process when it has been made 'Invokable' to be called as a REST API.

In the previously imported project, we have created some Activity Parameters for you. Let’s have a look to them. Locate and click the Business Process Initialization button at the top right of the Canvas and click on the Activity Parameters link:

Some variables already have a default variable value which will be very convinient for some later tests.

However, we want you to learn how to create them, so we will now define some to hold the Mail Session settings.

Click on the Add new parameter button located on the bottom-left to add a new parameter/variable. You’ll need to add these ones for the Mail Session activity:

Parameter name Type

mailAddress

alphanumeric

mailPort

integer

mailCredentials

user account

As commented already, when defining an Activity Parameter you can specify a default value that will be valid until you modify it during the workflow.

For these parameters type in the mail settings provided by the instructor that you already tested as hardcoded values in the previous step.

Click OK to save the parameters.
Let’s use/link some of these parameters into the Mail Session settings.

When you want to use any Activity Parameter in any activity of the flow, you first need to link them in the activity initialization section. Remember always to do so. If you forget it, the parameter will not be available within the activity step.

Double click on the Check Email activity to open its configuration. Expand (if not expanded already) the Workflow Initialization section at the beginning and double click on the Activity Parameters button:

Use the arrow buttons to include/exclude the following parameters into this activity (the just created ones and some others) and click OK to save:

attachmentFilename attachmentsTemporaryFolder containsAttachment mailAddress mailCredentials mailPort newMailAvailable
Double click on the Mail Session step to open the settings popup window.

When you want to link any of the settings to an external variable (such as an activity parameter), you have to click on the pin button () generally located on the right of the setting.

For example, for the Mail Session setting’s Server address:

You can link setting to any available external variable; these can be existing variables that were previously linked to the current activity or the result of a previously executed step. Expand the Activity Parameters section and select the mailAddress one:

Once linked to an external variable, it will be displayed and the pin button color will change to black:

Repeat the above steps to link the Server port and User account settings accordingly:

Click OK to save and close the settings.

Note

For the Mail Session and other similar steps, you cannot test the connection when the settings are linked to an external variable. If you want to test the connection to an external server within the step configuration, hardcode the settings, perform the test and, if it works, then link the corresponding Activity Parameter.
Now that we have the Mail Session configured, we need to read the INBOX and retrieve any new mail.

Drag the Read Mail action step into the Mail Session. Double click on it to set the parameters:

Click on Add Filter and select the Unread one.

Click again to add a Subject based on typing the following pattern: <your initials>-

(CC- as an example in the screenshot below). This means that only unread mails containing this pattern in the subject will be retrieved by this step.

The reason for this is that you will be using a shared mail account. So you want to filter mails sent by you, meaning that you’ll need to include this pattern in the mail subject when composing one.

Set the following settings too:
- Read maximum number of 1 mails.
- Tick the Save attachments check box.
- Use %TEMP%\attachments as the directory path.
- Tick the Create directory if it does not exist check box.
Click OK to save.
Now, three things may happen: either no new mails have been retrieved (remember, unread mails containing your pattern in the subject) or one new mail is retrieved but may or may not contain an attachment. We want to handle these three situations.

For this purpose, we have also included four Activity Parameters in the imported process: newMailAvailable, containsAttachment, attachmentsTemporaryFolder and attachmentFilename.

We need first to reset the boolean parameters before reading any email.

Drag & drop two Set Variable steps inside the Mail Session but before the Read Mail step as follows:

On the first one, click on the pin button () to set the target variable to the newMailAvailable activity parameter as follows:

Click OK to save and then double-click the step itself to set its name (Reset newMailAvailable) and value (false):

Click OK to save.

Repeat the same for the second Set Variable step as follows:
- Name: Reset containsAttachment
- Variable (pinned): Activity Parameters.containsAttachment
- Value: false
If and only if a new mail is read, the step(s) inside the Read Mail step/block will be executed. So we need to add a number of steps to handle the new email.

Drag and drop two Set Variable steps inside the Read Mail step/block and set them as follows:
- Name: Set newMailAvailable
- Variable (pinned): Activity Parameters.newMailAvailable
- Value (pinned): Read Mail.isSucceeded (we’re setting the variable with one of the result variables returned by the execution of the Read Mail step)
- Name: Set temporary attachments folder
- Variable (pinned): Activity Parameters.attachmentsTemporaryFolder
- Value (pinned): Read Mail.AttachmentsLocalFolder (a temporary subfolder gets created on every successful Read Mail execution. The mail attachment files, if any, will be stored there)
The Read Mail step doesn’t provide a result variable letting us know if the mail included an attachment or not. So we then need to search for any file inside the Read Mail.AttachmentsLocalFolder. If the temporary folder is empty, the mail contained no attachment. If at least one file is stored there, we need to keep its filename and also we need to set the correspondant Activity Parameter.

Drag and drop an Iterate over Files step and two additional Set Variable steps inside its block as follows:

Double click the Iterate over Files step and set it up as follows:
- Directory Path (pinned): Activity Parameters.attachmentsTemporaryFolder.
- File name: *.*
- Use a regular expression for File name: unchecked
- Iteration Limit: checked to 1.
- Force error if iteration limit is exceeded: unchecked.
- Force error if no file found: unchecked.
- Recursive loop: unchecked.
Set the two Set Variable steps inside the Iterate over Files block as follows:
- Name: Set attachmentFilename
- Variable: Activity Parameters.attachmentFilename
- Value: Iterate over Files.IterateFileName
- Name: Set containsAttachment
- Variable: Activity Parameters.containsAttachment
- Value: True
Finally, just after the Iterate over Files step/block, drag & drop a Force OK State step. This is needed to avoid an (expected) error in case the Iterate over Files step doesn’t find any file (mail retrieved with no attachment):