/ Development  

Cast a spell on your inbox with "receiveEmail"

Hi there “Process Automation” fans,

Welcome to a new installment of “Process Automation” tips.

Sometimes, I observe things in the field that amaze me. It triggers me to ask critical questions, but without a satisfactory answer, it continues to puzzle me. I know that at that point, I require an R&D session to better understand the why and how behind it. This post exposes a topic that everybody around me seems to know (obviously!?) and suddenly you notice it frequently (Baader-Meinhof Phenomenon or Frequency illusion) when examining implementations closely. It has to do with a service call with the name receiveEmail that doesn’t receive anything, but “magically” creates a new mail in your entity instance! The more I think about it, the more questions I get…So, let’s fire away!

Let’s get right into it…

A spectacular introduction with indeed a spectacular post where we’ll provide an answer to a service call receiveEmail everyone seems to know (except for me!?), but first…Check the Email tag where you can do emailbox configurations AND there (yes, my friend!) we already see receiveEmail as solution…even in the documentation (section “Configuring the E-mail connector”)!, but it’s not a best practice to do it like that…apparently, OpenText PS advices differently!? So, why is it documented like this and how do you need to use it!? AND where on earth are those mails saved!?

All valid questions we find an answer for, but first the receiveEmail call itself. As told, we see it in the emailbox configuration for the relative ‘Email service’ container, but we also want to call it directly as next week we’ll do the call from a BPM point of view (receiving a real mail)!

So, boot up the machine, create/open your workspace with relative project, and create a simple one-property ‘Case’ entity with the default building blocks in place…nothing fancy.

Next, add the ‘Email’ BB…STOP!! Is it needed? Let’s just try the service call first from the ‘Web Service Interface Explorer’ artifact:

1
2
3
4
5
6
7
8
9
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
   <receiveEmail xmlns="http://schemas.cordys.com/entity/email/1.0">
    <from>Contact OPA &lt;contact@appworks-tips.com&gt;</from>
    <subject>Hello world...</subject>
    <body>The body we're all been waiting for ;)</body>
   </receiveEmail>
  </SOAP:Body>
 </SOAP:Envelope>

Well, that’s an error:

receive_mail_001

An interesting error because our “subject” seems to miss something magic (✩₊˚.⋆☾⋆⁺₊✧) between [# and ]…#WTF!?

…

Ok, continue with the ‘Case’ entity (no ‘Email’ BB yet!). Make it publishable, and create a new instance in runtime. After opening the instance, copy the ‘ItemId’ from the URL, and update the previous call like this:

1
2
3
4
5
6
7
8
9
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
   <receiveEmail xmlns="http://schemas.cordys.com/entity/email/1.0">
    <from>Contact OPA &lt;contact@appworks-tips.com&gt;</from>
    <subject>Hello [#080027866f6aa1f09cb20694eff2256e.1] world...</subject>
    <body>The body we're all been waiting for ;)</body>
   </receiveEmail>
  </SOAP:Body>
 </SOAP:Envelope>

Again an error: There is no item member with a given name/id com.opentext.cordys.entityCore.elements.emailElement.Email in item 'case' with Id '1'.

In simple words, we need the ‘Email’ BB on our entity AND the ‘Content’ BB to configure it all like this:

receive_mail_002

I also update the layout with the ‘Email’ panel and the ‘Content’ panel, so we verify something in runtime!

Hit the gazzzz again on the service call…YES, “white smoke”! ✅ You can check the runtime entity instance now for a new mail in the inbox:

receive_mail_003

Pay attention…It’s nicely saved on our entity instance, but our body is not visible for some reason!? Well, it was a long struggle to find out, but it must be a Base64 String value of a real email. So, send yourself a simple email (via Gmail for example), download the message (you’ll get a .eml file), and open it with Notepad for an output like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
MIME-Version: 1.0
Date: Wed, 6 Aug 2025 15:40:23 +0200
Message-ID: <CACXZpRjTWD6K52Ai7mZUCUPCoxQKHCGPTy2M0EiGFkXPeFkESw@mail.gmail.com>
Subject: test
From: Antal Bos <antal@bos-ictservices.nl>
To: contact@appworks-tips.com
Content-Type: multipart/alternative; boundary="000000000000f44b62063bb27b6f"

--000000000000f44b62063bb27b6f
Content-Type: text/plain; charset="UTF-8"

The body we're all been waiting for ;)

--000000000000f44b62063bb27b6f
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div>The body we're all been waiting for ;)</div>

--000000000000f44b62063bb27b6f--

When we make a Base64 String from this message here, and paste it into the body-element of the request, you will get a valid body (only the text/html part!)

receive_mail_004

Time for a Q&A

Ok…All nice and great, but this is nasty stuff…agree? It’s for me unclear why to misuse the ‘Subject’ to get a grip on the entity ‘ItemId’. Why not simply add an <itemId>...</itemId> in the request!? Maybe it’s just a legacy we have to deal with, but then at least document it well, so we can all benefit from it as every project uses mail (which is for me still unclear in 2025 for a modern case management system)

Where is the mail saved? That was a research we did before, and with the CMC tool we can move ourselves to this location:

receive_mail_005

So, that’s the XML Data Store location which is not optimal; Use an ECM system like xECM or Documentum; Read here about the options!

Can we find a remote debug entry? Sure, how about the location: %TOMEE_HOME%/webapps/home#app#entityWebService/WEB-INF/classes/com/opentext/cordys/entity/webservices/email/EntityEmail.class. Decompiling this class with IntelliJ tells us it’s simply regEx on the ‘subject’ string:

receive_mail_006

Clearly legacy! #SUPPORT for adding the ItemId as separate input element.

Another observation is this part in the code:

receive_mail_007

It tells me that you can find <{ItemId}@opentext.com> in the headers of a mail-message! Fascinating…We haven’t seen this yet, but my assumption is that this has to do with the send and reply to the same message. So, sending a message from the OPA platform (you need a mail server and ‘Email service’ container…read here) will add this info to the header of the mail and on reply it will read this information again for the ‘ItemId’!

Finally, how can we do it different in the emailbox-config? A totally valid question, but not to answer in this post…I leave it for next week! 🧐

A best-practice “DONE” with still a valid open question: Why do you want to save mail with your entity instance!? OPA creates case management systems automating processes via a low-code approach; We’re not building a mail archiving system nobody looks at or even can find something in. It’s OK to save history, but do it smartly and wisely in a structured way…E-mail is and will be unstructured data which we need to unravel to structured data. I leave you with this final thought and wish you a great weekend with lots of fun!

Don’t forget to subscribe to get updates on the activities happening on this site. Have you noticed the quiz where you find out if you are also “The Process Automation guy”?