Axon Ivy 12:replacement for MailNotification_NewTask.ivp trigger

ypetrov

Hello Axon Ivy team . We are migrating to Axon Ivy 12 and previously used MailNotification_NewTask.ivp as a hook to run custom logic when a new task was created/assigned.

From the migration notes, this old mail notification approach seems to be removed and replaced by the new notification/template system. Our issue is that we do not just need to change mail content — we need to trigger a process or custom logic on new task creation.

What is the official replacement for this in Axon Ivy 12?

Is there a supported way to:

react to new task creation/assignment,

run custom code or start a process,

and replace what we previously did via MailNotification_NewTask.ivp?

Would the recommended solution be workflow system events like TASK_CREATED / TASK_CHANGED, or should this now be handled explicitly in the business process where the task is created?

Lukas Giger

Hi ypetrov ,

Yes, either use system events or implement the desired behavior explicitly in your processes using subprocesses, signals, or any other workflow design you see fit.

The best approach depends on your exact use case.
If you want to react to pretty much all task creations, for example, using the respective system event is probably the best fit. If you only want to react to a few selected task creations, a custom implementation might be more manageable.

Kind regards,
Lukas

Lukas

Hi @Lukas Giger
Can you give us an example on how this would look like? Or how the system events could be modified?

The approach suggested by you would mean adding a custom mail call for all process steps?

Kind Regards
Lukas Z.

Lukas Giger

Hi Lukas ,

I threw together a quick demo on how an implementation using system events could look like.

Implement an AbstractProcessStartEventBean you can use with a Program Start element. The start event bean creates and registers an ISystemEventListener which starts the process whenever the system event is triggered.

The SystemEvent instance received by the listener comes with parameters you can pass to the process as needed. For example, a system event of type WorkflowSystemEvent#TASK_CREATED provides the task IDs of the tasks created that triggered the event. You can use them to get and manipulate the tasks, for example.

package system.events.demo;

import java.util.EnumSet;
import java.util.List;

import ch.ivyteam.ivy.event.ISystemEventListener;
import ch.ivyteam.ivy.event.SystemEvent;
import ch.ivyteam.ivy.event.SystemEventCategory;
import ch.ivyteam.ivy.process.eventstart.AbstractProcessStartEventBean;
import ch.ivyteam.ivy.process.eventstart.IProcessStartEventBeanRuntime;
import ch.ivyteam.ivy.process.extension.ProgramConfig;
import ch.ivyteam.ivy.service.ServiceException;
import ch.ivyteam.ivy.workflow.WorkflowSystemEvent;
import ch.ivyteam.ivy.workflow.WorkflowSystemEventParameter;

public class TaskCreatedListenerBean extends AbstractProcessStartEventBean {

  private TaskCreatedListener listener;

  public TaskCreatedListenerBean() {
    super("TaskCreatedListenerBean", "Listens for task creation events across all PMVs");
  }

  @Override
  public void initialize(IProcessStartEventBeanRuntime eventRuntime, ProgramConfig programConfig) {
    super.initialize(eventRuntime, programConfig);
    // Disable polling as we don't need it. Otherwise, the process will be started every minute by default.
    eventRuntime.poll().disable();
  }

  @Override
  public void start() throws ServiceException {
	// Create and add the system event listener to the application when the bean is started.
    super.start();
    var eventRuntime = getEventBeanRuntime();
    this.listener = new TaskCreatedListener(eventRuntime);
    eventRuntime.getProcessModelVersion().getApplication()
        .addSystemEventListener(EnumSet.of(SystemEventCategory.WORKFLOW), this.listener);
  }

  @Override
  public void stop() throws ServiceException {
	// Don't forget to remove the listener when the bean is stopped.
    getEventBeanRuntime().getProcessModelVersion().getApplication()
        .removeSystemEventListener(EnumSet.of(SystemEventCategory.WORKFLOW), this.listener);
    super.stop();
  }

  private static class TaskCreatedListener implements ISystemEventListener {

    IProcessStartEventBeanRuntime eventRuntime;

    private TaskCreatedListener(IProcessStartEventBeanRuntime eventRuntime) {
      this.eventRuntime = eventRuntime;
    }

    @Override
    public void handleSystemEvent(SystemEvent<?> event) {
      // The listener starts the process where the Program Start element is used with the bean.
      // The process is only started if the event is of type `WorkflowSystemEvent#TASK_CREATED`
      if (!WorkflowSystemEvent.TASK_CREATED.equals(event.getName())) {
        return;
      }
      // We can get the task IDs from the event parameters and pass them to the process for later use.
      List<Long> taskIds = ((WorkflowSystemEventParameter) event.getParameter()).getIds();
      eventRuntime.processStarter()
          .withReason("Tasks created: " + taskIds)
          .withParameter("taskIds", taskIds)
          .startAsync();
    }
  }
}

Here's a picture of my working setup. The process starts with a Program Start element with the bean configured. The corresponding Data Class has the attribute taskIds which gets automatically mapped via the parameters we provided in the listener (they need to match). In the following script element, I simply log the task ids and you can see in the runtime log on the bottom left, that it works.

{System Events Demo}

Note, however, that this is not a 1 to 1 representation of your past implementation. The process will get triggered on every task creation (e.g. also system tasks) and does not care about whether New Task Mails are sent. New Task Mails could, for example, be suppressed in the configuration of the task itself. You might also need to implement this for the task changed event and maybe check whether the responsibles actually changed to achieve the same behavior as before. Therefore, there might be better approaches to your use case.
If you can give me more information about what you actually want to achieve, I could give my opinion on that. Is your use case actually even tied to the New Task Mails or did you just use that process to execute logic whenever a task was assigned to someone?

The approach suggested by you would mean adding a custom mail call for all process steps?

If I understand correctly, you don't need to do that. The New Task Mails will be sent independently, so no need for a custom mail step. Depending on what you actually want to do, you could, for example, also work with other workflow elements which you might then have to add wherever you want your logic to happen.

Kind regards,
Lukas

costifab

Hi Lukas Giger thanks for efforts and the detailed reply.

Our use case is quite simple, let me try to rephrase it. We have two different implementations to achieve the same goal in multiple projects which is, overriding the task notification logic to send only a single mail for a role assignment.

The different implementations are:

Having a GROUPMAILBOX_NameOfTheRole user in the specific role, if it exists, the task assignment notification shall only be sent there instead of all users of the role
Having a role_mailbox property on the specific role, if it exists, the task assignment notification shall only be sent there instead of all users of the role

There is another use case of the current/old override-implementation:

Sometimes a copy of the new task assignment mail shall be sent to the worker of the previous task

This means, there might be other actions related to task assignments e.g.:

Check whether a task custom field exists for the given task
Setting a task custom field on the given task
Fetching the previous worker of the previous task in the same case

In the end, we are searching for an approach on how to simply hook into the mail notification process without touching all processes (suppressing and adding a mail step) as it was possible before version 12, quite similar as in this post, could obviously be a different approach in the direction of your reply.

Regards
Fabio

Lukas Giger

Hi costifab ,

Sadly, it is not possible anymore to hook into the mail notification process directly as in Axon Ivy 10. The entire framework was rebuilt and is now configuration-based instead of process-based.

If you don't want to touch every process, I think the previously mentioned approach with system events could still be your best choice. You can turn off notifications security context wide per channel (web, mail, Microsoft Teams) and event (new task, business). So, for example, you can turn off New Task mails entirely without having to suppress them individually on every task.
Then, using system events, you can react to any task creation or change and send mails (and perform other logic) however you like (E-Mail Activity, Business Notification API, etc.). Of course, you would have to implement some additional checks to ensure your logic is only executed when necessary (e.g., not on system tasks/when there is no responsible present, on task changes only if the responsible actually changed and the task is in the right state, etc.) to ultimately recreate what you had before.

Kind regards,
Lukas