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.
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.
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 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 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.
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.
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.
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>
Property | Definition | Mandatory |
|---|---|---|
| Attributes that specify the name of the user service. | Yes |
| 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. |
| 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
| No. If not defined, activates as a global User service that is not attached to a particular node. |
| 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. |
| 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. |
| 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. |
| Element that specifies if the service is displayed in UI menus and buttons. | No. Default value is true. |
| 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 |
| 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. |
| Element that specifies the service default activation policy. See Default permission in this chapter for more information. Allowed values are: | No. If undefined, the service is enabled by default. |
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".
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 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
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.
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>
Property | Definition | Mandatory |
|---|---|---|
| Attribute that specifies the name of the User service. This name must be unique within the scope of a module. | Yes |
| 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 |
| Element that defines the availability of the User service as a whitespace-delimited list.
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 |
| Localized label and description of the user service, displayed in the menu where the user service appears. | No |
| 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. |
| 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. |
| Attribute that specifies the service default activation policy. See Default permission in this chapter for more information. Allowed values are: | No. If undefined, the service is enabled by default. |
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".
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
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
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.
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 |
|---|---|---|
| Element containing property declaration. | Yes. This element is unique for a service. |
| This attribute specifies the name of the property. | Yes |
| This attribute specifies if the property is an input one. | No |
| This attribute specifies if the property is an output one. This property is ignored by perspectives. | No |
| Label and description of the property. | No |
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.
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>
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.
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>
The following table summarizes the elements and attributes under the element services/serviceLink:
Property | Definition | Mandatory |
|---|---|---|
| Attribute of | Yes |
| Element that specifies the path to the data model, relative to the current module (web application). | Yes |
| Element that defines input and output parameters. | Yes. At least the input properties for "branch" and "instance" must be defined. |
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.
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.
<serviceExtension name="BuiltinCreationServiceExtension" extends="@creation" > <documentation xml:lang="en-US"> <label>Built in creation service extension</label> </documentation> <properties> ... </properties> </serviceExtension>
Property | Definition | Mandatory |
|---|---|---|
| Attribute that specifies the name of the service extension. | Yes |
| Attribute that specifies the name of the built-in User service being extended. The value is the | Yes |
| Element that declares properties being added to the built-in User service. | No |
| Localized labels and descriptions to add to the built-in User service. | No |
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 |
|---|---|---|
| Attribute that specifies the name of the service extension. | Yes |
| Attribute that specifies the name of the User service being extended. | Yes |
| Element that declares properties being added to the User service. | No |
| Localized labels and descriptions to add to the User service. | No |
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 |
|---|---|---|
| Attribute that specifies the name for the service extension. | Yes |
| Attribute that specifies the name of the User service being extended. | Yes |
| Attribute that specifies the path to the schema that defines the User service. | Yes |
| Element that declares properties being added to the User service. | No |
| Localized labels and descriptions to add to the User service. | No |
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.
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.
Available built-in service groups:
Service Group Key | Description |
|---|---|
| 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. |
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.
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.
Property | Definition | Mandatory |
|---|---|---|
| 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: | Yes |
| Localized labels and descriptions to add to the user service. | No |
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.
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.
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.