Camunda: 把邮件扩展集成到业务过程管理中

https://github.com/camunda/ca...

在业务过程系统中集成邮件服务.

功能

• 发送邮件

• 收取邮件

• 删除邮件

• 收到邮件时, 执行操作

安装

要求

• Camunda BPM >= 7.50

• Java 8

对于嵌入式过程引擎

添加 camunda-bpm-mail-core 作为应用程序依赖. 如果使用Maven, 需要添加如下依赖到 pom.xml 文件中:

<dependency>
  <groupId>org.camunda.bpm.extension</groupId>
  <artifactId>camunda-bpm-mail-core</artifactId>
  <version>1.1.0</version>
</dependency>

对于共享过程引擎

添加 camunda-bpm-mail-core-1.1.0.jar 到服务器的 lib 目录中, 比如 apache-tomcat-8.0.24\lib. 还要保证包括下面的依赖:

• camunda-connect-core >= 1.0.3

• JavaMail >= 1.5.5

• slf4j-api >= 1.7.21

如果使用 Wildfly, 参考这个特殊说明

如何使用

该扩展构建与 Connectors API 基础上, 并且提供了一些用于连接到邮件服务器的连接器. 连接可以作为一个服务任务实现用于一个过程当中, 并且通过ID进行引用. 然后使用 Camunda Modeler 来配置:

<serviceTask id="sendMail" name="Send Mail Task">
  <extensionElements>
    <camunda:connector>
      <camunda:connectorId>mail-send</camunda:connectorId>
      <!-- input / output mapping -->
    </camunda:connector>
  </extensionElements>
</serviceTask>

查看 连接器用户指南 以了解如何配置过程引擎来使用连接器

发送邮件

连接器ID: mail-send

输入参数	类型	是否要求
from	String	NO(从配置读取)
fromAlias	String	NO(从配置读取)
to	String	Yes
cc	String	NO
bcc	String	No
subject	String	Yes
text	String	No
html	String	No
fileNames	字符串列表 (文件路径)	Yes

邮件内容可以使HTML或者纯文本, 并且可以通过模板生成(比如, 使用 FreeMarkeer 模板, 可以参考 这个例子)

收取邮件

输入参数	类型	是否要求
folder	String(比如: 'Inbox'	NO(从配置读取)
download-attachements	Boolean	NO(从配置读取)

输出参数	类型
mails	Mail 类型列表

如果 download-attachements 为 true, 那么存储附件到配置中指定的位置. 存储附件的路径可以通过 Mail 的 Attachment 中获取

删除邮件

输入参数	类型	是否要求
folder	String(例如: 'Inbox')	NO(从配置读取)
mails	Mail 列表	NO
messageIds	字符串列表	NO
messageNumbers	整数列表	NO

mails, messageIds 或 messageNumbers 必须设置.

收取邮件后的自动化操作

该扩展使用 MailNotificationService 来对收取的邮件做响应操作(例如, 启动一个过程示例, 或关联一个消息) 你可以注册处理器/消费者, 当收到一个新的邮件时, 来处理这个邮件. 下面给出一个Java的实际代码例子:

MailNotificationService notificationService = new MailNotificationService(configuration);

notificationService.registerMailHandler(mail -> {
  runtimeService.startProcessInstanceByKey("process",
    Variables.createVariables().putValue("mail", mail));
});

notificationService.start();

// ...

notificationService.stop();

如果使用了一个邮件处理器, 并且在配置中启用了 downloadAttachments, 那么在调用对应的处理器的时候首先存储附件. 另外, 还可以通过调用 Mail.downloadAttachments() 触发手动下载.

如何配置

默认情况, 扩展会从CLASSPATH中查找一个名为mail-config.properties的配置文件. 你可以使用环境变量 MAIL_CONFIG 来修改查找路径. 如果你想在CLASSPATH中查找一个文件, 使用classpath 前缀. (例如: classpath:/my-application.config)

下面是一个配置示例:

# send mails via SMTP
mail.transport.protocol=smtp

mail.smtp.host=smtp.gmail.com
mail.smtp.port=465
mail.smtp.auth=true
mail.smtp.ssl.enable=true
mail.smtp.socketFactory.port=465
mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory

# poll mails via IMAPS
mail.store.protocol=imaps

mail.imaps.host=imap.gmail.com
mail.imaps.port=993
mail.imaps.timeout=10000

# additional config
mail.poll.folder=INBOX
mail.sender=[e-mail]
mail.sender.alias=User Inc

mail.attachment.download=true
mail.attachment.path=attachments

# credentials
mail.user=[e-mail]
mail.password=PASSWORD

可以在 extension/core/configs 找到一些配置示例. 如果使用没有配置的邮件供应商, 你也可以添加自己的. 可以通过 集成测试 来校验你的配置.

例子

下面的例子展示了如何使用连接器和服务.

• 披萨订单

  • 收取邮件

  • 发送纯文本邮件

  • 删除邮件

• 打印服务

  • 使用 MailNotificationService

  • 发送带附件的邮件

• 任务分配邮件例子

常见问题

• JavaMail 项目文档

• Oracle JavaMail 常见问题

• 关于使用 Gmail 发送邮件的问题

• 注意 javamail 的版本, 最好用比较新的

参考资料

• 把邮件服务集成到业务过程中

• 当一个用户任务被分配给具体的人, 或一个组时如何发送一个通知邮件

• 如何通过 Camunda 发送邮件