Workplace toolkit

The Workplace toolkit consists of a set of views that you can use to build your own custom applications and dashboards.

Views in the Workplace toolkit
Customizing the views

Each view points to a specific set of files:

A JavaScript file that provides the behavior of the view
Image files to represent the view on the palette and on the canvas
A preview JavaScript file that shows a preliminary image of the view

The view can also have other files such as CSS and LESS files for styling, localization files and other view specific resource files, but these additional files are optional.

Tip: You can use the views in the Workplace toolkit by themselves as stand-alone views, but typically you would use them in conjunction with views in the UI toolkit, such as Horizontal layout, Vertical layout, Collapsible panel, and Panel.

Configuration properties

Under Configuration, set or modify configuration properties for the view, such as appearance, behavior, and performance properties.

Screen size: A configuration property that has the Screen Sizes icon beside the property name can have different values for each screen size. If you do not set a value, the screen size inherits the value of the next larger screen size as its default value.

Theme definitions: Theme definitions specify the colors and styles for a view and determine its appearance. You can preview the look and feel of views in the theme editor. See Themes.

For specific configuration properties for each view, see the corresponding JavaScript API documentation.

Events: Set or modify the event handlers of a view in the Events properties. You can set events to be triggered programmatically or when a user interface interacts with the view. For information about how to define and code events, see User-defined events.; For event handler information that is specific to each view, see the corresponding JavaScript API documentation. Depending on the specific event, you can use JavaScript logic to modify the effects of the view. More information on using events with views is found in the topic User-defined events.

Methods: For the methods that are available for each view, see the corresponding JavaScript API documentation.

Additional resources: For information about how to create a coach or page, see Building coaches.
For information about standard properties (General, Configuration, Positioning, Visibility, and HTML Attributes), see View properties.

Views in the Workplace toolkit

The following views are available in the Workplace toolkit. To be able to use these views to build your user interfaces or dashboards, you must first add the Workplace toolkit as a dependency to your application.

Table 1. Views in the Workplace toolkit
View name	Description
Instance List	Adds an instance list widget to your dashboard, which lists all the workflow instances that you are authorized to see and participate in. You can sort, filter by app, and reload the instances in the list. For the methods and event handlers that are available for the view, see Instance List.
Instance Viewer	Adds an instance viewer widget to your dashboard, which displays data that is relevant to the workflow instance. For the methods and event handlers that are available for the view, see Instance Viewer.
Task List	Adds a task list widget to your dashboard, which lists all the tasks that you claimed or you've been assigned, as well as the unclaimed tasks that are assigned to your team. You can search, sort, filter by app, reload, and open the tasks in the list. For the methods and event handlers that are available for the view, see Task List.
Task Viewer	Adds a task viewer widget to your dashboard, which displays data that is relevant to the task. For the methods and event handlers that are available for the view, see Task Viewer.

Customizing the views

If necessary, you can customize the views for use in your custom business applications and workflow automations. The following customization examples refer mainly to the Task List and Instance List views.

Customizing in a business application

To use the Task List and Instance List views in your business application, add the following environmental variable and application resource to the application project settings, as follows. The added variable and resource specify where the Application Engine proxy should send the requests for retrieving the task or instance lists. By adding them, you ensure that the views are loaded correctly and are ready to use in your business application.

Environment variable

Name: PFS
Value: PFSEndpoint

Application resource

Name: WORKFLOW
Type: Registry Lookup
Category: IBM_WORKFLOW
Key: WORKFLOW_SYSTEM
Authentication: OpenID Connect

Customizing in a process application

Before using the Workplace toolkit views in your client-side human services, ensure that the toolkit is added as a dependency to your process application. When the dependency is added, the Task List, Instance List, Task Viewer, and Instance Viewer views are available in the designer's list of components, from where you can add them to coaches and arrange them as needed to build your UI. For example, you can add the Task List and Instance List views to a coach in your client-side human service to display the lists of your available tasks and instances in the runtime UI.

To enable your tasks and instances to open in the user interface:

Add the Task Viewer to the coach to display the task and instance details.
Select the Enable instance launch configuration option in the Instance List view to enable instances to open when you click their name.
Select the Enable task launch configuration option in the Task List view to enable tasks to open when you click their name.

By default, tasks or instances open in the same window, replacing the current view. To change the default behavior, use the following options in the Behavior section of the corresponding view:

For Task List, select Open task in new window to open all the tasks in a new window or tab.
For Instance List, select Open instance in new window to open all the instances in a new window or tab.

Note: These configurations load the page to a new URL.

If you want to open a task or instance without going to a different URL:

Clear the Open task in new window or Open instance in new window option.
Add all the existing views in a Vertical layout container, except for the Task Viewer and Instance Viewer.
Add the following line of code to the specified events in the corresponding views, as follows:
```
this.ui.getSibling("Vertical_Layout1").setVisible(false,true);
```
where Vertical_Layout1 is the control ID of the vertical layout container.
- In the Task List view, add the code to the "On task launched" event.
- In the Instance List view, add the code to the "On instance launched" event.
- In the Task Viewer view, add the code to the "On task opened" and "On service opened" events.
- In the Instance Viewer view, add the code to the "On instance UI launched" event.
Add the following line of code to the specified events in the corresponding views, as follows:
```
this.ui.getSibling("Vertical_Layout1").setVisible(true,true);
```
where Vertical_Layout1 is the control ID of the vertical layout container.
- In the Task Viewer view, add the code to the "On task closed" and "On service closed" events.
- In the Instance Viewer view, add the code to the "On instance closed" event.

If the Show the breadcrumb trail option is selected in the configuration properties for the Task Viewer or Instance Viewer views, you can return to the task list or the instance list through the navigation bar without needing to reload.