Cloud Software Group, Inc. EBX®
Documentation > Developer Guide > User interface > User services
Navigation mode Documentation > Developer Guide > User interface > User services

# Declaring a user service

## Declaration interface

The following table lists, per nature, the interface that the declaration class of a user service must implement:

Nature | Declaration Interface
--- | ---
`Dataspace` | `UserServiceDeclaration.OnDataspace`
`Dataset` | `UserServiceDeclaration.OnDataset`
`TableView` | `UserServiceDeclaration.OnTableView`
`Record` | `UserServiceDeclaration.OnRecord`
`Hierarchy` | `UserServiceDeclaration.OnHierarchy`
`HierarchyNode` | `UserServiceDeclaration.OnHierarchyNode`
`Association` | `UserServiceDeclaration.OnAssociation`
`AssociationRecord` | `UserServiceDeclaration.OnAssociationRecord`

## Life cycle and threading model

The user service declaration class is instantiated at the TIBCO EBX® startup and must be coded to be thread-safe. This is usually not an issue as most implementations should be immutable classes.

## Registration

A user service declaration must be registered by a module or a data model.

Registration by a module is achieved by the module registration servlet by a code similar to:

    public class CustomRegistrationServlet extends ModuleRegistrationServlet
    {
    	@Override
    	public void handleServiceRegistration(ModuleServiceRegistrationContext aContext)
    	{
    		// Register custom user service declaration.
    		aContext.registerUserService(new CustomServiceDeclaration());
    	}
    }

For more information on the module registration servlet, see module registration and `ModuleRegistrationServlet`.

Registration by a data model is achieved by a code similar to:

    public class CustomSchemaExtensions implements SchemaExtensions
    {
    	@Override
    	public void defineExtensions(SchemaExtensionsContext aContext)
    	{
    		// Register custom user service declaration.
    		aContext.registerUserService(new CustomServiceDeclaration());
    	}
    }

For more information on data model extensions, see `SchemaExtensions`.

## Service properties

The properties of a user service include its label, description, confirmation message and the group that owns the service. All are optional but it is a good practice to at least define the label.

For more information, see `UserServiceDeclaration.defineProperties`.

## Service activation scope

The activation scope defines on which selection the service is available.

Example of a service activation definition:

    public class CustomServiceDeclaration implements UserServiceDeclaration.OnTableView
    {
    	...

    	@Override
    	public void defineActivation(ActivationContextOnTableView aContext)
    	{
    		// activates the service in all dataspaces except the "Reference" branch.
    		aContext.includeAllDataspaces(DataspaceType.BRANCH);
    		aContext.excludeDataspacesMatching(Repository.REFERENCE, DataspaceChildrenPolicy.NONE);

    		// activates the service only on tables "table01" and "table03".
    		aContext.includeSchemaNodesMatching(
    			CustomDataModelPath._Root_Table01.getPathInSchema(),
    			CustomDataModelPath._Root_Table03.getPathInSchema());

    		// service will be enabled only when at least one record is selected.
    		aContext.forbidEmptyRecordSelection();

    		// service will not be displayed in hierarchical views (neither in the
    		// top toolbar, nor in the hierarchy nodes' menu).
    		aContext.setDisplayForLocations(
    			ActionDisplaySpec.HIDDEN,
    			ToolbarLocation.HIERARCHICAL_VIEW_TOP,
    			ToolbarLocation.HIERARCHICAL_VIEW_NODE);

    		// service will be considered as disabled if not explicitly enabled
    		// via the UI.
    		aContext.setDefaultPermission(UserServicePermission.getDisabled());
    	}
    }

For more information about declaring the activation scope, see `UserServiceDeclaration.defineActivation`.

For more information about the resolution of the user service availability, see Resolving permissions on services.

## Web component declaration

### Parameters declaration and availability in workflows and perspectives

User services are automatically available as web components with a set of built-in parameters depending on the service's nature. To define custom parameters and/or set the service web component as available when configuring a workflow user task, a perspective menu action or a toolbar web component action, `UserServiceDeclaration.declareWebComponent` must be used.

Example of a web component declaration:

    public class CustomServiceDeclaration implements UserServiceDeclaration.OnDataset
    {
    	...

    	@Override
    	public void declareWebComponent(WebComponentDeclarationContext aContext)
    	{
    		// makes this web component available when configuring a workflow user task.
    		aContext.setAvailableAsWorkflowUserTask(true);

    		// adds a custom input parameter.
    		aContext.addInputParameter(
    			"source",
    			UserMessage.createInfo("Source"),
    			UserMessage.createInfo("Source of the imported data."));

    		// modifies the built-in "instance" parameter to be "input/output" instead of "input".
    		aContext.getBuiltInParameterForOverride("instance").setOutput(true);
    	}
    }

See Using TIBCO EBX® as a Web Component for more information.

### User service extension

It is possible to extend existing user services (built-in or custom) in order to add input/output parameters when using these services as web components.

In order to do so, a user service extension must first be registered by a module or a data model.

Registration by a module is achieved by the module registration servlet by code similar to:

    public class CustomRegistrationServlet extends ModuleRegistrationServlet
    {
    	...

    	@Override
    	public void handleServiceRegistration(ModuleServiceRegistrationContext aContext)
    	{
    		// Register user service extension declaration.
    		aContext.registerUserServiceExtension(new ServiceExtensionDeclaration());
    	}
    }

For more information on the module registration servlet, see module registration and `ModuleRegistrationServlet`.

Registration by a data model is achieved by a code similar to:

    public class CustomSchemaExtensions implements SchemaExtensions
    {
    	...

    	@Override
    	public void defineExtensions(SchemaExtensionsContext aContext)
    	{
    		// Register user service extension declaration.
    		aContext.registerUserServiceExtension(new ServiceExtensionDeclaration());
    	}
    }

For more information on the data model extension, see `SchemaExtensions`.

## 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 an "Import / Export" sub-menu.
`@ebx-views` | Group containing services to display in the 'Views' menu. Unlike other service groups, services associated with this group are not displayed in the default menus, but only in the 'Views' menu displayed in the non-customizable part of the table top toolbar. These services can still be added manually to a custom toolbar.

### Declaring a User Service Group

User Service Groups must be declared while registering the module, using the method `ModuleServiceRegistrationContext.registerServiceGroup`:

    public class CustomRegistrationServlet extends ModuleRegistrationServlet
    {
    	...

    	@Override
    	public void handleServiceRegistration(ModuleServiceRegistrationContext aContext)
    	{
    		// In CustomModuleConstants,
    		// CUSTOM_SERVICE_GROUP_KEY = ServiceGroupKey.forServiceGroupInModule("customModule", "customGroup")

    		// registers CUSTOM_SERVICE_GROUP_KEY service group
    		aContext.registerServiceGroup(
    			CustomModuleConstants.CUSTOM_SERVICE_GROUP_KEY,
    			UserMessage.createInfo("Custom group"),
    			UserMessage.createInfo("This group contains services related to..."));
    	}
    }

### Associating a service to a group

The association of a service with a group is made at its declaration, using the method `UserServicePropertiesDefinitionContext.setGroup`:

    public class CustomServiceDeclaration implements UserServiceDeclaration.OnDataset
    {
    	...

    	@Override
    	public void defineProperties(UserServicePropertiesDefinitionContext aContext)
    	{
    		// associates the current service to the CUSTOM_SERVICE_GROUP_KEY group
    		aContext.setGroup(CustomModuleConstants.CUSTOM_SERVICE_GROUP_KEY);
    	}
    }

A service can be associated with either a built-in or a 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.

Documentation > Developer Guide > User interface > User services