Hi there AppWorks fans,

Welcome to a new installment of AppWorks tips.

Today we get a deeper dive to a question I get on a regular basis. How to configure mailing functionality in your solution. In other words. How to config sending out mails and receiving mail from an external mail service. This covers also the feature to extract the attachments from the mail and save them as separate files into the system.

But first an overview of the required steps:

1. Add a second user to CentOS for sending out mail from one user to another user
2. Update the ‘Email’ service container with correct Mailboxes XML
3. Set ‘Anonymous’ access on the security settings of the Email service group
4. Use the ‘GetMessageCount’ service to test if messages are getting in
5. Add an Email building block to an entity
6. Update the new created email configuration document in the /app/admin console
7. Add an Email template building block with entity data
8. Update the default view layout of the entity to also show e-mail data

Let get right into it…

Step 1…add a second user to CentOS

This second user is required to send mail from one user to another user. Why?…Because we’ll configure AppWorks to read-out one mailbox (in our case the mailbox from our previous configured otadmin@mydomain.com). From our test standpoint (with Mozilla Thunderbird as client) you will then always see an empty inbox as AppWorks will pull messages from the server almost directly before you see them in the inbox from this client!

I assume you already have a mail service (‘postfix’ with ‘dovecot’) up and running on you VM. Otherwise search for the post where we explain to bring up a brand-new mail service on your CentOS VM.

Open a ‘MobaXTerm’ console to your VM and user this command for creating a new ‘mail’ account: useradd -m mailuser -s /sbin/nologin

And set a password passwd mailuser. Give it password ‘admin’

Now use this information in Mozilla Thunderbird to send and receive mail for the brand-new user:

1
2
3

Your Name: mailuser
Email: mailuser@mydomain.com
Password: admin

The IMAP and POP3 settings should like this

Now see it you can send/receive a test mail with the new ‘mailuser’ account…ready?

Now make sure you can also send/receive mail between otadmin@mydomain.com and mailuser@mydomain.com

When !#$!@#$ hits the fan, you can find logging here sudo tail -f /var/log/maillog

There might be a dot in the file: sudo tail -f /var/log/mail.log

Step number 2…update the ‘Email’ service container with correct Mailboxes XML

Here we tell the AppWorks platform what mailbox should be used to pull messages from.

We execute this step in the ‘system’ organization of the AppWorks platform. We also use the ‘sysadmin’ account to make the appropriate change!

Open the ‘System Resource Manager’ and go to the ‘Email’ service container where you get the properties from. Go to the ‘Mailboxes’ tab.

Here we already put some information for sending out mail. That is what we also tested in the post about making a mail service available in AppWorks.

Now update area with this new XML file…WTF??…Don’t ask the messenger…I also got this from the documentation. See below this XML for notes to take on this XML!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

<emailboxes xmlns="http://schemas.cordys.com/1.0/email/configuration">
	<emailbox>
		<name>Development</name>
		<username>otadmin</username>
		<password>admin</password>
		<folders>
			<folder>INBOX</folder>
		</folders>
		<triggers>
			<trigger appliesTo="INBOX">
				<name>AllFolders</name>
				<rules>
					<rule section="SUBJECT">
						<pattern type="REGEX">
							<value>.+</value>
							<store>
								<token>
									<name>Subject</name>
									<value>0</value>
								</token>
							</store>
						</pattern>
					</rule>
					<rule section="TO">
						<pattern type="REGEX">
							<value>.+</value>
							<store>
								<token>
									<name>To</name>
									<value>0</value>
								</token>
							</store>
						</pattern>
					</rule>
					<rule section="FROM">
						<pattern type="REGEX">
							<value>.+</value>
							<store>
								<token>
									<name>From</name>
									<value>0</value>
								</token>
							</store>
						</pattern>
					</rule>
					<rule section="MULTIPART">
						<pattern type="CUSTOM">
							<value>com.eibus.applicationconnector.email.sample.Base64Plugin</value>
							<store>
								<token>
									<name>Base64Attachment</name>
									<value>string</value>
								</token>
							</store>
						</pattern>
					</rule>
				</rules>
				<message>
					<method>receiveEmail</method>
					<namespace>http://schemas.cordys.com/entity/email/1.0</namespace>
					<user>cn=awdev,cn=organizational users,o=appworks_tips,cn=cordys,cn=defaultInst,o=mydomain.com</user>
					<sync>true</sync>
					<namespacemappings>
						<namespacemapping>
							<prefix>ns</prefix>
							<namespace>http://schemas.cordys.com/entity/email/1.0</namespace>
						</namespacemapping>
					</namespacemappings>
					<input xmlns:ns="http://schemas.cordys.com/entity/email/1.0">
						<ns:from />
						<ns:subject />
						<ns:body />
					</input>
					<mappings xmlns:tns="http://schemas.cordys.com/1.0/email/configuration">
						<mapping>
							<source>.//ns:from</source>
							<value src="From" />
						</mapping>
						<mapping>
							<source>.//ns:subject</source>
							<value src="Subject" />
						</mapping>
						<mapping>
							<source>.//ns:body</source>
							<value src="Base64Attachment" />
						</mapping>
					</mappings>
				</message>
			</trigger>
		</triggers>
		<automaticrestart xmlns:tns="http://schemas.cordys.com/1.0/email">true</automaticrestart>
		<restartinprogress xmlns:tns="http://schemas.cordys.com/1.0/email/configuration">false</restartinprogress>
	</emailbox>
</emailboxes>

Notes on the XML (as far as I could figure out)

• The <triggers> tag is added
• Every <trigger> has some rules applied and a <message> configuration
• The MULTIPART has something to do with Attachments
• The <user> tag in the <method>receiveEmail</method> section needs to point to a user in your environment (I created users directly in same organization as my solution). The string for your solution can also be found in the CMC tool sudo sh /opt/opentext/AppWorksPlatform/defaultInst/bin/cmc.sh

I know…I use another user…Not the mentioned ‘awdev’ account!

Save the service container and make sure it restarts correctly. Directly continue with the next step in the same ‘system’ organization for this same ‘Email’ service container!

Step 3…set ‘Anonymous’ access on the security settings of the Email service group

In the ‘system’ organization with the ‘sysadmin’ account open again the ‘System Resource Manager’ and show the ‘Service Groups’ and get the ‘Security’ settings for the ‘Email’ service group.

And now make sure to add the ‘Anonymous’ account to allow to use this service.

Why do we need this?

During my testing I faced the error that the SendMail service is not accessible by anonymous users and this fixed the issue for me!

ERROR I got in the log: Anonymous access is denied for the Web service operation 'SendMail'

Next step number 4…use the GetMessageCount service to test if messages can be reached from the AppWorks platform

Open the AppWorks Explorer with ‘awdev’ in your own beloved organization and open the ‘Web Service Interface Explorer’ artifact. Search for ‘setprofile’ and get the properties of the ‘SetProfile’ operation for the ‘Method Set Email’ interface.

Now test the ‘GetMessageCount’ operation with this SOAP message:

1
2
3
4
5
6
7

<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <GetMessageCount xmlns="http://schemas.cordys.com/1.0/email">
      <folder></folder>
    </GetMessageCount>
  </SOAP:Body>
</SOAP:Envelope>

You get this message “The user profile is not found or is invalid”?

Then first set the profile by testing the ‘SetProfile’ operation with this SOAP message in that same webservice operation list:

1
2
3
4
5
6
7
8
9
10

<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <SetProfile xmlns="http://schemas.cordys.com/1.0/email">
      <displayName>Development</displayName>
      <mailId>otadmin@mydomain.com</mailId>
      <password>admin</password>
      <userId>otadmin</userId>
    </SetProfile>
  </SOAP:Body>
</SOAP:Envelope>

Is it all still working?…Still cool stuff?…Let’s dive deeper into the next step!

Step 5…add an Email building block to an entity

I use my ‘Category’ entity for this, but you can also use your own. Open that entity and add an ‘Email’ building block.

After the building block is in place you see in the right panel some extra configuration where you are required to add a new ‘Email configuration’…Hit that plus-signed button!

You’ll get this screen with some ‘secret’ information!

Just save it with a fancy name like ‘MyEmailConfiguration’…We get to this in the next step!

Now tell the mail configuration what should happen in all the circumstances:

Repository to select attachments from gives you the option to make the attachment option available on the messages sending out from AppWorks to a mail service

• Content is the current document storage location for your solution. In my case it will be the Documentum back-end as we changed this in another post, but we’ll check it that is really the case as ‘Business workspace’ describes the same situation…We’ll check it!
• None hides the attachments option from the end-user
• Business workspace is content stored in an external system like ‘Content Server’ of another xECM connection. I got this information from the documentation! As the ‘Business workspace’ is just a building block like others we’ll play with that in another post…Just placed it on the backlog.

Save email messages as files in gives the option where to save those messages and if you even want to save them

Save location gives you the option to select the ‘Default’ location. Don’t ask…just select it.

Save email as gives you the option to save as ‘.eml’ or as ‘.msg’

Save attachments of incoming email in gives you the option to extract attachments from the mail and save them as separate object in the storage…The good stuff!

Save location gives you the option where that location should be.

I configured it like this for now:

Then you see also an ‘Advanced configuration’. Click that blue link and see what magic will happen!

Yes…It’s just an ‘Emails’ relation where you can refine some settings for the content to be saved, but you also have a full set of building block available again!

And if you can even dive deeper by clicking that red arrowed link to make specific configuration on the content that might be used…And…If you haven’t asked yourself that question yet…As I was wondering where the ‘Default’ location came from and how it’s related…There is the answer…It’s a bit hidden behind several related entities.

Then step 6…update the new created email configuration document in the /app/admin console

Now for the administration part so the just ‘generated’ email configuration is changed to its best settings so the entity ‘knows’ what account to connect with for sending and receiving mail. This setting must be done in the /app/admin console where you will find this option that I configured like this.

No need to search for the save button as this happens automagically!

The mail address you use here should be the one that belongs to the account that you configured in that large XML in a previous section.

Next is step number 7 with…adding an Email template building block with entity data

Back to our ‘Category’ entity…And after you added that ‘Email’ building block you might have seen that the ‘Email template’ also was ungrayed and available for an ‘Add’ action…So, let’s do what is required to do for this step.

And give it a nicely recognizable name

Now the Email template editor can be opened and there you should be able to structure your reusable message with information from the entity based on variables. The values are retrieved with an expression like {item.Properties.cat_description}

Make something nice and use the expression buttons to see the possibilities.

For my example I also added a new property with the name ‘cat_mail_notifier’ where I filled in a default address to send a mail to. In my case mailuser@mydomain.com

Final step 8…update the default view layout of the entity to also show e-mail data

The last step for the low-coding part is the layout for the entity. If you don’t have one already you can add a new one from the building block list with the name ‘default_layout’. Open it in the designer.

Make sure you have something like this where the ‘Email’ panel is ‘the one’ we want to see.

Also make sure the panel is used when we open a new created instance of a ‘Category’ with these setting.

And now is the time for saving the entity and do a publish…

And then off course we have our testing step!

Go the front-end of the solution /app/start and create a new category and directly open it after creation. Now the new ‘default_layout’ should be shown with a screen like this

Time for hitting that ‘Send email’ button from the action bar. Or the plus-signed button in the Emails panel. You will get a modal panel where you can select you ‘Notification’ template that is filled in with data from the current entity.

Click OK to get a ‘New email’ view like this that we can directly ‘Send’ out.

If all is properly configured you should receive an email in the inbox of mailuser@mydomain.com with the Thunderbird client.

And it’s also saved in the Sent items in AppWorks…and as .eml content in that ‘Default’ location (as configured and expected)

Now we do a reply on the mail in Thunderbird and sent it to otadmin@mydomain.com with including an attachment from our local machine!

After sending out the mail you ‘normally’ would see the mail popping in you Thunderbird account in the mailbox for ‘otadmin’, but as we pull it from the mail server with our AppWorks configuration you will see it in the Inbox of the Emails panel.

You also see the attachment is saved as a separate content object in the ‘Default’ location…Great!

Test passed…

Now for the remaining great question…Where are those mails and the attaches really saved for our ‘Default’ content location!?

I would expect in the Documentum storage!…Why?…Because I saw that the related ‘Emails’ entity had a content block that points to the same location as the content block for the ‘Category’ entity itself.

But let’s double-check this with the Apache CMIS Workbench tool. That uses the Documentum CMIS connection layer to have a view in the Repository. Please do a search on this site as it is all explained how to make this work.

First make a connection:

And there it is…The email with separation of the attachment…Tadaaa…It’s magic!

And this gives us a big ‘DONE’ on the mailing feature on AppWorks. Again, great functionality where we make it possible to send out mail and retrieve mail from an external inbox. Also, a great feature that can be used in all of our solutions.

I see you in the next post and keep on learning during our AppWorks journey! Don’t forget to subscribe to get updates on the activities happening on this site.