Joget Workflow v6 Training Slides - 18 - Integrating with External System

All Rights Reserved © Joget Inc
Joget Workflow v6
Integrating with External System
http://facebook.com/jogetworkflow
http://twitter.com/jogetworkflow
Last Revised on Oct 2018

Prerequisites
1. Understand Joget Workflow components in depth and
able to make full use of its components.
2. Avid software developer with vast know-hows of web
application technologies.

Content
1. Introduction
2. JSON API
3. JSON API Authentication
4. JavaScript API
5. Single Sign On (SSO)
6. Embedding Task Inbox into External System
7. Embedding Userview Page in an iFrame
8. SOAP Tool
9. Integrating with External Form

Chapter 1
Introduction

Introduction
• There are various ways to integrate Joget Workflow with
external applications.
• Typically, there are 4 main components and the client
user to be considered about.
1. Joget Workflow Application Server
2. Joget Workflow Database Server
3. External Application Server
4. External Application Database Server
5. Client user

Joget as the Front-end
JogetApp
Server
JogetDB
Server
ExternalApp
Server
External
DBServer
End User
via
Userview
various
means…

External App as the Front-end
JogetApp
Server
JogetDB
Server
ExternalApp
Server
External
DBServer
End User
various
means…

User Directory
• Is User session important?
• How do you want to handle the user session between the
servers (Joget server and external application server)?
End User
Login
App
Server
Joget App
Server

User Directory – Joget as Front-end
• Is the identity of the End User important to the External
App Server?
ExternalApp
Server
User
Directory
JogetApp
Server
End User
Login
SSO?
User Directory
plugin

User Directory – Ext App as Front-end
• Is the identity of the End User important to the Joget App
Server?
JogetApp
Server
User
Directory
ExternalApp
Server
End User
Login
SSO?
User Directory
plugin

Chapter Review
• Understand various ways of integration with Joget
Workflow and external application server.

Chapter 2
JSON API

JSON API
• Joget Workflow provides a comprehensive list of APIs for
Workflow Process related tasks.
• Full list of the APIs can be obtained from
https://dev.joget.org/community/display/KBv6/JSON+API

Sample list of APIs
• web/json/monitoring/running/process/list
• web/json/workflow/currentUsername
• web/json/workflow/assignment/completeWithVariable/(:activityId)
• web/json/workflow/assignment/complete/(:activityId)

web/json/monitoring/running/process/list
• URL: /web/json/monitoring/running/process/list
• Method: HTTP GET/POST
• Description: Retrieve running process list
• Parameters
– packageId - (Optional) package id
– processId - (Optional) process definition id without
version
– processName - (Optional) process name
– version - (Optional) process version
– sort - (Optional) column name to be sorted
– desc - (Optional) Boolean value to determine whether to
sort by ascending or descending order (true equals to
descending)
– start - (Optional) where rows start from
– rows - (Optional) number of rows per page
Sample Result
{
"total":2,
"desc":false,
"sort":"name",
"start":0,
"data":
[
{"id":"3724_mdec_v1002_mdec_wp1",
"serviceLevelMonitor":"<span
class="dot_red"></span>",
"name":"mdec_wp1","state":"open.running",
"due":"Fri Mar 20 14:01:27 SGT 2009",
"startedTime":"Fri Mar 20 13:51:27 SGT
2009","version":"2"},
{"id":"3725_mdec_v1002_mdec_wp1",
"serviceLevelMonitor":"<span
class="dot_red"></span>",
"name":"mdec_wp1",
"state":"open.running",
"due":"Fri Mar 20 14:03:16 SGT 2009",
"startedTime":"Fri Mar 20 13:53:16 SGT 2009",
"version":"2"}
]
}

web/json/workflow/currentUsername
• URL
/web/json/workflow/currentUsername
• Method
HTTP GET/POST
• Description
Get current logged in user's username
• Parameters
– callback - (Optional) a function (in JavaScript) to call back after
invoking this method
Sample Result
{ "username":"admin" }

/web/json/workflow/assignment/
completeWithVariable/(:activityId)
• URL
/web/json/workflow/assignment/completeWithVariable/(:activityId)
• Method HTTP POST
• Description
Set activity variable
Variables can be passed as parameters with the var_ prefix
• Parameters
– callback - (Optional) a function (in JavaScript) to call back after
invoking this method
– activityId - activity id
– var_(workflow variable id) - (Optional) set workflow variable value

/web/json/workflow/assignment/
completeWithVariable/(:activityId)
Sample Result
{
"activityId": "1079_563_crm_process1_approve_proposal", "assignment":
"admin",
"nextActivityId": "1093_563_crm_process1_send_proposal",
"processId": "563_crm_process1",
"status": "completed“
}

Chapter Review
• Understand and able to retrieve the list of available APIs.

Chapter 3
JSON API Authentication

Using JSON API
• Can be called using AJAX call (front-end/web) or through
server-backend to retrieve data from or to perform action
to Joget Workflow System
• Return response in JSON format
• Example: web/json/workflow/assignment/list/count
{"total":11}

JSON API Authentication
{Host}/jw/web/json/workflow/assignment/list/count
This JSON API is accessed as
anonymous
{Host}/jw/web/json/workflow/assignment/list/count?j_username=admin
&j_password=admin
By using j_username and j_password or hash parameter.
This JSON API is accessed as admin
{Host}/jw/web/json/workflow/assignment/list/count?j_username=admin
&hash=14ACD782DCFEB2BCDE2B271CCD559477

Password Hashing
• Used in JSON API authentication and JavaScript Single
Sign ON (SSO)
• Prevents a user's password from being directly exposed
during authentication
• Formula
– md5(username + “::” + md5Base16(password))
– E.g. Assuming that the username is “admin” and the password is
“admin”, the resulting hash should be
“14ACD782DCFEB2BCDE2B271CCD559477”.
• Online reference: http://dev.joget.org/community/display/KBv4/Hashed+Password

Password Hashing Sample Java Code
public static String md5(String content) {
try {
MessageDigest m = MessageDigest.getInstance("MD5");
byte[] data = content.getBytes();
m.update(data, 0, data.length);
BigInteger i = new BigInteger(1, m.digest());
return String.format("%1$032X", i);
} catch (Exception ex) {}
return "";
}
public static String md5Base16(String content) {
try {
MessageDigest md = MessageDigest.getInstance("MD5");
byte[] bytes = md.digest(content.getBytes());
StringBuffer sb = new StringBuffer();
for (int i = 0; i < bytes.length; i++) {
byte b = bytes[i];
String hex = Integer.toHexString((int) 0x00FF & b);
if (hex.length() == 1) {
sb.append("0");
}
sb.append(hex);
}
return sb.toString();
} catch (Exception e) {}
return "";
}

Master Login
• Master Login Username and Password is a set of
credential that can be used to login to Joget system as
different user.
• This is particularly catered to integration needs:-
– Server-backend to Joget server where individual’s credential is
not required to perform calls on behalf.
• Reference: http://dev.joget.org/community/display/KBv5/JSON+API+Authentication

JSON API Authentication – Master Login
By using Master Login feature, user’s password is not
exposed in JSON API authentication.
{Host}/jw/web/json/workflow/assignment/list/count?j_username={master-login-
username}&hash={master-login-hash} &loginAs={username}
In System Setting >
General Setting
{Host}/jw/web/json/workflow/assignment/list/count?j_username={master-login-
username}&j_password={master-login-password}&loginAs={username}

Chapter Review
• Understand the purpose and use of Master Login.

Chapter 4
JavaScript API

Introduction
• Javascript API is a helper/utility with a set of methods to ease
integration calls
<script type="text/javascript" src="http://localhost:8080/jw/js/jquery/jquery-
1.9.1.min.js"></script>
<script type="text/javascript" src="http://localhost:8080/jw/js/json/util.js"
></script>
<script type="text/javascript" >
[put your code here]
</script>
• util.js source code: wflow-consolewebsrcmainwebappjsjsonutil.js
(GithHub link: https://github.com/jogetworkflow/jw-community/blob/5.0-
SNAPSHOT/wflow-consoleweb/src/main/webapp/js/json/util.js )
• Reference: http://dev.joget.org/community/display/KBv5/JavaScript+API

List of available methods
• ConnectionManager.post(url, callback, params)
• ConnectionManager.ajaxJsonp(url, callback, params)
• ConnectionManager.get(url, callback, params, xss)
• AssignmentManager.getCurrentUsername(baseUrl, callback)
• AssignmentManager.login(baseUrl, username, password, callback)
• AssignmentManager.loginWithHash(baseUrl, username, hash, callback)
• AssignmentManager.logout(baseUrl)
• AssignmentManager.completeAssignment(baseUrl, activityId, redirect)
• AssignmentManager.completeAssignmentWithVariable(baseUrl, activityId,
variableData, redirect)
• UrlUtil.encodeUrlParam(url)
• getUrlParam(paramName)

Sample usage – Start New Process
Instance
• Starting a new process by calling the JSON API
url = "http://localhost:8080/jw/web/json/workflow/process/start/hr_expense:latest:process1";
callback = {
success: function(response){
console.log(response);
}
};
params = {var_status : 'test' };
ConnectionManager.post(url, callback, params);
{"activityId":"908_906_hr_expense_process1_new_claim","processId":"906_hr_
expense_process1"}
JSON API to start a new process instance
Reference:
http://dev.joget.org/community/display/KBv5/JSON+API
Code:
Result:
Replace accordingly
• Sample coding can be obtained at 18.4.1.txt

Sample Usage – Get Current User
• Finding out the current logged in user by using the
AssignmentManager.getCurrentUsername() method.
• Sample coding can be obtained at 18.4.2.txt
var callback = { success : function(response){
//response.username }
}
AssignmentManager.getCurrentUsername('http://localhost:8080/jw', callback);
{username: "admin"}
Code:
Result:

Setup Suggestion
• Can you now imagine the following setup?
JogetApp
Server
Joget
DB
Server
External
App
Server
External
DB
Server
Javascript
API

Chapter Review
• Understands the purpose and usages of the Javascript
API.

Chapter 5
Single Sign On (SSO)

Introduction
• User logs in to external system and implicitly gains access
to Joget without being prompted to login again.
• Used with JavaScript API .
• AssignmentManager.login(baseUrl, username, password, callback)
• AssignmentManager.loginWithHash(baseUrl, username, hash, callback)
• AssignmentManager.logout(baseUrl)

Sample Script
• Perform actions in callback of successful login
<script type="text/javascript" src="http://localhost:8080/jw/js/json/util.js" ></script>
$(document).ready(function(){
var loginCallback = {
success : function(response){
if(response.username != "roleAnonymous"){
alert("login successfully");
}else{
alert("login fail");
}
}
};
AssignmentManager.login('http://localhost:8080/jw', 'admin', 'admin', loginCallback);
});
</script>
• Sample coding can be obtained at 18.5.1.txt.

Single Sign on (SSO)
Required JavaScript library
Callback Function Joget Workflow Server URL Username
Clear Text Password or
Hashed Password
<script type="text/javascript" src="http://localhost:8080/jw/js/json/util.js"
></script>
var loginCallabck = {
if(response.username != "roleAnonymous"){
alert("login successfully");
}else{
alert("login fail");
}
}
};
AssignmentManager.login('http://localhost:8080/jw', 'admin', 'admin',
loginCallback);
});
</script>

Hashed Password
• To prevent directly expose user’s password in
authentication
• Formula:
– md5(username + “::” + md5Base16(password));
• Example:
– Username is “admin”
– Password is “admin”
– Resulted hash should be
“14ACD782DCFEB2BCDE2B271CCD559477”

Generate Hashed Password
public static String md5(String content) {
try {
MessageDigest m = MessageDigest.getInstance("MD5");
byte[] data = content.getBytes();
m.update(data, 0, data.length);
BigInteger i = new BigInteger(1, m.digest());
return String.format("%1$032X", i);
} catch (Exception ex) {}
return "";
}
public static String md5Base16(String content) {
try {
MessageDigest md = MessageDigest.getInstance("MD5");
byte[] bytes = md.digest(content.getBytes());
StringBuffer sb = new StringBuffer();
for (int i = 0; i < bytes.length; i++) {
byte b = bytes[i];
String hex = Integer.toHexString((int) 0x00FF & b);
if (hex.length() == 1) {
sb.append("0");
}
sb.append(hex);
}
return sb.toString();
} catch (Exception e) {}
return "";
}
Code in Java

Setup Suggestion
JogetApp
Server
User
Directory
ExternalApp
Server
End User
Login
SSO?
User Directory
plugin

Chapter Review
• Understand on how to use the SSO feature.

Chapter 6
Embedding Task Inbox into
External System

Embedding Task Inbox into External
System
• Display Joget Workflow task inbox in other web
applications, such as portal (SharePoint, Liferay) and
content management system (Joomla!, WordPress,
Drupal, Alfresco).

System
<link rel="stylesheet" type="text/css" href="http://localhost:8080/jw/css/portlet.css">
<script type="text/javascript" src="http://localhost:8080/jw/js/jquery/jquery-migrate-
<script type="text/javascript" src="http://localhost:8080/jw/js/json/util.js"></script>
<div id="inbox1">
<center><img src="http://localhost:8080/jw/images/v3/portlet_loading.gif" />
</center>
</div>
<script type="text/javascript">
$(document).ready(function() {
$.getScript('http://localhost:8080/jw/web/js/client/inbox.js?id=1&rows=5&divId=inbox1',
null);
});
</script>
Unique id to identify the inbox instance
Number of rows to be displayed in this inbox instance
ID of the HTML DIV to display this inbox instance

System

System
Customize the look and feel of embedded task inbox by pointing to a new css
file.
<div id="inbox1">
</center>
</div>
$(document).ready(function() {
null);
});
</script>

System with SSO
<div id="inbox1">
</center>
</div>
var loginCallback = {
success: function(){
null);
}};
AssignmentManager.login('http://localhost:8080/jw', 'admin', 'admin',
loginCallback);
});
</script> Load script after successfully logged in

Setup Suggestion
JogetApp
Server
JogetDB
Server
External
AppServer
External
DBServer
End User
Embedded
Task Inbox

Chapter Review
• Understand on how to embed Task Inbox into external
app.

Chapter 7
Embedding Userview Page in
an iFrame

Embedding Userview Page in an IFrame

Embedding Userview Page in an IFrame
• The header, menu & footer of Userview can be removed
by following:
—By adding parameter “embed=true” in the URL OR
—By modifying the URL
http://localhost:8081/jw/web/userview/crm/crm_userview_sales
http://localhost:8081/jw/web/embed/userview/crm/crm_userview_sales
From
To

Setup Suggestion
JogetApp
Server
JogetDB
Server
External
AppServer
External
DBServer
End User
Embedded
Mode

Exercise
• Choose a Userview Page.
• Add in the necessary parameter to turn it into the
Embedded mode.
• Use iFrame to display it in your custom app.

Chapter Review
• Understands the purpose of using Embedded mode of
Userview pages.

Chapter 8
Using the SOAP Tool

Introduction
• The SOAP Tool allows one to invoke web service for
integration purpose to return useful information from
external sources into the process instance.
• Reference:
http://dev.joget.org/community/display/KBv5/SOAP+Tool

How it works?
• The SOAP Tool will call the Web Service configured,
passes the set of parameters set.

How it works?
• Data will be returned in the JSON form.
INFO 07 Jun 2013 10:54:37 SoapTool - <ns1:GetGeoIPResult
xmlns:ns1="http://www.webservicex.net/"><ns1:ReturnCode>1</ns1:ReturnCode><ns1:IP>8.
8.8.8</
ns1:IP><ns1:ReturnCodeDetails>Success</ns1:ReturnCodeDetails><ns1:CountryName>United
States</ns1:CountryName><ns1:CountryCode>USA</ns1:CountryCode></n s1:GetGeoIPResult>
INFO 07 Jun 2013 10:54:37 SoapTool - {"GetGeoIPResult":{"CountryName":"United
States","ReturnCodeDetails":"Success","ReturnCode":"1","IP":"8.8.8.8",
"CountryCode":"USA"}}
{
"GetGeoIPResult": {
"CountryName": "United States",
"ReturnCodeDetails": "Success",
"ReturnCode": "1",
"IP": "8.8.8.8",
"CountryCode": "USA"
}
}

How it works?
• Data can be then stored into Form table or Workflow
Variable.

Exercise
• Go to http://www.webservicex.net
• Select a service
• Create a new Joget Workflow App with a Activity -> Tool -
> Activity process.
• Map the Tool to a SOAP Tool, configure accordingly.

Setup Suggestion
JogetApp
Server
JogetDB
Server
External
AppServer
External
DBServer
End User
via
Userview
Web
Service Call

Chapter Review
• Be able to make calls from Joget to other web services by
using the SOAP Tool.
• You may also achieve similar result by using other
integration plugins such as JSON Tool.

Chapter 9
Integrating with External
Form

Integrating with External Form
• To perform (form) activities that Joget Workflow is not
designed to do.
• To integrate with web data form built in external system,
regardless of platform.
• To allow data to be submitted into external system within
a process.

Scenario – Integrate with Payment
Gateway
Joget Workflow
External Web
Application
Payment Gateway
Submit
Registration
Form
External :
Process
Payment
Email : Send
Notification
Joget
Form
Externa
l URL
1
Submit
Payment Detail
Process
Transaction
Result
View Payment
Status
2
3 4
5
6
7
URL params that will be passed over:
appId, appVersion, processId,
processVersion, activityId,
processRequesterId,
username
Post data to
Payment Gateway
Data post back from
Payment gateway
Use Joget Workflow
JavaScript API to
complete assignment
and set Workflow
Variable

Example
Joget Workflow
External Web
Application
Submit
Registration
Form
External :
Process
Payment
Email : Send
Notification
credit-
card-
payment.js
p
1
credit-card-
payment.jsp
process-
payment.jsp
payment-
status.jsp
2 4
JavaScript:
AssignmentManager.completeAssignmentWithVariable
3
5
6

Example – Workflow Process
credit-card-payment.jsp
process-payment.jsp
payment-status.jsp
EXTERNAL SYSTEM
External Form Mapping JavaScript API

Map to an External Form
X
Y
<ifram src=“X” style=“Y”> … </iframe>

• Parameters that will be passed into external form from Joget
Workflow:
– appId
– appVersion
– processId
– processVersion
– activityId
– processRequesterId
– username
• credit-card-payment.jsp is the first external URL called, but it
can call to any other web pages in the series, before getting
back to Joget Workflow activity

<h1>Credit Card Payment</h1>
<p>Parameters passed into this page:
<ul>
<li>appId: <%=request.getParameter("appId")%></li>
<li>appVersion: <%=request.getParameter("appVersion")%></li>
<li>processId: <%=request.getParameter("processId")%></li>
<li>processVersion: <%=request.getParameter("processVersion")%></li>
<li>activityId: <%=request.getParameter("activityId")%></li>
<li>processRequesterId : <%=request.getParameter("processRequesterId")%></li>
<li>username: <%=request.getParameter("username")%></li>
</ul>
</p>
<form method="POST" action="process-
payment.jsp?activityId=<%=request.getParameter("activityId")%>&redirect=payment-
status.jsp">
<p>Assuming you have completed all payment details, now let's submit this form to
process-payment.jsp</p>
<input type="submit" value="Submit" />
</form>
`

process-payment.jsp
• Process the payment details submitted from credit-card-
payment.jsp, and make a Ajax JavaScript call to Joget
Workflow, to
– Complete the “External: Process Payment” assignment
– Update workflow variable – “transaction_no”
• Redirect to payment-status.jsp to display summary of the
transaction
• Once the “External: Process Payment” is completed,
subsequent workflow activities will be continued and
performed in Joget Workflow

process-payment.jsp
<script type="text/javascript"
src="http://localhost:8080/jw/js/json/util.js"></script>
var callback = {
AssignmentManager.completeAssignmentWithVariable("http://localhost:8080/jw",
getUrlParam("activityId"),
"var_transaction_no =TN00001",
escape(getUrlParam("redirect")));
}
}
AssignmentManager.login("http://localhost:8080/jw", "admin", "admin", callback);
</script>

payment-status.jsp
• Display to user synchronously without interrupt
subsequent workflow activities.
<h1>Payment Status</h1>
<p>Yeh~~~ payment transaction is completed.</p>

Setup Suggestion
JogetApp
Server
JogetDB
Server
ExternalApp
Server
External
DBServer
End User
via
Userview
External
Form

Chapter Review
• Understand and being able to use External Form
effectively.

Module Review
• Can you now picture various setup scenarios to integrate
Joget with your external app?
JogetApp
Server
JogetDB
Server
External
AppServer
External
DB
Server
End User
various
means…
various
means…
End User
various
means…

Stay Connected with Joget Workflow
• http://www.joget.org
• http://community.joget.org
• http://twitter.com/jogetworkflow
• http://facebook.com/jogetworkflow
• http://youtube.com/jogetworkflow
• http://slideshare.net/joget

Joget Workflow v6 Training Slides - 18 - Integrating with External System

More Related Content

What's hot (20)

Similar to Joget Workflow v6 Training Slides - 18 - Integrating with External System (20)

More from Joget Workflow (19)

Recently uploaded (20)

Joget Workflow v6 Training Slides - 18 - Integrating with External System