The context object

The context object provides access to helper functions, such as a callback to fire a named boundary event.

Properties

Through the context object, you can access its properties.
Property Description
context.binding Provides access to the data object that is bound to the current view. To access the data, use the following call:
this.context.binding.get("value")
Where value is a special property name that returns the bound data object.
For example, if a view is bound to local.phoneBook.title, the view can get the title by using the following code:
if (!! this.context.binding){
	var title = this.context.binding.get("value")
}
context.contextRootMap Contains the values of different context roots of the workflow servers. Use this API to construct the URL that your views use to connect to these servers. The object has the following properties:
  • rest (String). A workflow REST server, such as "/rest/bpm/wle"
  • processPortal (String).IBM® Process Portal server, such as "/ProcessPortal"
context.element Contains the root DOM element of the view. The view must not delete this DOM element. Views that are defined in the layout are children of this root element. Generally, the view uses this root DOM element to locate its own content.
Note: Multiple instances of the same view can be on the same HTML page. Use this root DOM element to scope your search.
context.isWorkflowPXServer() Checks whether the server is a Workflow Process Service server.
context.options Provides access to the configuration options of the view. These configuration options include the properties that users can set for the view such as the label for a button control and metadata properties.
context.subview[viewid]
Returns an object with the div ID of the subview as a property name. In a non-repeating scenario, there is usually only one property. Generally context.getSubview() is a more convenient function to use.
  • viewid (String). The view ID or control ID.
For more information, see Example: Get and use a domNode and Example: Get a div ID.
context.bpm.system Provides access to the following system values:
  • baseTextDirection (String). The text direction preference of the user.
  • (Deprecated) caseFolderId (String). The ID of the case folder if the current human service is running in the context of a case instance; otherwise the returned value is an empty string. Use processInstanceFolderId instead.
  • (Deprecated) caseFolderServerName(String). The name of the server associated with the instance in which the client-side human service runs. Use processInstanceFolderServerName instead.
  • enablingDocumentId (String). The ID of the document that activated the case activity whose implementation the current human service belongs to. An empty string is returned if the triggering activity was not activated by a document or is not a case activity.
  • processInstanceFolderId (String). The ID of the case folder associated with the process instance.
  • processInstanceFolderServerName (String) The name of the server associated with the process instance case folder.
  • instanceId (String). The instance ID of the BPD in which the coach is running.
  • paId (String). The ID of the process application or toolkit that contains the coach definition.
  • parentCase.caseId (String). The parent case identifier that is associated with the process instance.
  • parentCase.caseServerId (String). The identifier of the server associated with the parent case instance. Not intended to be displayed to end users.
  • parentCase.parentActivityId (String). The parent activity identifier that is associated with the process instance.
  • paShortName (String). The acronym of the process application or toolkit that contains the coach definition.
  • snapshotId (String). The ID of the process application or toolkit snapshot that contains the coach definition.
  • runtimeRootSnapshotId (String). The ID of the process application or toolkit snapshot in which the coach is running.
  • startingDocumentId (String). The ID of the case starting document if the current human service is running in a case instance that was started by a document filed event; otherwise the returned value is an empty string.
  • taskId (String). The ID of the current task or process in which the coach is running.
  • user_id (String). The ID of the user.
  • user_loginName (String). The name that the user used to log in.
  • user_fullName (String). The full name of the user.
  • user_localeCountry (String). The locale of the user.
  • user_localeLanguage (String). The language of the user.
context.bpm.system.settings Provides access to the following properties related to timer-based refreshing for views:
  • TimerCoachViewEnabled (Boolean). This setting specifies the active or inactive status of the timer coach control used on the default instance details user interface to trigger automatic refreshes. By default, this setting is true, which means the timer control is active.
  • TimerCoachViewRefreshInterval (Integer). This setting specifies the frequency of refresh requests triggered by the timer coach control. The value is defined in seconds. The default value is-1, indicating that the value used in the coach control configuration is to be used. Administrators can override the settings specified in the models using this property.
  • MinimumCoachViewRefreshInterval (Integer). This setting defines the minimum time between refresh requests handled by the instance user interface coach controls. The value is defined in seconds. The default value is 10, which means that refresh calls to the server are only sent if at least 10 seconds have passed since the last refresh call.
context.bpm.team.manager Lists the teams that the current user is manager of. The list ("[]") is empty by default. Each item in the list for context.bpm.team.manager is an object that contains the following properties:
  • name (String). The name of the team
  • id (String). The unique identifier of the team.
context.bpm.team.member Lists the teams that the current user is member of. The list ("[]") is empty by default. Each item in the list for context.bpm.team.member is an object that contains the following properties:
  • name (String). The name of the team
  • id (String). The unique identifier of the team.
context.viewid Contains the unique identifier for this view definition. Multiple view instances might have the same viewId. For more information, see context.getSubview(viewId, requiredOrder).

Functions

Through the context object, you can access its functions.
Function Description
context.bindingType() Returns the type of the data binding.
context.broadcastMessage(message) Broadcasts the supplied message.
Important: Do not use this API to send sensitive or confidential information.
  • message (Object). An object that has a name property.
context.cancelBoundaryEvents() Cancels the boundary events that have not been sent to server. If a callback function was supplied when the boundary event was triggered, the coach framework calls the callback function to update the status of the boundary event. For more information, see the context.trigger(callback) function.
context.containDiffLoopingContext() Returns a value of true if the following conditions are true:
  • A view that is bound to a list contains a content box that contains a view.
  • This contained view is bound to the currentItem of a different list.
For example, the API returns a value of true for the following structure:
TableView (bind to ListA[])
	ContentBox
		TextView (bind to ListB.currentItem)

The framework displays a message at run time when there is a mismatch in list lengths. For example, the message occurs for the previous example if ListA has four items and ListB has three items. For more information, see Data binding for views.

You use containDiffLoopingContext() to, for example, determine whether to disable the add-and-delete capability of a table during the runtime even if a user specifies to enable the add-and-delete capability.

Important: If the view that contains a view-managed content box is bound to a list that is not empty, do not call this API between deleting a domNode of the content box and the rendering of the first repeating element. The return value might not be accurate.
context.createView(domNode, index, parentView) Creates a view instance and any subview instances under the specified DOM element, which is usually a content box div.
  • domNode (Element). The HTML DOM element of the content box or node of any view.
  • index (Integer) (optional). Indicates the position so that data binding and configuration indexes can be adjusted or zero-indexed.
  • parentView (CoachView) (optional). The view instance of the parent view; alternatively, the parent view can be computed based on the document order.

If domNode is the node of any view other than a content box, the framework creates a single instance of the view and returns it. If (domNode is the node of a context box, the framework creates view instances for all the views that are owned by the content box. The framework recursively creates views for all the framework-managed content boxes that are owned by the content box that is specified by the domNode parameter. The framework then returns an array of these view instances.

The following code snippet shows how to create a content box view.
var location = 5;
var trElement = document.createElement("tr");
// rowTemplate is the contentBox that contains some nodes
// the view nodes define table columns.
var oneDiv = this.rowTemplate.cloneNode(true);
trElement.appendChild(oneDiv);
this.tableElement.appendChild(trElement);
var viewArray = this.context.createView(oneDiv, location);
For more information, see Example: Get and use a domNode.
context.deleteView(domNode) Deletes the view instance and any subview instances, starting from the specified DOM element.
  • domNode (Element). The HTML DOM element of content box or the node of any view.
The following code snippet shows how to delete a view instance:
var nodeToDelete = document.getElementById("myId");
this.context.deleteView(nodeToDelete);
nodeToDelete.parentNode.removeChild(nodeToDelete);
For more information, see Example: Get and use a domNode.
context.getDomNode(uniqueViewId, optParam) Returns the first match of the DOM node that has its data-ibmbpm_uniqueViewId property that has the specified ID or null if there is no match. The search starts with the parent DOM node of the this.context.element unless you pass in a different start node by using optParam.startNode and the search checks only the immediate children of the start node unless you pass in optParam.deepSearch=true.
  • uniqueViewID (String). The value to search for in the data-ibmbpm_uniqueViewId of the domNode.
  • optParam (Object) (optional). Parameters that modify the scope of the search.
context.getInheritedVisibility() Returns a String containing the value of the visibility setting of the ancestors of the view that is calling this function. If visibility values of all of its ancestors are set to DEFAULT, the function returns EDITABLE.
context.getOptions(viewDomNode) Returns the options object for the view given its viewDomNode. The options are returned even when the view represented by viewDomNode is not yet constructed. Typically, use this API in a view to look at the configuration options (such as label or visibility ) of one of its child views before it is created.
  • viewDomNode (Element). The HTML DOM element of the child view.

The following code snippet is an example of how you could use this API:

var childOptions = this.context.getOptions(childViewDomNode);
var childLabel = childOptions._metadata.label.get("value");
childOptions._metadata.visibility.set("value", "READONLY");
context.getStyle() Returns the currently applied positioning information specified in the Positioning properties of the coach designer. The currently applied positioning is based on an inheritance model where settings for larger screen width are applied to smaller screen sizes if nothing is specified for the smaller screen sizes. If a given property is not specified for any screen size, null is returned. The following properties are defined:
  • width (String)
  • height (String)
  • min-width (String)
  • min-height (String)
  • margin (String)
  • padding (String)
  • overflow (String)
context.bind(type, callbackFunc, scopeObject) Registers a callback function to receive a change notification associated with the specified type. For now, only thestyle type is supported. Any other values will cause an exception to be thrown. This setting change can be a design-time change in the positioning settings or a change in the run-time screen size.

Normally, the callback function invokes the context.getStyle() method to get the currently applied positioning.

Only one notification or callback is triggered even if more than one positioning property is changed. This function returns an object that can be used to unregister the callback. The returned object contains a unbind() method that takes no parameter.
  • type(String). Currently, the only supported value is style.
  • callbackFunc (Function). The function to be invoked as a callback. This function has no type parameter.
  • scopeObject (Object) . (Optional) Indicates the "this" to be used when invoking the callback function. If it is not specified then no scope is defined.
context.setGroupNotification()

When enabled, allows a view to receive notification of data binding and configuration option changes in a single notification for all changes within the current thread.

The event object that is passed into the callback contains a single property type of value groupNotification. It does not have any information about the individual changes. Views should retrieve the latest binding and configuration option values after receiving the group notification.

The following parameters are defined:
  • enable(boolean). A value of true enables the group notification. A value of false disables the group notification.
  • callback (function). Specifies the callback to call when group notification is enabled. When enable is set to set to false, all previous callbacks will be removed.
  • scope(Object) The function scope when the callback is invoked.
context.getSubview(viewId, requiredOrder) Returns the subview instance given the subview ID. This method is similar to context.subview[viewid] except that the return value is an array of subview instances.
  • viewId (String). The view ID or control ID of the subview
  • requiredOrder (boolean) (optional). Indicates whether the array that is returned must maintain the same order as in the DOM tree. The default value is false.

The call this.context.getSubview("viewid") returns an unsorted array of subview objects. The call this.context.getSubview("viewid", false) returns the same array. The only difference between the two calls and the function call this.context.getSubview("viewid", true) is that this.context.getSubview("viewid", true) returns an array of subview objects whose order matches the order of the DOM nodes in the DOM tree.

For more information, see Accessing a child view by using a control ID.
context.htmlEscape(text) Escapes the specified text. This function is used to avoid potential cross-site scripting (XSS) attacks.
  • text (String). The text to escape. The escaped text is returned.
context.isTrustedSite(origin) Returns true if origin matches the protocol, host, and port of the coach or a site listed on the allowlist. For example, a view receives a postMessage event. The view can check the origin of the event by calling this API using event.origin as the parameter.
  • origin (String). The protocol and host of the URL. The origin must also include the port if the URL does not use the default port for the protocol. Examples of origin include https://bpm1.mycompany.com:9080, https://bpm2.mycompany.com:9443, and http://bpm3.mycompany.com.
context.parentView() Returns the parent view instance or null if there is no parent view. During the invocation of load(), the parentview object is created but not fully initialized. One reason it is not initialized is that load() of the parent view is called after the current load() function. Because the parentview object is not fully initialized, avoid calling this function in the load() function.
context.refreshView() Forces the view and all its subviews to rebind. As a result, the change() callback is called, which causes the view (and all its subviews) to refresh.
context.setDisplay(isDisplay, domNode) Shows or hides the specified DOM element by removing or adding a CSS class that sets display:none. When the domNode is hidden, the parent coach or view does not reserve the space that domNode would occupy.
  • isDisplay (Boolean). The value true shows the domNode; the value false hides the domNode
  • domNode (DOMElement) (optional). If not specified, the root element of the current view is used.
For more information, see Example: Get and use a domNode.
context.setUniqueViewId(uniqueViewId, targetNode) Sets the uniqueViewId in the data-ibmbpm_uniqueViewId property of the targetNode. If the call does not include the targetNode, this function sets the property for the DOM node of the this.context.element.
  • uniqueViewId (String). The ID to be set.
  • targetNode (Element) (optional). The HTML DOM element that contains the data-ibmbpm_uniqueViewId property to be set.
context.setVisibility(isVisible, domNode) Shows or hides the specified DOM element by removing or adding a CSS class that sets display:hidden. When the domNode is hidden, the parent coach or view reserves the space that domNode would occupy.
  • isVisible (Boolean). The value true shows the domNode; the value false hides the domNode
  • domNode (Element) (optional). If not specified, the root HTML DOM element of the current view is used.
context.subscribeValidation() Registers the view to receive the validation errors of descendant views that are bound to a different business object than the current view. These errors are contained in the errors_subscription list of the error event object. Views that do not have a data binding, such as the Tab stock control, can use this API to receive validation errors.
context.trigger(callback, options) Fires a named boundary event.
  • callback (function) (optional)

    If a callback function is supplied, the coach framework calls the callback function when the boundary event has one of the status values described in the following table. Whether the callback function is called is also dependent on the value of the options parameter. If the boundary event fails, the callback function is not resubmitted or retried in the error state. The callback function has a response object as a single parameter: {status: boundaryEventStatus}.

    The boundaryEventStatus parameter has one of the following values:
    Value Description
    executed The boundary event was successfully run.
    unqualified The context.element does not have a data-eventid property and the boundary event cannot be run.
    cancelled The boundary event is canceled because context.cancelBoundaryEvents() was called.
    abandoned The boundary event is abandoned because the coach framework was unable to process it. For example, the framework could not communicate with the server or the coach was shutting down.
  • options (Object) (optional)
    This parameter has a single property: callBackForAll (Boolean). If any of the following conditions apply, the callback is only invoked when the boundary event was successfully run (executed):
    • The options parameter does not exist.
    • The options parameter exists but does not contain the callBackForAll property.
    • The options parameter exists and it contains the callBackForAll property but the property is set to false.

    If the property is set to true, the callback is invoked not only for those boundary events that ran (executed) successfully, but also for the ones of unqualified, cancelled, and abandoned status.
context.triggerCollaboration(payload) (Deprecated.) Fires a custom collaboration event. The custom message is sent to the browser of a collaborating user. The corresponding view on the collaborating browser receives the collaboration() callback with event.type = "custom".
  • payload (Object). The object that contains the custom message contents.
context.unsubscribeValidation() Unregisters the view so that it no longer receives errors in the errors_subscription list. The view still receives the errors list if it exists.

Example: Get and use a domNode

Many functions of the context object take a document node (domNode) as an argument. The following code example shows how to get a domNode and use it in a function.

 1  var subview = this.context.getSubview("subviewID", "true")[5];
 2  var subviewDomNode = subview.context.element;
 3  this.context.deleteView(subviewDomNode);
  •  1  The parameter subviewID is the control ID of the subview and corresponds to the value for the property data-viewid of the <div></<div> tag of the subview instance. The function getSubview(subViewID) returns an array of subviews. In this example, the intent is to get the sixth element in the index of arrays. The parameter true ensures that the objects of the array are returned in the same order as the DOM.
  •  2  Get the domNode of the subview element that is returned in step 1.
  •  3  Delete the subview by using the domNode that step 2 returns.

Example: Get a div ID

To get the div ID of an element, use the syntax this.context.element.id

To get the ID of a subview, first get the domNode of the subview and then use .id.

 1  var subview = this.context.getSubview("subviewID", "true")[5];
 2  var subviewDomNode = subview.context.element;
 3  var subViewDomId = subviewDomNode.id; // This gives you the ID of the subview
  •  1  The parameter subviewID is the control ID of the subview and corresponds to the value for the property data-viewid of the <div></<div> tag of the subview instance. The function getSubview(subViewID) returns an array of subviews. In our example, we want the sixth element in the index of arrays. The parameter true ensures that the objects of the array are returned in the same order as the DOM.
  •  2  Get the domNode of the subview element that is returned in step 1.
  •  3  Get the ID of the subview.