TIBCO EBX®
Documentation > Reference Manual > Integration
Navigation modeDocumentation > Reference Manual > Integration

Using TIBCO EBX® as a Web Component

Overview

EBX® can be used as a user interface Web Component, called through the HTTP protocol. An EBX® Web Component can be integrated into any application that is accessible through a supported web browser. This method of access offers the major benefits of EBX®, such as user authentication, data validation, and automatic user interface generation, while additionally providing the ability to focus user navigation on specific elements of the repository.

Typical uses of EBX® Web Components include integrating them into the intranet frameworks of organizations or into applications that manage the assignment of specific tasks to users.

Integrating EBX® Web Components into applications

A web application that calls an EBX® Web Component can be:

  1. A non-Java application, the most basic being a static HTML page.

    In this case, the application must send an HTTP request that follows the EBX® Web Component request specifications.

  2. A Java application, for example:

    • A Java web application running on the same application server instance as the EBX® repository it targets or on a different application server instance.

    • An EBX® User service or a Custom widget, in which case, the new session will automatically inherit from the parent EBX® session.

Note

In Java, the recommended method for building HTTP requests that call EBX® web components is to use the class UIHttpManagerComponent in the API.

Repository element and scope selection

When an EBX® Web Component is called, the user must first be authenticated in the newly instantiated HTTP session. The Web Component then selects a repository element and displays it according to the scope layout parameter defined in the request.

The parameter firstCallDisplay may change this automatic display according to its value.

The repository elements that can be selected are as follows:

The scope determines how much of the user interface is displayed to the user, thus defining where the user is able to navigate in the session. The default scope that the Web component uses is the smallest possible depending on the entity or service being selected or invoked by the request.

See also
See also

It is also possible to select a specific perspective as well as a perspective action.

By default, the selection of the element is done in the context of the perspective of the user if the scope is "full".

See also

Combined selection

A URL of a Web component can specify a perspective and an action or an entity (dataspace, dataset, etc). Thus, for a Web component that has specified in its URL a perspective and an entity (but no action), if an action of the perspective matches this entity, then this action will be automatically selected.

Otherwise, if no action matches this entity, no action will be selected but the entity is opened regardless.

If an action is specified at the same time than an entity, this last is ignored and the action will be selected.

Specific case

If the target entity is a record and if an action is on the table that contains this record, then this action will be selected and the record will be opened inside the action.

In the same way, if a workflow work item is targeted by the web component, and if an action on « inbox » exists in the perspective, then this action will be selected and the work item will be opened inside it.

Known limitations

If the Web component specifies a predicate to filter a table, the perspective action must specify the exact same predicate to be selected.

In the same way, if the perspective action specifies a predicate to filter a table, the Web component must specify the exact same predicate to establish the match.

Request specifications

Base URL

In a default deployment, the base URL must be of the following form:

http://<host>[:<port>]/ebx/

Note

The base URL must refer to the servlet FrontServlet, defined in the deployment descriptor /WEB-INF/web.xml of the web application ebx.war.

User authentication and session information parameters

Parameter

Description

Required

login and password, or a user directory-specific token

Specifies user authentication properties. If neither a login and password pair nor a user directory-specific token is provided, user will be required to authenticate through the repository login page.

See Directory for more information.

No

trackingInfo

Specifies the tracking information of the new session. Tracking information is logged in history tables. Additionally, it can be used to programmatically restrict access permissions.

See AccessRule for more information.

No

redirect

The URL to which the user will be redirected at the end of the component session, when they click on the button 'Close'. The close button is always displayed for record selections, but whether or not it is displayed for all other cases must be specified using the parameter closeButton.

For more information, see Exit policy.

No

locale

Specifies the locale to use. Value is either en-US or fr-FR.

No, default is the locale registered for the user.

Entity and service selection parameters

Parameter

Description

Required

branch

Selects the specified dataspace.

No

version

Selects the specified snapshot.

No

instance

Selects the specified dataset. The value must be the reference of a dataset that exists in the selected dataspace or snapshot.

Only if xpath or viewPublication is specified.

viewPublication

Specifies the publication name of the tabular or hierarchical view to apply to the selected content.

This publication name is the one declared during the publication of the view. It can be found in the 'Administration' area under Views configuration > Views.

All settings of the view, that is, its filters, sort order, and displayed columns, are applied to the result. A dataspace and a dataset must be selected in order for this view to be applied. The target table selection is not necessary, as it can be automatically determined based on the definition of the view. This parameter can be combined with the predicate specified in the xpath parameter as a logical 'AND' operation.

No

xpath

Specifies a node selection in the dataset.

Value may be a valid absolute path located in the selected dataset. The notation must conform to a simplified XPath, with abbreviated syntax.

It can also be a predicate surrounded by "[" and "]" (to be encoded using %5B and %5F respectively) if a table can be automatically selected using other Web Component parameters (for example, viewPublication or workflowView).

For XPath syntax, see XPath supported syntax

See UIHttpManagerComponent.setPredicate for more information.

No

service

Specifies the service to access.

For more information on built-in User services, see Built-in services.

In the Java API, see ServiceKey for more information.

No

workflowView

Specifies the workflow section to be selected.

See WorkflowView for more information.

No.

perspectiveName

Specifies the name of the perspective to be selected.

If this parameter is specified, the scope parameter can have only two values: full and data.

Only if perspectiveActionId or perspectiveActionName is specified.

perspectiveActionId

Deprecated. Please consider using perspectiveActionName instead.

Specifies the identifier of the perspective action to be selected.

No.

perspectiveActionName

Specifies the unique name of the perspective action to be selected.

No.

Layout parameters

Parameter

Description

Required

scope

Specifies the scope to be used by the web component. Value can be full, data, dataspace, dataset or node.

See UIHttpManagerComponent.Scope for more information.

No, default will be computed to be the smallest possible according to the target selection.

firstCallDisplay

Specifies which display must be used instead of the one determined by the combination of selection and scope parameter.

Possible values are:

  • auto: The display is automatically set according to the selection.

  • view: Forces the display of the tabular view or of the hierarchical view.

  • record: If the predicate has at least one record, forces the display of the first record in the list.

For example,

firstCallDisplay=view

firstCallDisplay=view:hierarchyExpanded

firstCallDisplay=record

firstCallDisplay=record:{predicate}

See UIHttpManagerComponent.setFirstCallDisplay for more information.

See UIHttpManagerComponent.setFirstCallDisplayHierarchyExpanded for more information.

See UIHttpManagerComponent.setFirstCallDisplayRecord for more information.

No, default will be computed according to the target selection.

closeButton

Specifies how to display the session close button. Value can be logout or cross.

See UIHttpManagerComponent.CloseButtonSpec for more information.

No. If scope is not full, no close button will be displayed by default.

dataSetFeatures

Specifies which features to display in a UI service at the dataset level or a form outside of a table.

These options pertain only to features in the workspace. It is recommended to use this property with the smallest scope possible, namely dataset or node.

Syntax:

<prefix> ":" <feature> [ "," <feature>]*

where

  • <prefix> is hide or show,

  • <feature> is services, title, save, or revert.

For example,

hide:title

show:save,revert

See UIHttpManagerComponent.DataSetFeatures for more information.

No.

viewFeatures

Specifies which features to display in a tabular or a hierarchy view (at the table level).

These options pertain only to features in the workspace. It is recommended to use this property with the smallest scope possible, namely dataset or node.

Syntax:

<prefix> ":" <feature> [ "," <feature>]*

where

  • <prefix> is hide or show,

  • <feature> is create, views, selection, filters, services, refresh, title, or breadcrumb.

For example,

hide:title,selection

show:service,title,breadcrumb

See UIHttpManagerComponent.ViewFeatures for more information.

No.

recordFeatures

Specifies which features must be displayed in a form at the record level.

These options pertain only to features in the workspace. It is recommended to use this property with the smallest scope possible, namely dataset or node.

Syntax:

<prefix> ":" <feature> [ "," <feature>]*

where

  • <prefix> is hide or show,

  • <feature> is services, title, breadcrumb, save, saveAndClose, close, or revert.

For example,

hide:title

show:save,saveAndClose,revert

See UIHttpManagerComponent.RecordFeatures for more information.

No.

pageSize

Specifies the number of records that will be displayed per page in a table view (either tabular or hierarchical).

No.

startWorkItem

Specifies a work item must be automatically taken and started. Value can be true or false.

See ServiceKey.WORKFLOW for more information.

No. Default value is false, where the target work item state remains unchanged.

Example calls to an EBX® Web Component

Minimal URI:

http://localhost:8080/ebx/

Logs in as the user 'admin' and selects the 'Reference' dataspace:

http://localhost:8080/ebx/?login=admin&password=admin&branch=Reference

Selects the 'Reference' dataspace and accesses the built-in validation service:

http://localhost:8080/ebx/?login=admin&password=admin&branch=Reference&service=@validation

Selects the roles table in the default directory:

http://localhost:8080/ebx/?login=admin&password=admin&branch=ebx-directory&instance=ebx-directory&xpath=/directory/roles

Selects the record 'admin' in the default directory:

http://localhost:8080/ebx/?login=admin&password=admin&branch=ebx-directory&instance=ebx-directory&xpath=/directory/user[./login="admin"]

Note

For clarity purposes, the above URLs are not encoded and this can make them incompatible with some application servers.

Accesses the interface for creating a new user in the default directory:

http://localhost:8080/ebx/?login=admin&password=admin&branch=ebx-directory&instance=ebx-directory&xpath=/directory/user&service=@creation

Compares the record 'admin' in the default directory with the record 'jSmith':

Compares the record 'R1' in the dataset 'instanceId' in the dataspace 'Reference' with the record 'R0':

http://localhost:8080/ebx/?login=admin&password=admin&branch=ebx-directory&instance=ebx-directory&xpath=/directory/user[./login="admin"]&service=@compare&compare.branch=ebx-directory&compare.instance=ebx-directory&compare.xpath=/directory/user[./login="jSmith"]

Note

For clarity purposes, the above URLs are not encoded and this can make them incompatible with some application servers.

Documentation > Reference Manual > Integration