ในบทช่วยสอนนี้ เราจะทำตาม guideline for developing a plugin เพื่อพัฒนาปลั๊กอิน Slack Notification ของเรา โปรดอ้างอิงถึงบทช่วยสอน วิธีการพัฒนา Bean Shell Hash Variable สำหรับรายละเอียดเพิ่มเดิมขั้นต่อไป
1. ปัญหาคืออะไร?
เราต้องการส่งข้อความถึง Slack เพื่อแจ้งเตือนผู้ใช้เมื่อมีการมอบหมายงานที่สร้างขึ้นสำหรับพวกเขาใน Joget Workflow
2. วิธีแก้ปัญหา?
เราจะพัฒนาปลั๊กอิน Audit Trail Plugin เพื่อส่งข้อความถึง Slack.
3. อินพุตที่จำเป็นสำหรับปลั๊กอินของคุณคืออะไร?
ในการพัฒนาปลั๊กอินการแจ้งเตือน Slack เราจะพิจารณาให้ตัวเลือกคุณสมบัติที่คล้ายกับปลั๊กอิน User Notification.
4. ผลลัพธ์และผลลัพธ์ที่คาดหวังจากปลั๊กอินของคุณคืออะไร?
เมื่อมีการสร้างการมอบหมายสำหรับผู้ใช้ข้อความที่มีลิงค์การมอบหมายจะส่งไปยังบัญชี Slack ของตนตามการกำหนดค่า
5. มีทรัพยากร / API ที่สามารถนำกลับมาใช้ใหม่ได้หรือไม่?
เราสามารถใช้ slack-webhook library เพื่อรวมกับ Slack และเรายังสามารถขยาย org.joget.apps.app.lib.UserNotificationAuditTrail เพื่อประหยัดเวลาของเราในการใช้วิธีการที่คล้ายกันอีกครั้ง
6. เตรียม environment สำหรับการพัฒนา
เราจำเป็นต้องให้ซอร์สโค้ด Joget Workflow ของเราพร้อมและสร้างโดยทำตาม this guideline.
บทช่วยสอนนี้จัดทำขึ้นโดย Macbook Pro และ the Joget Source Code is version 5.0.1. โปรดอ้างอิงถึง แนวทางสำหรับการพัฒนาปลั๊กอิน สำหรับคำสั่งแพลตฟอร์มอื่น ๆ
สมมติว่าไดเรกทอรีโฟลเดอร์ของเรามีดังนี้
- Home
- joget
- plugins
- jw-community
-5.0.1
ไดเรกทอรี "ปลั๊กอิน" คือโฟลเดอร์ที่เราจะสร้างและจัดเก็บปลั๊กอินของเราทั้งหมดและไดเรกทอรี "jw-community" เป็นที่เก็บซอร์สโค้ด Joget Workflow
เรียกใช้คำสั่งต่อไปนี้เพื่อสร้างโครงการ maven ในไดเรกทอรี "ปลั๊กอิน"
cd joget/plugins/ ~/joget/jw-community/5.0.1/wflow-plugin-archetype/create-plugin.sh org.joget slack_notification 5.0.1
จากนั้นเชลล์สคริปต์จะขอให้เราใส่หมายเลขเวอร์ชันสำหรับปลั๊กอินและขอให้เรายืนยันก่อนที่จะสร้างโครงการ Maven
Define value for property 'version': 1.0-SNAPSHOT: : 5.0.0 [INFO] Using property: package = org.joget Confirm properties configuration: groupId: org.joget artifactId: slack_notification version: 5.0.0 package: org.joget Y: : y
เราควรได้รับข้อความ "BUILD SUCCESS" ที่แสดงในเครื่องของเราและโฟลเดอร์ "slack_notification" ที่สร้างขึ้นในโฟลเดอร์ "ปลั๊กอิน"
เปิดโครงการ maven ด้วย IDE ที่คุณชื่นชอบ เราแนะนำให้ใช้ NetBeans.
7. เริ่มโค้ด!
a. ขยาย abstract class สำหรับประเภทปลั๊กอิน
สร้างคลาส "SlackNotification" ภายใต้ "org.joget" package. จากนั้นขยายคลาสด้วย org.joget.apps.app.lib.UserNotificationAuditTrail ซึ่งขยาย org.joget.plugin.base.DefaultAuditTrailPlugin abstract class. โปรดอ้างอิงถึง Audit Trail Plugin. เราจะต้องดำเนินการ org.joget.plugin.base.PluginWebSupport ระดับอินเตอร์เฟซเช่นกันเพื่อให้ส่งข้อความทดสอบปุ่มในหน้าคุณสมบัติปลั๊กอิน โปรดอ้างอิงถึง Web Service Plugin.
b. การดำเนินการทั้งหมดของ abstract methods
ตามปกติเราต้องใช้วิธีนามธรรมทั้งหมด เราจะใช้วิธี AppPluginUtil.getMessage เพื่อสนับสนุน i18n และการใช้ตัวแปร MESSAGE_PATH คงที่สำหรับ message resource bundle directory.
ตอนนี้เราต้องสร้าง UI สำหรับผู้ใช้ผู้ดูแลระบบเพื่อให้อินพุตสำหรับปลั๊กอินของเรา. ในวิธีการ getPropertyOptions เราได้ระบุไฟล์ ตัวเลือกคุณสมบัติปลั๊กอิน ไว้ที่ "/properties/slackNotification.json". ให้สร้าง directory "resources/properties" ภายใต้ "slack_notification/src/main" directory. หลังจากสร้าง directory, สร้างไฟล์ชื่อ "slackNotification.json" ในโฟลเดอร์ "properties"
ในไฟล์ตัวเลือกคุณสมบัติ เราจะต้องกำหนดตัวเลือกดังต่อไปนี้ โปรดทราบว่าเราสามารถใช้ "@@message.key@@" syntax เพื่อสนับสนุน i18n ในตัวเลือกคุณสมบัติ. ที่นี่เราสามารถคัดลอกตัวเลือกคุณสมบัติของปลั๊กอินการแจ้งเตือนผู้ใช้และแก้ไขจากที่นั่น โปรดอ้างอิงถึง userNotificationAuditTrail.json.
[{
title : '@@SlackNotification.config@@',
properties : [
{
name : 'apiurl',
label : '@@SlackNotification.url@@',
type : 'textfield',
required : 'true'
},
{
label : '@@SlackNotification.from@@',
type : 'header'
},
{
name : 'username',
label : '@@SlackNotification.fromUsername@@',
type : 'textfield',
value : '@@SlackNotification.fromUsername.value@@'
},
{
name : 'customIcon',
label : '@@SlackNotification.customIcon@@',
type : 'selectbox',
value : 'joget',
options : [{
value : '',
label : '@@SlackNotification.customIcon.none@@'
},
{
value : 'joget',
label : '@@SlackNotification.customIcon.joget@@'
},
{
value : 'url',
label : '@@SlackNotification.customIcon.url@@'
},
{
value : 'emoji',
label : '@@SlackNotification.customIcon.emoji@@'
}]
},
{
name : 'iconUrl',
label : '@@SlackNotification.customIcon.url@@',
type : 'textfield',
required : 'true',
control_field: 'customIcon',
control_value: 'url',
control_use_regex: 'false'
},
{
name : 'iconEmoji',
label : '@@SlackNotification.customIcon.emoji@@',
type : 'textfield',
required : 'true',
control_field: 'customIcon',
control_value: 'emoji',
control_use_regex: 'false'
},
{
label : '@@SlackNotification.to@@',
type : 'header'
},
{
name : 'usernameTransform',
label : '@@SlackNotification.usernameTransform@@',
description : '@@SlackNotification.usernameTransform.desc@@',
type : 'textfield',
value : '@@SlackNotification.usernameTransform.value@@',
required : 'True'
},
{
label : '@@SlackNotification.message@@',
type : 'header'
},
{
name : 'text',
label : '@@SlackNotification.text@@',
description : '@@SlackNotification.text.desc@@',
type : 'codeeditor',
required : 'True'
},
{
name : 'unfurl_links',
label : '@@SlackNotification.unfurl_links@@',
description : '@@SlackNotification.unfurl_links.desc@@',
type : 'checkbox',
value : 'true',
options : [{
value : 'true',
label : ''
}]
},
{
name : 'unfurl_media',
label : '@@SlackNotification.unfurl_media@@',
description : '@@SlackNotification.unfurl_media.desc@@',
type : 'checkbox',
value : 'true',
options : [{
value : 'true',
label : ''
}]
}],
buttons : [{
name : 'sendTestMessage',
label : '@@SlackNotification.sendTestMessage@@',
ajax_url : '[CONTEXT_PATH]/web/json/app[APP_PATH]/plugin/org.joget.SlackNotification/service?action=sendTestMessage',
fields : ['url'],
addition_fields : [
{
name : 'testChannel',
label : '@@SlackNotification.sendTestMessage.testChannel@@',
type : 'textfield'
}
]
}]
},
{
title : '@@app.usernotificationaudittrail.notificationLink@@',
properties : [
{
name : 'base',
label : '@@app.usernotificationaudittrail.baseUrl@@',
type : 'textfield',
description : '@@app.usernotificationaudittrail.baseUrl.desc@@',
required : 'True'
},
{
name : 'url',
label : '@@app.usernotificationaudittrail.url@@',
type : 'textfield'
},
{
name : 'urlName',
label : '@@app.usernotificationaudittrail.urlName@@',
type : 'textfield'
},
{
name : 'parameterName',
label : '@@app.usernotificationaudittrail.parameterName@@',
description : '@@app.usernotificationaudittrail.parameterName.desc@@',
type : 'textfield',
value : 'activityId'
},
{
name : 'passoverMethod',
label : '@@app.usernotificationaudittrail.passoverMethod@@',
type : 'selectbox',
value : 'param',
options : [{
value : 'none',
label : '@@app.usernotificationaudittrail.passoverMethod.none@@'
},
{
value : 'append',
label : '@@app.usernotificationaudittrail.passoverMethod.append@@'
},
{
value : 'param',
label : '@@app.usernotificationaudittrail.passoverMethod.param@@'
}]
}]
},
{
title : '@@app.usernotificationaudittrail.advanced@@',
properties : [{
name : 'exclusion',
label : '@@app.usernotificationaudittrail.activityExclusion@@',
type : 'multiselect',
size : '10',
options_ajax : '[CONTEXT_PATH]/web/json/app[APP_PATH]/plugin/org.joget.apps.app.lib.UserNotificationAuditTrail/service?action=getActivities'
}]
}]
หลังจากเสร็จสิ้นตัวเลือกคุณสมบัติเพื่อรวบรวมอินพุตเราสามารถทำงานกับวิธีการหลักของปลั๊กอินซึ่งเป็นวิธีการดำเนินการ แต่เนื่องจากเราขยายคลาส UserNotificationAuditTrail เราเพียงต้องการแทนที่เมธอด sendEmail ที่ใช้ในการส่งอีเมลโดยคลาส UserNotificationAuditTrail
private SlackApi api = null;
@Override
protected void sendEmail (final Map props, final AuditTrail auditTrail, final WorkflowManager workflowManager, final List<String> users, final WorkflowActivity wfActivity) {
new PluginThread(new Runnable() {
public void run() {
WorkflowUserManager workflowUserManager = (WorkflowUserManager) AppUtil.getApplicationContext().getBean("workflowUserManager");
String base = (String) props.get("base");
String url = (String) props.get("url");
String urlName = (String) props.get("urlName");
String parameterName = (String) props.get("parameterName");
String passoverMethod = (String) props.get("passoverMethod");
String text = (String) props.get("text");
String linkLabel = AppPluginUtil.getMessage("SlackNotification.viewAssignment", getClassName(), MESSAGE_PATH);
String activityInstanceId = wfActivity.getId();
String link = getLink(base, url, passoverMethod, parameterName, activityInstanceId);
if (!link.startsWith("http")) {
if (!link.startsWith("/")) {
link = "/" + link;
}
link = base + link;
}
SlackMessage message = createMessage();
try {
for (String username : users) {
workflowUserManager.setCurrentThreadUser(username);
WorkflowAssignment wfAssignment = null;
int count = 0;
do {
wfAssignment = workflowManager.getAssignment(activityInstanceId);
if (wfAssignment == null) {
Thread.sleep(4000); //wait for assignment creation
}
count++;
} while (wfAssignment == null && count < 5); // try max 5 times
if (wfAssignment != null) {
String channel = getSlackUsername(username, wfAssignment);
if (channel != null && !channel.isEmpty()) {
message.setText(AppUtil.processHashVariable(text, wfAssignment, null, null));
message.setAttachments(new ArrayList<SlackAttachment>());
SlackAttachment attachment = new SlackAttachment();
attachment.setFallback(link);
if (urlName != null && !urlName.isEmpty()) {
attachment.setTitle(AppUtil.processHashVariable(urlName, wfAssignment, null, null));
} else {
attachment.setTitle(linkLabel);
}
attachment.setTitleLink(link);
message.addAttachments(attachment);
try {
LogUtil.info(SlackNotification.class.getName(), "Sending slack message to " + username);
sendMessage(channel, message);
LogUtil.info(SlackNotification.class.getName(), "Sending slack message completed to " + username);
} catch (Exception ex) {
LogUtil.error(UserNotificationAuditTrail.class.getName(), ex, "Error sending slack message");
}
}
} else {
LogUtil.debug(UserNotificationAuditTrail.class.getName(), "Fail to retrieve assignment for " + username);
}
}
} catch (Exception e) {
LogUtil.error(UserNotificationAuditTrail.class.getName(), e, "Error executing plugin");
}
}
}).start();
}
protected SlackApi getApi() {
if (api == null) {
api = new SlackApi(getPropertyString("apiurl"));
}
return api;
}
protected String getSlackUsername(String username, WorkflowAssignment assignment) {
String syntax = getPropertyString("usernameTransform");
syntax = syntax.replaceAll(StringUtil.escapeRegex("{username}"), StringUtil.escapeRegex(username));
return AppUtil.processHashVariable(syntax, assignment, null, null);
}
protected void sendMessage(String channel, SlackMessage message) {
if (message == null) {
message = createMessage();
}
if (channel != null && !channel.isEmpty()) {
message.setChannel(channel);
}
getApi().call(message);
}
protected SlackMessage createMessage() {
SlackMessage message = new SlackMessage();
String username = getPropertyString("username");
if (!username.isEmpty()) {
message.setUsername(username);
}
String customIcon = getPropertyString("customIcon");
if (!customIcon.isEmpty()) {
if ("joget".equals(customIcon)) {
HttpServletRequest request = WorkflowUtil.getHttpServletRequest();
if (request != null) {
String url = request.getScheme() + "://" + request.getServerName() + ":" + request.getServerPort() + request.getContextPath() + "/images/v3/logo.png";
message.setIcon(url);
}
} else if ("url".equals(customIcon)) {
message.setIcon(getPropertyString("iconUrl"));
} else {
message.setIcon(getPropertyString("iconEmoji"));
}
}
message.setUnfurlLinks("true".equalsIgnoreCase(getPropertyString("unfurl_links")));
message.setUnfurlMedia("true".equalsIgnoreCase(getPropertyString("unfurl_media")));
return message;
}
ในคุณสมบัติปลั๊กอินของเราเรามีปุ่มสำหรับส่งข้อความทดสอบ ให้ใช้วิธีการ webService เพื่อจัดทำ API เพื่อส่งข้อความทดสอบ
public void webService(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
boolean isAdmin = WorkflowUtil.isCurrentUserInRole(WorkflowUserManager.ROLE_ADMIN);
if (!isAdmin) {
response.sendError(HttpServletResponse.SC_UNAUTHORIZED);
return;
}
String action = request.getParameter("action");
if ("sendTestMessage".equals(action)) {
String message = "";
try {
AppDefinition appDef = AppUtil.getCurrentAppDefinition();
String url = AppUtil.processHashVariable(request.getParameter("url"), null, null, null, appDef);
String testChannel = AppUtil.processHashVariable(request.getParameter("testChannel"), null, null, null, appDef);
setProperty("apiurl", url);
setProperty("text", AppPluginUtil.getMessage("SlackWebhookTool.testMessage", getClassName(), MESSAGE_PATH));
if (testChannel != null && !testChannel.isEmpty()) {
sendMessage(testChannel, null);
} else {
sendMessage(null, null);
}
message = AppPluginUtil.getMessage("SlackWebhookTool.sendTestMessage.success", getClassName(), MESSAGE_PATH);
} catch (Exception e) {
LogUtil.error(this.getClassName(), e, "Fail to send Test Message to Slack");
message = AppPluginUtil.getMessage("SlackWebhookTool.sendTestMessage.fail", getClassName(), MESSAGE_PATH) + "\n" + StringEscapeUtils.escapeJavaScript(e.getMessage());
}
try {
JSONObject jsonObject = new JSONObject();
jsonObject.accumulate("message", message);
jsonObject.write(response.getWriter());
} catch (Exception e) {
//ignore
}
} else {
response.setStatus(HttpServletResponse.SC_NO_CONTENT);
}
}
c. จัดการ dependency libraries สำหรับปลั๊กอินของคุณ
เราจำเป็นต้องรวมไลบรารี "jsp-api" และ "slack-webhook" ไว้ในไฟล์ POM ของเรา
<!-- Change plugin specific dependencies here -->
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>jsp-api</artifactId>
<version>2.0</version>
</dependency>
<dependency>
<groupId>net.gpedro.integrations.slack</groupId>
<artifactId>slack-webhook</artifactId>
<version>1.1.1</version>
</dependency>
<!-- End change plugin specific dependencies here -->
d. จัดการปลั๊กอิน internationalization (i18n) ของคุณให้พร้อม
รากำลังใช้คีย์ข้อความ i18n ในวิธี getLabel และ getDescription เราจะใช้คีย์ข้อความ i18n ในการกำหนดตัวเลือกคุณสมบัติของเราเช่นกัน จากนั้นเราจะต้องสร้างไฟล์คุณสมบัติมัดทรัพยากรสำหรับปลั๊กอินของเรา
สร้าง directory, "resources/message", ภายใต้ "slack_webhook/src/main" directory. จากนั้นสร้างไฟล์ "SlackWebhookTool.properties" ในโฟลเดอร์. In the properties file, add all the message keys and its label as below.
org.joget.SlackNotification.pluginLabel=Slack Notification
org.joget.SlackNotification.pluginDesc=Send notification message to Slack user when an assignment is available.
SlackNotification.config=Configure Slack Notification
SlackNotification.url=Webhook URL
SlackNotification.from=From
SlackNotification.fromUsername=Username
SlackNotification.fromUsername.value=Joget Workflow
SlackNotification.customIcon=Custom Icon
SlackNotification.customIcon.none=None
SlackNotification.customIcon.joget=Joget Workflow Logo
SlackNotification.customIcon.url=Image URL
SlackNotification.customIcon.emoji=Emoji Code
SlackNotification.to=To
SlackNotification.usernameTransform=Transform username to Slack username
SlackNotification.usernameTransform.desc=Hash Variable can be used to transform username to Slack username. Eg. @#form.slack.username[{username}]#
SlackNotification.usernameTransform.value=@{username}
SlackNotification.message=Message
SlackNotification.text=Text
SlackNotification.text.desc=Refer to <a href="https://api.slack.com/docs/formatting" target="_blank">Slack Message Formatting</a>.
SlackNotification.unfurl_links=Unfurling Links
SlackNotification.unfurl_links.desc=Automatically find URLs in a message and create attachments based on the content of those URLs
SlackNotification.unfurl_media=Unfurling Media
SlackNotification.unfurl_media.desc=Automatically find Media URLs in a message and create attachments based on the media of those URLs
SlackNotification.sendTestMessage=Send Test Message
SlackNotification.sendTestMessage.testChannel=Test Channel
SlackNotification.sendTestMessage.success=Test message sent.
SlackNotification.sendTestMessage.fail=Fail to sent test message. Error:
SlackNotification.testMessage=Test Message
SlackNotification.viewAssignment=View Assignment
e. Register your plugin to the Felix Framework
Next, we will have to register our plugin class in the Activator class (Auto generated in the same class package) to tell the Felix Framework that this is a plugin.
public void start(BundleContext context) {
registrationList = new ArrayList<ServiceRegistration>();
//Register plugin here
registrationList.add(context.registerService(SlackNotification.class.getName(), new SlackNotification(), null));
}
f. Build it and test
Let's build our plugin. Once the building process is done, we will find a "slack_notification-5.0.0.jar" file created under "slack_notification/target" directory.
Then, let's upload the plugin jar to Manage Plugins. After uploading the jar file, double check that the plugin is uploaded and activated correctly.
Check the Slack Notification plugin is available in Plugin Default Properties.
Now, let us configure the Incoming Webhooks in Slack platform.
- Go to your_team.slack.com/services/new.
- Search for Incoming WebHook and click in
Add - Choose Channel to Post and press
Add Incoming WebHooks Integration - Into Setup Instructions, you've a WebHook URL. This is the argument will use for the "Webhook URL" later. Then, copy it.
Configure the Slack Notification plugin. We can see the properties options are quite similar to User Notification plugin.
When test running a process, the message is received in Slack once a new assignment is created.
8. Take a step further, share it or sell it
You can download the source code from slack_notification_src.zip.
To download the ready-to-use plugin jar, please find it in http://marketplace.joget.org/. (Coming Soon)