Universal Workflow

The Workflow Widget NEW ​

The Workflow Widget is a versatile tool designed to streamline the approval process for workflow packages. This widget is seamlessly integrated into web pages via an iframe and utilizes the University's OIDC authentication system to ensure secure access.

Key Features:

  • Authentication: The widget leverages the University's OIDC authentication system to verify user identity and permissions.
  • Approval Actions: Approvers can perform a variety of actions, including signing and voiding packages, adding approvers, viewing routing history, and adding comments and attachments.
  • Permission-Based Display: The widget automatically checks an approver's permissions and only displays the actions they are authorized to perform, ensuring a tailored and secure user experience.

Usage: The Workflow Widget is intended to be embedded on pages that allow users to view and sign workflow packages. It handles all actions available to approvers during the routing process, making it an essential tool for efficient workflow management.

By integrating the Workflow Widget, you can enhance the functionality of your web pages and provide approvers with a comprehensive set of tools to manage workflow packages effectively.

IMPORTANT! 🚨

Before you deploy to production: We need the hostname of the application you'll be embedding the widget in for location verification. Otherwise, widget won't load.

Installation ​

To install the Workflow Widget, please place the following code snippet on your page:

js
(function() {
	window.WorkflowWidget = {};
	window.WorkflowWidget.package_id = '{{ WORKFLOW_ID }}';
	window.WorkflowWidget.client_id = '{{ API_CLIENT_ID }}';
	// window.WorkflowWidget.history_mode = true; Optional and defaults to false

	let cacheBuster = new Date().getTime();
	let script = document.createElement('script');
	script.async = true;
	script.src   = 'https://workflow.uiowa.edu/workflow-widget/widgetLoader.js?v=' + cacheBuster;
	script.type  = 'text/javascript';

	document.getElementsByTagName('head')[0].appendChild(script);
})();

A div with id #widgetContainer determines where the Workflow Widget will be placed within your page.

html
<div id="widgetContainer"></div>

Tip

If you want to develop locally, ensure that your localhost connection is running via HTTPS; otherwise, your browser will not allow the widget to operate normally.

Options and Parameters ​

WorkflowWidget.package_id - The ID of the package you want to display in the widget. This is a required parameter.

WorkflowWidget.client_id - The api client ID of the application using the widget. This is a required parameter.

WorkflowWidget.history_mode Optional - Set to true if you want to display the package history instead of approval options. This is an optional parameter and defaults to false.

Events NEW ​

Workflow Widget emits several events that your app can listen to for added functionality. The key events are:

workflow-widget-event:approve - this event is emmitted after the user successfully approves a package using the Workflow Widget.

workflow-widget-event:void - this event is emitted after the user successfully voids a package through the Workflow Widget.

workflow-widget-event:r2i - this event is emitted after the user successfully returns a package to the initiator through the Workflow Widget..

js
// Widget event listener
window.addEventListener('message', handleWidgetEvents);

// Function to handle messages from the widget
function handleWidgetEvents(event) {
    if (event.origin === 'https://workflow.uiowa.edu') {
        if (event.data.action === 'workflow-widget-event:approve') {
            // Add custom code to handle an approval event or redirect to a specific page
            // window.location.href = 'https://workflow.uiowa.edu';
        }
        else if (event.data.action === 'workflow-widget-event:void') {
            // Add custom code to handle a void event or redirect to a specific page
            // window.location.href = 'https://workflow.uiowa.edu';
        }
        else if (event.data.action === 'workflow-widget-event:r2i') {
            // Add custom code to handle an return to initiator event or redirect to a specific page
            // window.location.href = 'https://workflow.uiowa.edu';
        }
    }
    else {
        console.warn('Message received from an unexpected source:', event.source);
    }
}