Embedding Process UI Components in Other Applications

Integrate Oracle Process Cloud 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.

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 Workspace. For example, you might configure a Process form that initiates a process by enabling users to submit a safety incident report.

Oracle Process Cloud Service provides the following reusable UI components. You use jQuery to embed the component in any HTML page.
  • Detail: Displays details for the selected task.

  • Start Application: Displays the list of applications and their start form.

  • Start Form: Displays the start form and attachments or documents. Documents display only if Oracle Content and Experience Cloud is configured, and only if documents are enabled for the application.

  • Attachments: Displays attachments or documents. Documents display only if Oracle Content and Experience Cloud is configured, and only if documents are enabled for the application.

  • Comments: Displays comments for the selected task.

  • Conversation: Displays conversations for the selected task. Conversation display only if Oracle Content and Experience Cloud is configured, and only if conversations are enabled for the application.

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.

  • Oracle Process Cloud Service provides an open endpoint to its UI components, 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 the Process Cloud Service 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

  • Embeddable components are automatically protected by the same security model as Workspace. To implement OAuth security for a component, use an OAuth token to access the UI. See Using OAuth with REST APIs.

  • Oracle Process Cloud Service provides downloadable files, including the entire library of embeddable Process UI component files and dependencies. See Downloading 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 Experimenting 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 Consuming the Process Cloud UI Component.

  • Embeddable components and REST APIs support cross-origin resource sharing (CORS).

Downloading 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 Cloud Service 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:
  1. Access the open components endpoint on your Process Cloud Service server using the following format:
    host:port/bpm/components
  2. Click Resources.
  3. Download the files listed in the Download section.

    Be sure to download and update component files after releases as needed. The Oracle Process Cloud Service 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.

Experimenting with Process UI Components

Oracle Process Cloud Service includes a cookbook where you can try out the functionality of the Process UI components, and view the methods, events, and options they support. 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:
  1. Access the cookbook at the following endpoint:
    host:port/bpm/components
    The Home page opens. It displays settings and information that apply to all the embeddable Process UI components.
  2. On the Home page, complete the Server Setup fields to identify your Oracle Process Cloud Service 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 Workspace test mode.

  3. Click Apply.
  4. While you’re on the Home page, expand and review the information:
    • In the Process Cloud Service Connection section. It describes how to connect to the Oracle Process Cloud Service 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.

  5. Click Cookbook.
  6. Use the links in the left pane to select a UI component (Detail, Start Application, Start Form, Attachments, Comments, or Conversation).
  7. 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.
  8. 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.
  9. 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.

Consuming the Process Cloud UI Component

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

  1. 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 Process Cloud Service server. For example:

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

    This command means you don’t have to include the Oracle Process Cloud Service code in your application, and can get it remotely instead.

  2. Create the Oracle Process Cloud Service 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 PCS 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}'

    See Obtaining a Client Access Token.

  3. Configure component use in the app main.js file. For details, go to the Home page and expand the Configuration section.
  4. Configure the selected component, as described on the Cookbook UI’s component pages. For example, see Require, Usage, Options, Methods, and Events fields.
  5. 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.