Embed Process UI Components in Other Applications

Integrate Process functionality in external applications, such as self-service applications, services, or portals, by embedding Process UI components provided as jQuery widgets. The external application or service consumes the embeddable Process component and renders it on the appropriate mobile, tablet, or web platform.

Topics:

Process UI Components Available for Embedding

After you embed Process UI components in an external application, your users can then start their tasks within the context of their primary focus rather than in Process runtime. For example, you might configure a Process form that initiates a process by enabling users to submit a safety incident report.

Description of safety-incident-report.png follows

Description of the illustration safety-incident-report.png

Use jQuery to embed a selected reusable Process UI component in any HTML page. Components related to the following categories are provided.

Task
Application: Display the list of applications and their start form or start form and attachments or documents. Documents display only if Oracle Content Management is configured, and only if documents are enabled for the application..
Dynamic Process: Displays various components for dynamic process.
Charts
Miscellaneous

Embeddable Process UI components expose several options and events that the consuming application can use. You can customize the components using these options and get access to the internal data using public methods.

Whenever a significant user action occurs, the components trigger events. For example, when a user submits a form, an event is fired along with the instance data. You can listen to the events, and perform actions on the consuming application. See http://learn.jquery.com/events/introduction-to-custom-events/.

Before You Embed Process UI Components

Review these requirements and tips before you embed Process UI components in external applications.

Embedding components requires knowledge of JavaScript, HTML, jQuery, and Require JS.
An open endpoint to Process UI components is provided, and the cookbook is hosted directly on it. The open endpoint gives you several options:
- Download and use the code in the zip file
- Point directly to theOracle Integration server to load JS/CSS resources remotely without the need to include the resource inside your application
- Use the HTML Inline Frame Element <iframe> to embed the component pages
Downloading files, including the entire library of embeddable Process UI component files and dependencies, are provided. See Download Process UI Component Files.
Newer versions of the component files may be available with each release, although you can download previous versions. Note that any customizations you make to previous versions must be made again to a newer version.
To view and experiment with the UI component capabilities, use the cookbook. See Experiment with Process UI Components.
To change the look and feel of either a single component or the entire UI, override the cascading style sheet (CSS). See Consume the Process UI Component.
Embeddable components and REST APIs support cross-origin resource sharing (CORS).

Download Process UI Component Files

Before you can experiment with the Process UI components, you need access to the entire code base of the embeddable components, including the Process library, cookbook sample code, and dependency library. The library contains both the debug (complete) version and the minified version for JS and CSS files. You can download and host the component files. Alternatively, you can use an HTML Inline Frame Element (<iframe>) to embed the components.

To download and host the component files:

Access the open components endpoint on your Oracle Integration server using the following format:
host:port/ic/pub/components
Click Resources.
Download the files listed in the Download section.

Be sure to download and update component files after releases as needed. The Process library file identifies the component feature’s version number. To ensure that you’re using the latest embedded Process UI component files available in future releases, compare your current version number with the version number listed on the Resources page, and download the newer version if needed.

As an alternative to hosting the components, you can use them in an <iframe> element instead. For information, go to the Resources page, scroll to the Server Access section, and expand the HTML section.

Experiment with Process UI Components

Use the cookbook to try out Process UI component functionality, and view supported methods, events, and options. Note that the cookbook is provided for demonstration purposes only. You can’t use it to consume the UI components.

To experiment with Process UI components:

Access the cookbook at the following endpoint:
host:port/ic/pub/components

The Home page opens. It displays settings and information that apply to all the embeddable Process UI components.
On the Home page, complete the Server Setup fields to identify your Oracle Integration server.
- You must configure these fields if you want to experiment with using the Process UI components.
- Select the testMode option if you want to get and test production data. This option is equivalent to the runtime test mode.
Click Apply.

Description of the illustration using_cookbook_ui_oic.png
While you’re on the Home page, expand and review the information:
- In the Integration Connection section. It describes how to connect to the Process server and authenticate the user using a Basic, JWT, or OAuth access token.
- In the Configuration section. It describes how to consume the embeddable components in the external application’s main.js file.
You’ll need this information when you’re ready to connect and consume the components.
Click Cookbook.
Use the links in the left pane to select a UI component (Detail, Start Application, Start Form, Attachments, or Comments).
Expand the Documentation section and review its details about configuring the selected component. The Documentation section displays the following information:
- Require: Describes the Require JS module name and any other settings required to consume the component.
- Usage: Provides sample code for consuming the component.
- Options: Provides a table listing ways to alter the component’s behavior. Some of the options are required to consume the component. Expand the Component Setup section to try out the options.
- Methods: Lists methods to access various data in the component. For example, use the applist component’s getStartformList method to get a list of available forms. This information is useful for consuming the Start Form component independently. Expand the Data section to view event and method call results.
- Events: Lists the user actions on the component that fire events that the consuming application can listen to and use in the external application’s logic. Expand the Data section to view event and method call results.
Expand the Demo Code section to review sample JS and HTML code for the selected component, along with the component options currently being used to load the component. These options change when you change Component Setup values.
Expand the Component Setup section, select or enter options, and click Apply to see how your changes affect the component. For example, try renaming or hiding buttons.

Description of component-setup-oic.png follows

Description of the illustration component-setup-oic.png

Consume the Process UI Component

Use the configuration, documentation, and demo code provided in the cookbook to guide you in integrating the component:

Consume the downloaded library’s js/libs and css/libs inside your external application.

Alternatively, you can directly point the 'pcs' path in your requirejs file to the remote Oracle Integration server. For example:

'pcs' : 'PCS_SERVER_URL/ic/pub/components/js/libs/pcs/v1.2/min'

This command means you don’t have to include the Process code in your application, and can get it remotely instead.
Create the Process connection ($.pcsConnection) in the app main.js file and configure it to identify the server URL and authentication. Go to the Home page and expand the Connection section for details.

The authentication information is provided through the authInfo property, which can contain the Basic, JWT, or OAuth access token. The app main.js file is responsible for maintaining a valid token.

Basic authentication token can be provided by:

var tok = username + ':' + password;

$.pcsConnection.authInfo = 'Basic ' + btoa(tok);

Other access tokens (JWT or OAuth) can be provided by:

$.pcsConnection.authInfo = 'Bearer {token string}'
Configure component use in the app main.js file. For details, go to the Home page and expand the Configuration section.
Configure the selected component, as described on the Cookbook UI’s component pages. For example, see Require, Usage, Options, Methods, and Events fields.
Optionally change a component’s look and feel, or that of the entire UI, by overriding the cascading style sheet (CSS) files.
Each UI component has an ID and a class. For example, to change the application list links from circles to squares, override .pcs-applist-process-holder-smaller css class.
1. To change a component’s css, expand the Demo Code and HTML sections on the component page and determine the CSS file. You can copy, modify, and override the CSS file listed.
2. Use CSS selectors to access HTML elements and modify the look and feel after the UI component has rendered.

Best Practices for Embedding Process UI Components

To integrate the Process UI with external applications, you can either embed Process components directly into an external application’s HTML or JS code or use URL iFrames.

The tips and best practices listed in this section correspond to the first approach; they’re aimed towards facilitating a hassle-free integration of Process UI by adding the required components into your consuming application’s code, without employing iFrames.

Download all the required dependent libraries and CSS files to the client location and reference them using a local path to prevent unexpected interruptions while loading the client interfaces. For example, download and reference oj-alta-min.css locally in the consuming HTMLs, instead of including it as follows:

<link rel="stylesheet" href="https://<pcsserverhost:port>/ic/pub/components/css/libs/oj/v2.0.0/alta/oj-alta-min.css" type="text/css"/>
In addition to the standard dependent libraries, load the JS configuration files of the corresponding embeddable component in the consuming HTML. For example, you’ll require the following code to load the Start Form widget:

<script data-main="<local_host>/main/startform-main " src="<local_host>/js/libs/require/require.js"></script>
Configure the client applications to consume the component-load events that are fired by an embeddable component. For instance, an embeddable component can open up further pop-ups to resize or repaint itself.
Avoid using iFrames to consume UI embeddable components (snippets). Use them only as a last resort.
Use the minified JS and CSS files for better performance. Minified versions of components are available in the min folder of the downloaded code.
If you need to use Process components as part of Sites in Oracle Content Management, use the out-of-the-box (OOTB) components to avoid integration issues. The OOTB Process UI components are available in Oracle Content Management.
Before you use a newer version of UI embeddable components, always port the customizations performed on the previous version to avoid mismatches in the UI rendering.
You can use standalone widgets, such as Comments, Attachments, and so on, in similar ways to other jQuery widgets for your business requirements, without having to connect to the Process server. The widgets fire events—with all the required data—whenever a comment or attachment is added or updated, so that consuming applications can act on these events.
Optionally, retrieve the Process test data corresponding to applications, start forms, and task details by adding the testMode parameter to the default URL. The following example fetches the applications that are deployed to the test platform:

IS_SERVER_UR/ic/pub/components/pages/applist.html?testMode=true

Here are working samples for embedding a task list and start application.

Task List:

<html>
<head lang="en">
	<meta charset="UTF-8">
	<title>TaskList</title>
	<!-- This is the main css file for the default Alta theme -->
	<link rel="stylesheet" href="https:///<local_host>/ic/pub/components/css/libs/oj/v2.0.0/alta/oj-alta-min.css" type="text/css"/>
	<!-- This is where you add application-specific styling -->
	<link rel="stylesheet" href="https://<local_host>/ic/pub/components/css/libs/pcs/v1.3/alta/pcs-tasklist-min.css" type="text/css"/>
	<!-- RequireJS configuration file  -->
	<script data-main="https://<local_host>/main/tasklist-main" src="https://<local_host>/ic/pub/components/js/libs/require/require.js"></script>
<script>
requirejs.config({
baseUrl: "https://<local_host>/ic/pub/components/js",
paths:
{
'knockout': 'libs/knockout/knockout-3.4.0',
'jquery': 'libs/jquery/jquery-2.1.3.min',
'jqueryui-amd': 'libs/jquery/jqueryui-amd-1.11.4.min',
'promise': 'libs/es6-promise/promise-1.0.0.min',
'hammerjs': 'libs/hammer/hammer-2.0.4.min',
'underscore' : 'libs/underscore/underscore-1.8.3.min',
'ojdnd': 'libs/dnd-polyfill/dnd-polyfill-1.0.0.min',
'ojs': 'libs/oj/v2.0.0/min',
'ojL10n': 'libs/oj/v2.0.0/ojL10n',
'ojtranslations': 'libs/oj/v2.0.0/resources',
'signals': 'libs/js-signals/signals.min',
'text': 'libs/require/text',
'pcsMsg' : 'libs/pcs/v1.3/resources',
'pcs' : 'libs/pcs/v1.3/min',
'rendererMsg': 'libs/pcs/v1.3/rendererMsg'
},
shim: {
'jquery': {
exports: ['jQuery', '$']
}
}
});
require(['jquery', 'pcs/pcs.tasklist' ],
function ($) {
//var tok = 'cloud.admin' + ':' + 'StacKed@7SUitE';
$.pcsConnection = {
serverURL: 'https://<local_host>',
authInfo: 'Basic c2VyZW5lLnRhbkBvcmFjbGUuY29tOk9uQ2U3c2F0MSE=',
};
//$.pcsConnection.authInfo = 'Basic ' + btoa(tok);
var tasklist = $('#tasklist');
$("#tasklist").tasklist({
"hideToolbar": false,
"hideFilter": false,
"hideSystemActions": false,
"hideCustomActions": false,
"hideSearch": false,
"hideSort": false,
"hideRefresh": false,
"hideFromUserName": false,
"hideAssignedDate": false,
"hideDueDate": false,
"hideCreatedDate": false,
"hideSummary": false,
"hideTaskDetails": false,
"pageSize": 10,
"hideSelectAll": true,
"selectedSortType": "assignedDate",
"selectedSortOrder": "ascending",
"taskDetailOptions": "{\"attachmentsOptions\": {\"showDocsInline\":true}}",
"systemActions": "SUSPEND,ESCALATE,RENEW,REASSIGN,INFO_REQUEST,WITHDRAW,ACQUIRE,PURGE,DELETE,RESUME,RELEASE",
"tasklistFilter": "{}"
});
// Defining the event listeners --
tasklist.on('tasklist:taskSelect', function(event, data){
});
tasklist.on('tasklist:taskCheck', function(event, data,instance){
});
}
);
</script>
</head>
<body style="overflow-y:scroll">
<div id="tasklist"></div>
</body>
</html>

Start Application:

<html>
<head lang="en">
	<meta charset="UTF-8">
	<title>Start Application</title>
	<!-- This is the main css file for the default Alta theme -->
	<link rel="stylesheet" href="https://<local_host>/ic/pub/components/css/libs/oj/v2.0.0/alta/oj-alta-min.css" type="text/css"/>
	<!-- This is where you add application-specific styling -->
	<link rel="stylesheet" href="https://<local_host>/ic/pub/components/css/libs/pcs/v1.3/alta/pcs-applist-min.css" type="text/css"/>
	<!-- RequireJS configuration file  -->
	<script data-main="https://<local_host>/main/applist-main" src="https://<local_host>/ic/pub/components/js/libs/require/require.js"></script>
<script>
requirejs.config({
baseUrl: "https://<local_host>/ic/pub/components/js",
paths:
{
'knockout': 'libs/knockout/knockout-3.4.0',
'jquery': 'libs/jquery/jquery-2.1.3.min',
'jqueryui-amd': 'libs/jquery/jqueryui-amd-1.11.4.min',
'promise': 'libs/es6-promise/promise-1.0.0.min',
'hammerjs': 'libs/hammer/hammer-2.0.4.min',
'underscore' : 'libs/underscore/underscore-1.8.3.min',
'ojdnd': 'libs/dnd-polyfill/dnd-polyfill-1.0.0.min',
'ojs': 'libs/oj/v2.0.0/min',
'ojL10n': 'libs/oj/v2.0.0/ojL10n',
'ojtranslations': 'libs/oj/v2.0.0/resources',
'signals': 'libs/js-signals/signals.min',
'text': 'libs/require/text',
'pcsMsg' : 'libs/pcs/v1.3/resources',
'pcs' : 'libs/pcs/v1.3/min',
'rendererMsg': 'libs/pcs/v1.3/rendererMsg'
},
shim: {
'jquery': {
exports: ['jQuery', '$']
}
}
});
require (['ojs/ojcore', 'ojs/ojmodule', 'pcs/pcs.applist'],
function (oj,$) {
oj.ModuleBinding.defaults.modelPath = './';
oj.ModuleBinding.defaults.viewPath = 'text!./';
}
);
require(['jquery', 'pcs/pcs.applist' ],
function ($) {
//var tok = 'cloud.admin' + ':' + 'StacKed@7SUitE';
$.pcsConnection = {
serverURL: 'https://<local_host>',
authInfo: 'Basic c2VyZW5lLnRhbkBvcmFjbGUuY29tOk9uQ2U3c2F0MSE=',
};
//$.pcsConnection.authInfo = 'Basic ' + btoa(tok);
var appList = $('#applist');
$("#applist").applist({
"hideStartform": false,
"startformDialog": false,
"hideSubmit": false,
"hideSave": false,
"hideDiscard": false,
"submitLabel": "Submit",
"hideAttachment": false,
"hideSearchBox": true,
"hideDefaultCheck": true,
"iconSize": "small",
"hideEmptyText": false,
"hideToolbar": false,
"hideRefresh": false,
"defaultVersion": false
});
// Defining the event listeners --
appList.on('applist:formSelected', function(event, data){
});
appList.on('applist:formSubmited', function(event, data,instance){
});
appList.on('applist:formSaved', function(event, data ,instance){
});
}
);
</script>
</head>
<body>
<div id="applist"></div>
</body>
</html>