TIBCO EBX®
TIBCO EBX® Documentation
Navigation modeTIBCO 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:

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:

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:

Common use cases

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

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 http://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 '/'.

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:

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.

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 '/'.

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:

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.

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:

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