Cloud Software Group, Inc. EBX®
TIBCO EBX® Documentation
Navigation mode TIBCO EBX® Documentation

# Legacy user services

##### Attention

This documentation is about an outdated API. For new developments, it is strongly recommended to use the new user service API available from 5.8.0. Please refer to the current documentation on user services.

## Overview

A user interface service (User service) is an HTTP resource, such as a JSP or Java servlet, that is integrated into TIBCO EBX®. Through User services, users can perform specific and advanced functions directly from the user interface.

The following types of User services exist:

- Built-in User services provided by EBX®,

- Custom User services on datasets declared in the data model,

- Custom User services on dataspaces or snapshots that are declared in a module and are available to all dataspaces or snapshots. These can be disabled on specific dataspaces or snapshots using service permissions.

Additionally, to integrate a User service with a workflow or a perspective, it needs to be declared for this usage. See Integration of User services with workflows and perspectives in this chapter for more information.

### Accessing User services

Depending on the nature of User services and their declarations, users can access them in several ways:

- Directly in the EBX® user interface, from a Services or Actions menu,

- From a data workflow, in which case the User service must be declared as an interaction,

- For a perspective, in which case the User service must be declared in an action menu item,

- From the Java API, using ``UIHttpManagerComponent.setService``.

## User services on datasets

User services can be declared in a specific data model contained in a module, which makes them available to datasets that implement that data model. These User services can be defined to be executable on the entire data set, or on tables or record selections in the dataset. They are launched in the user interface as follows:

- For datasets, from the Services menu in the navigation pane.

- For tables, from the Actions menu in the workspace.

- For record selections, from the Actions menu in the workspace.

### Common use cases

Common uses for User services on datasets, tables, and record selections are:

- Updating a table or a user selection of table records. For example, the field values of a column 'Product price' can be adjusted by a ratio that is specified by the user.

- Importing data from an external source into the current data set.

- Exporting the selected records of a table.

- Implementing specific events in the life cycle of MDM entities. For example, the creation of a product, which impacts several tables, or the "closure" of a product at a given date.

- Displaying statistics on a table.

### Declaration and configuration

##### Attention

From version 5.8.0 of EBX®, it is recommended to use the user service API instead of the user services defined in a data model. The user service API provides more features and a better integration of user services. As a consequence, no further evolution will be made on the user services defined in a data model and the user service section is no longer displayed by default in the Data Model Assistant on new data models and on existing data models that do not define user services. However, the new property `Enable user services (old API)` available in the section `Global properties` allows to enable the definition of user services in a data model.

See `UserServiceDeclaration` and Data model properties for more information.

User services are available on `embedded` data models, published using the Data Model Assistant, and `packaged` data models.

For embedded data models, the definitions of user services are embedded in EBX®'s repository and linked with a publication. That is, when publishing an embedded data model, definitions of user services are embedded in the publication of the data model and managed by EBX®.

For packaged data models, the definitions of user services are set in a dedicated `XML` document and must be named as the data model and end with the keyword `_services`. For instance, if a data model is named `catalog.xsd`, then the XML document containing the definition of the user services must be named `catalog_services.xml`. This `XML` document must also be stored in the same location as the data model. The user services document is automatically loaded by EBX® if a file complying with this pattern is found when compiling a data model. This document must comply with the XML Schema document `userServices_1.0.xsd` that defines the structure of the user services document. The XML Schema document file is provided for the module `ebx-root-1.0`, at the path `/WEB-INF/ebx/schemas`.

##### Note

Since EBX® 5.7.1, user services are defined in a dedicated XML document. Previous definitions, embedded in XML Schema documents, are still supported but are deprecated. The Data Model Assistant can be used to migrate existing data models. That is, the definition of user services embedded in the data models being edited by the Data Model Assistant will be automatically migrated to the next publication.

#### Example

The following example declares the user service 'Distribution' on a table:

    <?xml version="1.0" encoding="UTF-8"?>
    <services xmlns="urn:ebx-schemas:userServices_1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema" xsi:schemaLocation="urn:ebx-schemas:userServices_1.0 https://schema.orchestranetworks.com/userServices_1.0.xsd">
        <service name="Distribution">
            <documentation xml:lang="en-US">
                <label>Distribute data for table 'Product'</label>
                <description>This service distributes data for table 'Product'</description>
            </documentation>
            <resourcePath>/Distribution/Distribution.jsp</resourcePath>
            <orderInMenu>1</orderInMenu>
            <activation>
            	<onDataModel>
            		<path>/root/Product</path>
            	</onDataModel>
            </activation>
        </service>
    </services>

#### Properties

Property | Definition | Mandatory
--- | --- | ---
`name` | Attributes that specify the name of the user service. | Yes
`resourcePath` | Element that identifies the JSP or servlet resource to be called. The identifier is a path relative to the root of the EBX® module containing the data model. It must begin with '/'. ##### See also `ServiceContext` ServletContext.getRequestDispatcher(String) | Yes.
`activation/onDataModel/path` | Element that specifies where the User service will be available. Several paths can be specified using this element several times. Each path must be the absolute XPath notation of the node. It is possible to activate the User service on nodes or on datasets. The path '/' activates the User service globally on the dataset. On `osd:table`, an additional syntax allows you to specify whether the User service is activated globally on the table or on record selections. If the path to the table is `/root/myTable`: /root/myTable activates the User service globally on the table. /root/myTable{n} activates the User service only if exactly 'n' records are selected, where 'n' is a positive integer. /root/myTable{+} activates the User service if one or more records are selected (an unbounded selection). | No. If not defined, activates as a global User service that is not attached to a particular node.
`activation/onDataModel/pathRegExp` | Element that specifies where the User service will be available based on a regular expression. The User service will be available on all nodes whose full path in the data model match the regular expression. The format of the regular expression is defined in the Java specification. | No. When set, it is exclusive with `activation/onDataModel/path` element.
`permissions` | Element that specifies a Java class that implements `ServicePermission`. The Java class is specified using the attribute `class`. | No. If not defined, service has no permission restriction.
`confirmation` | Element that specifies a confirmation message or that suppresses user confirmation before the User service is launched. See Confirmation messages below. | No. If not defined, a default confirmation message is displayed.
`displayInMenu` | Element that specifies if the service is displayed in UI menus and buttons. | No. Default value is true.
`orderInMenu` | Element that specifies the position of this User service among the User services defined in the schema. This position is used for the display order of User services. | No
`group` | Element that specifies the group to which this service belongs. See User Service Groups in this chapter for more information. | No. If undefined, the service will be displayed at the root level.
`defaultPermission` | Element that specifies the service default activation policy. See Default permission in this chapter for more information. Allowed values are: `enabled` and `disabled`. | No. If undefined, the service is enabled by default.

#### Confirmation messages

By default, the user is shown a generic message and must confirm the execution of the User service. The element `osd:confirmation` allows you to specify a custom localized confirmation message:

    <services ...>
    	<service name="DummyService">
    		...
    		<confirmation>
    			<label xml:lang="fr-FR">
    			Voulez-vous lancer le service ?
    			</label>
    			<label xml:lang="en-US">
    			Do you want to launch the service ?
    			</label>
    		</confirmation>
    		...
    	</service>
    	...
    </services>

The element `confirmation` can also be used to disable the user confirmation entirely with the attribute `disable="true"`.

## Global User services on all dataspaces and snapshots

A User service can also be declared in such a way that they are available to all dataspaces and/or snapshots in the repository. The purpose of such services is to write high-level core business procedures that involve actions such as merges, imports and exports, and validations.

### Common use cases

Common uses for User services on dataspaces and snapshots are:

- Importing data from an external source.

- Exporting data to multiple systems.

- Validating a dataspace or snapshot before exporting it

- Sending messages to monitoring systems before performing a merge

### Declaration and configuration

The Java applications, JSPs, and servlets for User services on data spaces or snapshots must be declared in a module. It is recommended to create a dedicated module for User services on dataspaces and snapshots; these User services will be available on all dataspaces and snapshots, but may have a life cycle that is independent of the data life cycle.

User services on dataspaces and snapshots must be declared in the module configuration file `module.xml`, under the element `services/service`, where `services` is the root of all User services declared in the module.

##### See also

- Packaging EBX® modules

#### Example

The following example declares a User service that validates and merges a dataspace:

    <service name="AdvancedMerge" defaultPermission="disabled">
    	<resourcePath>/services/advancedMerge.jsp</resourcePath>
    	<type>branch version</type>
    	<documentation xml:lang="en-US">
    		<label>Merge/Validate</label>
    		<description>Merge current branch to parent if valid.</description>
    	</documentation>
    	<confirmation>
    		<label>A default confirmation message.</label>
    		<label xml:lang="en-US">An English confirmation message.</label>
    		<label xml:lang="fr-FR">Un message de confirmation en français.</label>
    	</confirmation>
    </service>

#### Properties

Property | Definition | Mandatory
--- | --- | ---
`name` | Attribute that specifies the name of the User service. This name must be unique within the scope of a module. | Yes
`resourcePath` | Element that identifies the JSP or servlet resource to be called. The identifier is a path relative to the root of the EBX® module containing the schema. It must begin with '/'. ##### See also `ServiceContext` ServletContext.getRequestDispatcher(String) | Yes
`type` | Element that defines the availability of the User service as a whitespace-delimited list. 'branch', which makes the User service available to dataspaces 'version', which makes the User service available to snapshots 'workflow', which makes the User service available to be defined for user tasks in workflow models 'perspective', which makes the User service available to be defined for action menu items in perspective configurations. If the list includes neither 'branch' or 'version', the User service will not be available in all Services menus. If the value 'workflow' is specified, the User service will be available for workflows on any dataspace or snapshot. If the value 'perspective' is specified, the User service will be available for perspectives on any dataspace or snapshot. See Services on dataspaces or snapshots for data workflows or perspectives | Yes
`documentation` | Localized label and description of the user service, displayed in the menu where the user service appears. | No
`confirmation` | Element that specifies a confirmation message or that suppresses user confirmation before the User service is launched. See Confirmation messages below. | No. If not defined, a default confirmation message is displayed.
`group` | Element that specifies the group to which this service belongs. See User Service Groups in this chapter for more information. | No. If undefined, the service will be displayed at the root level.
`defaultPermission` | Attribute that specifies the service default activation policy. See Default permission in this chapter for more information. Allowed values are: `enabled` and `disabled`. | No. If undefined, the service is enabled by default.

#### Confirmation Message

By default, the user is shown a generic message and must confirm the execution of the User service. The element `confirmation` allows you to specify a custom localized confirmation message:

    <service name="AdvancedMerge">
    	<resourcePath>/services/advancedMerge.jsp</resourcePath>
    	<type>branch version</type>
    	<documentation xml:lang="en-US">
    		<label>Merge/Validate</label>
    		<description>Merge current branch to parent if valid.</description>
    	</documentation>
    	<confirmation disable="true"/>
    </service>

The element `confirmation` can also be used to disable the user confirmation entirely with the attribute `disable="true"`.

## Integration of User services with workflows or perspectives

### Overview

In order to make a User service available to workflows or perspectives, an additional declaration must be made in the configuration file `module.xml` of the module that implements the User service.

User services that are integrated into workflows or perspectives benefit from a declarative and secure specification for a "component-oriented" approach

#### Workflow

Once this declaration has been made, the User service becomes available in the Workflow Models area where the user defines user tasks. The user then maps the input parameters and output parameters that are specified in the module configuration file `module.xml`.

Once the workflow model has been published and a workflow has been started, for every user starting a work item, the corresponding user session on the application server will be associated with a persistent interaction object that contains the valued input parameters. Through the Java API, the running User service can access these input parameters and adapt its behavior accordingly. Once the corresponding work item and associated User services are complete, the completion method must be invoked with the output parameters specifying the resulting state of the work item. For more information, the developer of the User service should read the JavaDoc of the interface ``SessionInteraction``.

#### Perspective

Once this declaration has been made, the User service becomes available for action menu items. The perspective administrator then maps the input parameters that are specified in the module configuration file `module.xml`. Output parameters are not used by perspectives but can be defined in `module.xml` if the User service is also used for workflows.

### Common properties for defining input and output parameters

Parameter declarations in the module configuration file `module.xml` are made under the element `services`. The element `properties` is used for declaring the input and output parameters of the User service. These parameters will be available for the definition of user tasks that use the User service.

For instance, the following sample specifies a service on a branch with one input parameter named `branch` and one output parameter named `choice`:

    <properties>
    	<property name="branch" input="true">
    		<documentation xml:lang="en-US">
    			<label>Branch</label>
    			<description>
    			This input parameter indicate the branch to work on.
    			</description>
    		</documentation>
    	</property>
    	<property name="choice" output="true" />
    </properties>

The following table summarizes the XML tags to use for defining input and output parameters:

Property | Definition | Mandatory
--- | --- | ---
`properties` | Element containing property declaration. | Yes. This element is unique for a service.
`name` | This attribute specifies the name of the property. | Yes
`input` | This attribute specifies if the property is an input one. | No
`output` | This attribute specifies if the property is an output one. This property is ignored by perspectives. | No
`documentation` | Label and description of the property. | No

### Services on dataspaces or snapshots for data workflows or perspectives

The declaration of an User service on dataspaces and/or snapshots can indicate if the User service can also be used with workflows or perspectives.

If the `type` element contains the value `workflow` in the whitespace-delimited list, the User service will be available to the definition of user tasks in workflow models.

If the `type` element contains the value `perspective` in the whitespace-delimited list, the User service will be available for definition of action menu items in perspective configurations.

For User services on dataspaces in workflows or perspectives, an element `properties/property`, with attributes `name="branch" input="true"`, is also required. Similarly, for User services on snapshots in workflows or perspectives, an element `properties/property`, with attributes `name="version" input="true"`, is required.

#### Example

This example declares a User services that is available in the Services menu for dataspaces, for user tasks in workflow models and for action menu items in perspective configurations. Note the mandatory inclusion of the element `property` with the attributes `name="branch" input="true"`.

    <service name="AdvancedMerge">
    	<resourcePath>/services/advancedMerge.jsp</resourcePath>
    	<type>branch workflow perspective</type>
    	<documentation xml:lang="en-US">
    		...Merge a branch to its parent if valid...
    	</documentation>
    	<properties>
    		<property name="branch" input="true"/>
    	</properties>
    </service>

### Service on datasets for data workflows or perspectives

User services on datasets are declared at the data model-level. However, in order to make them definable for workflow user tasks or perspective action menu items, their declarations must include additional elements in the module configuration file `module.xml` of the module containing the data model.

Under the element `services/serviceLink`, several properties must be defined.

Built-in parameters must be used to define the service selection. The built-in parameters are the same as for Web Components. Entity and service selection parameters.

The built-in parameters `branch` and `instance` are required, which respectively identify the dataspace and contained data set on which the User service will be run.

To define on which table or on which record the service must be run, the `xpath` parameter must be added.

In addition, it is possible to define specific parameters that will be used in the service.

#### Example

The following example declares a dataset service that imports a spreadsheet into a table in a dataset.

    <serviceLink serviceName="ImportSpreadsheet">
    	<importFromSchema>/WEB-INF/ebx/schema/my-ebx.xsd</importFromSchema>
    	<properties>
    		<property name="branch" input="true"/>
    		<property name="instance" input="true"/>
    		<property name="pathToTable" input="true"/>
    		<property name="xpath" input="true"/>
    		<property name="aSpecificParameter" input="true"/>
    	</properties>
    </serviceLink>

#### Properties

The following table summarizes the elements and attributes under the element `services/serviceLink`:

Property | Definition | Mandatory
--- | --- | ---
`serviceName` | Attribute of `serviceLink` that defines the name of the User service as it is specified in the data model. | Yes
`importFromSchema` | Element that specifies the path to the data model, relative to the current module (web application). | Yes
`properties` | Element that defines input and output parameters. | Yes. At least the input properties for "branch" and "instance" must be defined.

### Service extensions

It is possible to extend User services that have already been declared, by defining labels and descriptions and adding properties. You can extend built-in User services, dataspace or snapshot User services and dataset User services. However, it is not possible to further extend a service extension.

Service extensions must be declared in the module configuration file `module.xml`, under the element `services/serviceExtension`.

##### Note

A service extension allows to extend a built-in service or a service declared in the same module. In other words, it is not possible to extend a service declared in an other module. Because of this limitation, it is not possible to extend an add-on service.

#### Extending a built-in User service

    <serviceExtension name="BuiltinCreationServiceExtension" extends="@creation" >
    	<documentation xml:lang="en-US">
    		<label>Built in creation service extension</label>
    	</documentation>
    	<properties>
    		...
    	</properties>
    </serviceExtension>

Property | Definition | Mandatory
--- | --- | ---
`name` | Attribute that specifies the name of the service extension. | Yes
`extends` | Attribute that specifies the name of the built-in User service being extended. The value is the ``ServiceKey`` of the built-in User service. For the default built-in User service 'Access data', this attribute must be empty. | Yes
`properties` | Element that declares properties being added to the built-in User service. | No
`documentation` | Localized labels and descriptions to add to the built-in User service. | No

#### Extending dataspace and snapshot User services

The service extension and the User service being extended must be defined in the same `module.xml` module configuration file.

    <serviceExtension name="AdvancedMergeExtension" extends="AdvancedMerge">
    	<documentation xml:lang="en-US">
    		...
    	</documentation>
    	<properties>
    		...
    	</properties>
    </serviceExtension>

Property | Definition | Mandatory
--- | --- | ---
`name` | Attribute that specifies the name of the service extension. | Yes
`extends` | Attribute that specifies the name of the User service being extended. | Yes
`properties` | Element that declares properties being added to the User service. | No
`documentation` | Localized labels and descriptions to add to the User service. | No

#### Extending dataset User services

Since the service extension and the User service being extended must be defined in the same `module.xml` module configuration file, you must first declare the User service as an interaction using element `serviceLink`.

    <serviceExtension name="ImportSpreadsheetExtension" extends="ImportSpreadsheet" fromSchema="/WEB-INF/ebx/schema/my-ebx.xsd">
    	<documentation xml:lang="en-US">
    		...
    	</documentation>
    	<properties>
    		...
    	</properties>
    </serviceExtension>

Property | Definition | Mandatory
--- | --- | ---
`name` | Attribute that specifies the name for the service extension. | Yes
`extends` | Attribute that specifies the name of the User service being extended. | Yes
`fromSchema` | Attribute that specifies the path to the schema that defines the User service. | Yes
`properties` | Element that declares properties being added to the User service. | No
`documentation` | Localized labels and descriptions to add to the User service. | No

## User services default permission

The service default permission is used when no permission has been explicitly set for this service to a given profile. This occurs when:

- No permission rule is set for this profile.

- At least one permission rule is set for this profile, but the permission for the service is set "default".

Note that when adding a new service to an EBX® repository, the service permission is set to "default" for all existing permissions rules.

To set the default permission for user services on datasets, the `osd:defaultPermission` element must be used in the service declaration. To set the default permission for user services on dataspaces, the `defaultPermission` attribute must be used in the service declaration.

##### See also

- Permission rules
- Resolving permissions on services

## User service groups

User service groups are used to organize the display of user services in menus and permission management screens.

The following types of service groups are available:

- Built-in User Service Groups provided by EBX®,

- Custom User Service Groups declared in a module.

The link between groups and services is made upon service declaration. See Associating a service to a group.

### Built-in User Service Groups

Available built-in service groups:

Service Group Key | Description
`@ebx-importExport` | Group containing all built-in import and export services provided by EBX®. In the default menus, these services are displayed in a "Import / Export" sub-menu.

### Declaring a User Service Group

User Service Groups must be declared in the module configuration file `module.xml`, under the element `serviceGroups/serviceGroup`, where `serviceGroups` is the root of all user services declared in the module.

#### Example

The following example declares a user service group `myCompanyGroup`:

    <serviceGroups>
    	<serviceGroup name="myCompanyGroup">
    		<documentation xml:lang="en-US">
    			<label>My Company Services</label>
    		</documentation>
    		<documentation xml:lang="fr-FR">
    			<label>Services de ma compagnie</label>
    		</documentation>
    	</serviceGroup>
    </serviceGroups>

Should this declaration be in a module named `myCompanyModule`, the resulting service group key would then be `myCompanyModule@myCompanyGroup`.

#### Properties

Property | Definition | Mandatory
--- | --- | ---
`name` | Attribute specifying the name of the user service group. This name must be unique within the scope of a module. The key identifier to reference this user service group is as follows: `<moduleName>@<serviceGroupName>`. | Yes
`documentation` | Localized labels and descriptions to add to the user service. | No

### Associating a service to a group

Associating a service to a group is made upon service declaration. To do so, the target service group key has to be set as a value of the `osd:group` element for a user service on datasets, or as a value of the `group` for a user service on dataspaces.

A service can be associated to either a built-in or custom service group. In the latter case, this service will be displayed in this built-in group, just like other built-in services belonging to this group.

The following examples are based on module declared services, but they apply similarly to data model declared services.

#### Example 1: Association with a custom group

In the following example, the `displayAboutFromMyCompany` user service is associated with the `myCompanyModule@myCompanyGroup` custom group.

    <service name="displayAboutMyCompany">
    	<resourcePath>/help/displayAboutMyCompany.jsp</resourcePath>
    	<group>myCompanyModule@myCompanyGroup</group>
    	<type>branch version</type>
    	<documentation xml:lang="fr-FR">
    		<label>A propos...</label>
    		<description>Affiche diverses informations sur ma compagnie.</description>
    	</documentation>
    </service>

In menus, this service will be displayed in the "My Company Services" sub-menu with other custom services associated with this group.

#### Example 2: Association with a built-in group

In the following example, the `importFromMyCompanyArchiveFormat` user service is associated with the `@ebx-importExport` built-in group.

    <service name="importFromMyCompanyArchiveFormat">
    	<resourcePath>/import/importFromMyCompanyArchiveFormat.jsp</resourcePath>
    	<group>@ebx-importExport</group>
    	<type>branch</type>
    	<documentation xml:lang="fr-FR">
    		<label>Import d'archive</label>
    		<description>Importe une archive dans la branche courante.</description>
    	</documentation>
    </service>

In menus, this service will be displayed in the "Import / Export" sub-menu with the CSV and XML import/export built-in services.

TIBCO EBX® Documentation