Cloud Software Group, Inc. EBX®
Documentation > Reference Manual > Integration
Navigation mode Documentation > 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.

##### See also

- Supported web browsers

## 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:

- Dataspace or snapshot

- Dataset

- Node

- Table or a published view

- Table record

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

- Scope

##### See also

- firstCallDisplay

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

- Perspective

## 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 (deprecated). | 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, hierarchical, or tile 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, the hierarchical or the tile 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, a hierarchy or a tile 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, hierarchical or tile). | 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/users[./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/users&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/users[./login="admin"]&service=@compare&compare.branch=ebx-directory&compare.instance=ebx-directory&compare.xpath=/directory/users[./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