Exposing heritage human services

In addition to implementing the activities in a process, the heritage human services that you create in IBM® Process Designer can also be used to customize the Process Admin Console or to create a custom dashboard for IBM Process Portal. The exposure settings for a service depend on its intended purpose.

Before you begin

For information about exposing client-side human services, see Defining usage settings for client-side human services.

Procedure

Open a process app or toolkit in Process Designer
Open the heritage human service that you want to expose and click the Overview tab.
Select the team that you whose members can view and use the exposed service. In the web Process Designer, set the Exposed to start option under the Usage section.
In the desktop Process Designer, set the Exposed to option under the Exposing section.

Specify how you want to use the service. In the Use As or Expose As list, select one of the following options.

Table 1. Exposing options
Option	Description
Task (Service contained in a process) or Do Not Expose (Service contained in a BPD or case type)	Use this default option for services that implement the activities within a process. When this option is selected, the Exposed to setting is not used.
Administration Service (Available in the Process Admin Console)	Use this option to make the heritage human service available to members of the selected team as a separate page in the Process Admin Console in the Server Admin capabilities. A new category is added to the menu, which has the same name as the process application that contains the service. The name of the individual page in the new category matches the service name.
Startable Service (Launch from Process Portal)	Use this option to enable members of the selected team to start the service from the Launch list in Process Portal.
Dashboard (Available in Process Portal Dashboards menu)	Use this option to make the heritage human service available in Process Portal to members of the selected team. Team members can access the dashboard by clicking the Organize tabs icon , and selecting the dashboard from the list of hidden pages. If you do not specify a localization resource for the dashboard name, the dashboard page has the same name as the exposed service. If you defined a localization resource for your dashboard name, click Select next to the Label field and select the key in the resource. See Globalizing dashboard names. If the heritage human service is in a toolkit, you must complete the following steps: Create a snapshot of the toolkit. Activate the toolkit snapshot. See Activating snapshots for use with IBM Process Portal Add the toolkit snapshot as a dependency to a process application. See Creating, changing, and deleting a toolkit dependency in the Designer view. If you want to expose the dashboard outside of Process Portal, generate a portlet that you can deploy to a portal server by clicking Create a Portlet from the Dashboard.
URL (Available from a URL only)	Use this option to make the service available from a URL address. For information about the REST API that provides the URL for the exposed service, see REST Interface for BPD-related Resources - Exposed Items Resource.

Click Save or Finish Editing.

Results

In addition to being exposed to user interfaces as described in the previous table, all exposed heritage human services are made available to be called as URLs.

The URL is composed of the name of the host on which IBM Process Center Server or Process Server is installed, the port that is designated for the server during the IBM Business Process Manager installation, and the acronym for the process application that contains the service. For example, if you expose a service named MyService, you can access it from the following URL:

http://host_name:port/contextRootPrefix/executeServiceByName?processApp=acronym&serviceName=MyService

The default value for the contextRootPrefix is teamworks. For more information about how to configure a custom context root, see the section for the -update parameter in the BPMConfig command-line utility topic.

Remember: Any browser-specific URL limitations, such as the URL length and character restrictions, apply and must be considered when calling a heritage human service as a URL.

URL parameters

The URL can contain one or more of the following parameters:

processApp: The name of the process application
serviceName: The name of the heritage human service
snapshot: The name of the snapshot
com.lombardisoftware.errorPage: The URL of the error page

Input variables

In the URL, input variables that are defined for the service have the following format:

&tw.local.variableName=value

The default configuration is defined in the 99Local.xml file. For more information, see The 100Custom.xml file and configuration. Also, the following example shows how to customize the 100Custom.xml file to enable the type-string-to-date configuration option:

<common merge="mergeChildren">
		<type-string-to-date merge="replace">true</type-string-to-date>
</common>

For heritage human services, variableName can be a system-defined SimpleType or a BusinessObject that is based off a SimpleType variable (of type String, Integer, Decimal, Date, Time, Selection). Date or Time are allowed only after enabling the type-string-to-date configuration option.

Restriction: The type-string-to-date configuration option is applicable only to heritage human services. It does not apply to client-side human services.

<common merge="mergeChildren">
		<type-string-to-date merge="replace">true</type-string-to-date>
</common>

Date/Time syntax

The date and time format differs between client-side human services and heritage human services. The syntax for the other simple types (String, Integer, Decimal, Selection) is the same for client-side human services and heritage human services.

Note: For information about the date and time syntax in human services, see Defining usage settings for client-side human services.

For heritage human services, the date and time format is as follows:

The Date format is YYYY-MM-DD.
The Time format is HH:mm:ss.
Time Zone: Because support for time zone information is not provided with heritage human services, the default time zone is set to the time zone of the server.

Service version invoked

If a specific snapshot name is not passed to the URL, the default version of the service that is run depends on the environment in which the service is running.

Table 2. Version of the heritage human service invoked for each environment
Environment	Version of the heritage human service
Process Center	The exposed service in the tip of the default track is run.
Process Server	The exposed service in the default snapshot is run.
Process Portal	When you start a heritage human service as a dashboard in Process Portal, the version that is started is the current working version of the heritage human service if the version is exposed. Otherwise, if there is an active snapshot in which the heritage human service is exposed, then the snapshot version is started. If the current working version is not exposed and there are multiple active snapshots in which the heritage human service is exposed, then the latest snapshot version is started.
A portlet in an external portal server	You can export only one valid snapshot when you generate a portlet for a dashboard. When the portlet communicates back to IBM Business Process Manager, that snapshot must be active.