Using ECA to Send Emails When a Field’s Value Changes

The Florida DrupalCamp website (where session submissions are open till December 19th), uses the ECA module to send transactional emails. In part 1 of this series, I walk through using ECA to send an email when a user creates a “session” node. If you’ve not read that article yet, check it out now as it gives a good background of ECA.

In this next article, I’ll walk through the steps of sending confirmation and rejection emails when a field is changed to indicate the session is accepted or rejected. We’ll also display a confirmation message to the user that emails have been sent out.

FLDC site architecture

The Florida DrupalCamp website has a node type called session. Along with the normal expected fields, there’s an optional “Acceptance” field (field_acceptance) that’s a reference to a taxonomy vocabulary where there are two entries: “Accepted”, and “Rejected”.

I have the following ECA related modules installed and enabled:

• eca - this is the core module
• eca_content - this enables ECA to work with content entities (like creation, updating, etc)
• eca_ui - This is a UI to see (but not configure) existing ECA modals.
• bpmn_io - This is the UI to create and configure models

Where we’re going

To give you an idea of where we’re ending up, here’s a screenshot of the final model within ECA.

1. Navigate to ECA

The first step is to navigate to Admin > Configuration > Workflow > ECA. You’ll see a list of your current models (below we see the one that we create in step 1 of this series). Click on the “Add new model” button at the top right and then give the model a name (we name this "Send email on acceptance / rejection").

2. Create the start event

To start, we need to create an event to trigger the ECA workflow.

1. Drag the “Create Start Event” circle from the left toolbar to the canvas.
2. Within the properties pane on the right hand side, click the “Select” button within the “Template” section.
3. A modal appears. Choose the option for “Update content entity”.
4. Change the type of this entity to “Content: Session” (“Session” is the name of our content type that updating will trigger this model).
5. Give this event a name. We call ours, “Session is updated”.

3. Append the “Load original entity” task

The next step is that we need to load the entity without its modified fields. We’ll then give this entity a token name so we can reference it later.

1. Click the start event circle. You’ll see some icons appear to the right of it. Click the rounded rectangle “Append task” icon, which inserts a task.
2. Label the task “Load original entity”.
3. In the “Template” section, Click the “Select” button and choose “Entity: load”.
4. In the “Custom properties” section, change the “Name of token” field to originalentity. We’ll be referencing this later, so watch for typos!
5. Near the bottom, change the option for “Load unchanged values” to yes.

4. Append another task: “Load new values”

We also need another task to load the entity with its new values (so we can compare). We’ll chain this task off of the previous one.

* Note that I'm being explicit very here. While graciously reviewing this, maintainer Jürgen Haas noted that this step is not necessary, because the event already provides that token automatically. 

1. Click the “Load original entity” task. You’ll see some icons appear to the right of it. Click the rounded rectangle “Append task” icon, which inserts another task.
2. Label the task “Load new values”.
3. In the “Template” section, Click the “Select” button and choose “Entity: load”.
4. In the “Custom properties” section, change the “Name of token” field to updatedentity. Once again, we’ll be referencing this later, so watch for typos!
5. Near the bottom, we do not modify the “Load unchanged values” dropdown.

5. Create conditional to only proceed to “Load new values” if the acceptance field is empty

We only want to send an email if the acceptance field has not yet been set, this will prevent emails from going out if we update other fields. To do this, we create a conditional.

1. Select on the arrow that goes from the “Load original entity” task to the “Load new values” task. This will bring a “Sequence flow” property pane to the right.
2. In the “Template” section, Click the “Select” button and choose “Entity: field value is empty”.
3. Label the condition, “Check if acceptance is empty”.
4. Within the “Field name” field, enter the machine name of the field you want to check. For FLDC it’s field_acceptance.
5. Within the “Entity” field, we enter in the token that we created for the original entity’s values, originalentity. Once again, no typos!

6. Append task: “Send acceptance email”

The next step is to create the task that will actually send the email!

1. Click the “Load new values” task. You’ll see some icons appear to the right of it. Click the rounded rectangle “Append task” icon, which inserts another task.
2. Label the task “Send acceptance email”.
3. In the “Template” section, Click the “Select” button and choose “Send email”.
4. Insert either an email address or a token representing an email address into the “Recipient email address” field. I use the [node:author:mail] token to represent the author of the session node. Note that I can specify the previously created entity tokens here, but do not need to because this node token is taken from the event. 
5. Fill out the “Subject” and “Message” fields. Note you can also use tokens here.

7. Create conditional to only proceed if the acceptance field is set to “Accepted”

Before we send the acceptance email, we obviously need to check that the field_acceptance field is set to “Accepted”. To do this, we need to check that the value is set to 46, which is the ID of the “Accepted” taxonomy term that I created.

1. Select on the arrow that goes from the “Load new values” task to the “Send acceptance email” task. This will bring a “Sequence flow” property pane to the right.
2. Label the condition, “Check if acceptance is is accepted”.
3. In the “Template” section, Click the “Select” button and choose “Entity: compare field value”.
4. Within the “Field name” field, enter the machine name of the field you want to check. For us it’s field_acceptance.
5. For the “Expected field value” field, set the value to the value you’re expecting. For FLDC, we’re expecting 46, which is the ID of the “Accepted” taxonomy term that we created.
6. Within the “Entity” field, we enter in the token that we created for the original entity’s values, updatedentity. Be sure no typos!

8. Append a new task to show “Emails sent” message to the user

After the emails are sent, we want to let the admin know that action happened. To do this we display a message.

1. Click the “Send acceptance email” task. You’ll see some icons appear to the right of it. Click the rounded rectangle “Append task” icon, which inserts another task.
2. Label the task “Display message to user”.
3. In the “Template” section, Click the “Select” button and choose “Display a message to user”.
4. Within the “Message” field, Enter the message that you want to display.

9. Create alternate workflow to send rejection emails and show message

The “Accepted” emails are now going out!

Let's do this again for rejection emails by replicating steps 6-8.

1. Same as before, we click the “Load new values” task. You’ll see some icons appear to the right of it. Click the rounded rectangle “Append task” icon, which inserts another task.
2. Label the task “Send rejection email”.
3. With your mouse, grab the starting point of the arrow that is splitting off from the “Check if acceptance is accepted” arrow. Drag it to the bottom of the “Load new values” task.
4. Select the “Send rejection email” task that you just created.
5. In the “Template” section, Click the “Select” button and choose “Send email”
6. Insert either an email address or a token representing an email address into the “Recipient email address” field. I use the [node:author:mail] token to represent the author of the session node.
7. Fill out the “Subject” and “Message” fields. Note you can also use tokens here.
8. Select the arrow that goes from the “Load new values” task to the “Send rejection email” task. This will bring a “Sequence flow” property pane to the right.
9. Label the condition, “Check if acceptance is is rejected”
10. In the “Template” section, Click the “Select” button and choose “Entity: compare field value”
11. Within the “Field name” field, enter the machine name of the field you want to check. For us it’s field_acceptance.
12. For the “Expected field value” field, set the value to the value you’re expecting. We’re expecting 47, which is the ID of the “Rejected” taxonomy term that we created.
13. Once again, within the “Entity” field, we enter in the token that we created for the original entity’s values, updatedentity.
14. Click the “Send rejection email” task. You’ll see some icons appear to the right of it. Click the rounded rectangle “Append task” icon, which inserts another task.
15. Label the task “Display message to user”
16. In the “Template” section, Click the “Select” button and choose “Display a message to user”
17. Within the “Message” field, Enter the message that you want to display.

We’re done!

And with that, we have a completely functional system to send transactional emails without any custom code!

Image

Image

As you’ve seen, barely scratching the surface of what the ECA module can do. But hopefully with this tutorial, you can see how its interface works, and imagine the possibilities!