In this recipe, we will learn how to interact with e-mails and discuss configuring, sending, and receiving e-mails with Orchestrator. We will discuss both e-mail objects that the API currently has.
Unsurprisingly, we need an e-mail server. If you don't have one handy, you can use hMailServer for Windows; refer to the There's more... section of this recipe to learn how to install and configure this free, open source e-mail server.
For this recipe, we will use IMAP and SMTP to connect to the e-mail server. In the How it works... section, we also take a quick look at POP3 and SSL. We will also need two e-mail addresses. In our example, we will use [email protected] and [email protected].
There are two API objects that can be used when working with e-mail: the MailClient object and the EmailMessage object. We will use EmailMessage to send messages and MailClient to receive e-mail.
We will break this recipe down into configuration and sending/receiving e-mail.
As you probably need e-mail a lot in all your Orchestrator workflows, it's a good idea to store all the necessary e-mail configuration information in a configuration, as shown in the recipe Working with configurations in Chapter 8, Better Workflows and Optimized Working. Follow these steps to prepare the information you need to interact with a e-mail server:
- Create a new configuration.
- Create the following items:
Variable name
Type
Description
mailHostString
The IP or FQDN of the e-mail server.
mailUserString
The username that is needed to access the e-mail account (it's the e-mail in the case of hMail).
mailPassSecureString
The password for the user account.
smtpPortNumber
The TCP port that should be used (the default port is
TCP 25).SmtpFromNameString
A string that identifies the sender, for example, the full name of the user.
smtpFromMailString
The e-mail address of the sender.
receiveProtocolString
The protocol used, either POP3 or IMAP.
You can now use this configuration in workflows, as shown in the recipe Working with configurations in Chapter 8, Better Workflows and Optimized Working.
To send e-mails, there is a ready-made workflow that we can use by navigating to Library | Mail | Send notification. However, we will create a new one to understand the code and API a bit better:
- Create a new workflow and create the following variables (and if you did the configuration, link the values to your configuration):
Variable name
Section
Type
Description
mailToIN
String
The e-mail address the e-mail should go to.
mailCCIN
String
The e-mail address that should be sent to CC (carbon copy).
mailBCCIN
String
The e-mail address that should be sent to BCC (blind carbon copy); the BCC e-mail address is not disclosed to other e-mail recipients.
mailSubjectIN
String
The subject of the e-mail.
mailContentIN
String
The text content you want to send.
mailHostAttribute
String
The link with the corresponding configuration attribute.
mailUserAttribute
String
The link with the corresponding configuration attribute.
mailPassAttribute
SecureString
The link with the corresponding configuration attribute.
smtpPortAttribute
Number
The link with the corresponding configuration attribute.
smtpFromNameAttribute
String
The link with the corresponding configuration attribute.
smtpFromMailAttribute
String
The link with the corresponding configuration attribute.
- Add a scriptable task to the schema and enter the following code:
//Create a message object var message = new EmailMessage(); // set connections parameters message.smtpHost = mailHost; message.smtpPort = smtpPort; message.username = mailUser; message.password = mailPass; message.fromName = smtpFromName; message.fromAddress = smtpFromMail; //Set email specific information message.toAddress = mailTo; message.ccAddress = mailCC; message.bccAddress = mailBCC; // the subject of the message message.subject = mailSubject; // the mail content, message type and the character set message.addMimePart(mailContent,"text/html; charset=UTF-8"); // send the message message.sendMessage(); - Save and run the workflow.
You can now use this workflow to send e-mails.
There are already two workflows to receive e-mails by navigating to Library | Mail: Retrieve messages and Retrieve messages (via MailClient). The problem with them is that they don't have any output that we can use and therefore, they are quite useless to anyone who wants to use e-mails to check for content. In this example, we will use the more powerful MailClient object to create a workflow that receives e-mail and outputs the important parts of an e-mail.
- Create a new workflow and define the following variables; link them to the configuration from the first part, as required:
Variable name
Section
Type
Description
mailHostAttribute
String
Link with the configuration.
receiveProtocolAttribute
String
Link with the configuration.
mailUsernameAttribute
String
Link with the configuration.
mailPasswordAttribute
SecureString
Link with the configuration.
deleteMailIN
Boolean
Should the messages be deleted?
outMailOUT
Array of properties
The output array for messages.
- Add a scriptable task and bind all the variables to it.
- Enter the following script:
// initialize array var outMail = new Array (); // initialize Property var mail = new Properties(); //mail constructor var myMailClient = new MailClient(); //get the default port for the protocol var mailPort=System.getModule("com.vmware.library.mail"). getDefaultPort(receiveProtocol) myMailClient.setProtocol(receiveProtocol); // connect to mail server myMailClient.connect( mailHost, mailPort, mailUsername, mailPassword); //open the inbox myMailClient.openFolder("Inbox"); // get messages var messages = myMailClient.getMessages(); //if there are any messages loop thought them if ( messages != null && messages.length > 0 ) { for (i = 0; i < messages.length; i++) { //get the mail details and write them into a property var mail = new Properties(); mail.put("from",messages[i].from); mail.put("date",messages[i].getSentDate()); mail.put("subject",messages[i].subject); mail.put("content",messages[i].getContent()); // push Properties into array. outMail.push(mail); //delete messages if this was chosen if (deleteMail) { messages[i].delete(); } } } else { System.warn( "No messages found" ); } // Close mail connection myMailClient.closeFolder(); myMailClient.close(); - Save and run the workflow.
This workflow will output one array, with these property keys: from, date, subject, and content. Refer to the introduction to this chapter to learn how to access the output of this workflow.
Check out the recipe Working with XML in Chapter 10, Built-in Plugins to change the output of this workflow to XML.
E-mail can quickly become a really important addition to Orchestrator. Just think about the possibilities of sending e-mail to users after a task has been successfully finished (or not) or for sending a report of some sort.
In Orchestrator, the Mail.EmailMessage object is responsible for sending e-mails; to receive or work with e-mails, there are actually three objects: Mail.MailClient, Net.POP3Client, and Net.IMAPClient.
Mail.MailClient is the more powerful of the objects for reading e-mails as it comes with a lot of types and methods centered around e-mails that can be useful, such as extracting attachments or using different e-mail folders. The other two objects are more rudimentary and more directed at either POP3 or IMAP. For more information, I would suggest that you check out the API and look for the available attributes and methods that they contain.
The receive workflow that we have created in the recipe isn't very sophisticated, but it lets you build a workflow that extracts all e-mails so that you can check for specific content. Take a look at the example workflow 05.04.3 DoWhile loop to see how it can be used.
Sending an attachment is more or less easy; we will showcase it by uploading the attachment as an Orchestrator resource. We covered how to work with resources in the Working with resources recipe in Chapter 8, Better Workflows and Optimized Working.
the following example attaches a picture to e-mail. There is also another example workflow in the example pack that lets you attach any file from the local Orchestrator to an e-mail: 09.01.5 SendAttachment(File).
- You will need to add the following variable to the send the workflow:
Name
Type
Section
Use
attachmentResourceElement
IN
Contains the Orchestrator resource for the attachment
- Add the following code to the send script:
message.addMimePart(attachment.getContentAsMimeAttachment());
In order to fetch an attachment from an e-mail, we need to have a much closer look at how the MailClient object works. Each e-mail can have multiple content parts, such as attachments and text. To check whether a message contains more than one part, use the MailClient.isContentMultiPart() method; it returns either true or false. To get all the parts, use the following:
var multiPartContent = message.getMultiPartContent();
This will return an array (multiPartContent). Now we need to look into each of the parts by looping through them. We get a single part by using the following :
var bodyPart = multiPartContent.getBodyPart(counter);
To know whether the body part is an attachment, check bodyPart.isAttachment(). To fetch the attachment, use the following :
var attachment = bodyPart.getAsMimeAttachment();
You now have the attachment as a mime type. Refer to the Working with resources recipe in Chapter 8, Better Workflows and Optimized Working.
To get the mime type of the attachment, use attachment.mimeType; to get the name, use attachment.name.
A fast and pretty easy way to configure the e-mail server is the open source hMailServer, which you can download from www.hmailserver.com.
Creating a non-relaying, local-only e-mail server is pretty straightforward. I will not waste too much page space on this, so there are no screenshots. The following steps let you create a e-mail server and e-mail addresses that are configured for SMTP, POP3, and IMAP:
- In Windows, download hMail and start the installer.
- Make sure that SMTP (
TCP 25), POP3 (TCP 110), and IMAP (TCP 143) can pass through the Windows firewall. - Select a folder where you would like to place the program binaries (this is not the place where the e-mails will end up; hMail needs less than 15 MB disk space).
- Install Server and Administrator tools.
- You can now choose to use an external DB (MSSQL, MySQL, or PostgreSQL) or the Microsoft SQL Server Compact Edition (2 MB installation size) shipped with hMail (use the compact edition for the lab).
- You are now asked whether you would like to create a shortcut (recommended for the lab).
- Set a password for the admin access of hMail.
- After the installation is finished, run Administrator tools.
- Connect to the localhost e-mail server and enter the admin password from step 7.
- After the administrator console opens, click on Domains and then click on Add.
- In the Domain field under General, enter your domain name and click on Save.
- Your domain is now created. Click on your domain, then click on Accounts, and then click on Add.
- To create an e-mail address, just fill in the name of the account by navigating to General | Address and give it a password. Adjust Maximum size (MB) to 10 MB (we will just use some text e-mail). Finally, click on Save.
That's it. Now you can play with this recipe.