Enabling widgets to work with multiple endpoints

If you have one Process Portal instance configured and you have a need to create another instance of the service endpoints in your environment, you must configure IBM® Business Process Manager so that the widgets can display data from the multiple service endpoints. You must edit two files: the endpoints file, which registers endpoints with the Business Space component, and the widget catalog file, which contains definitions of widgets.

1. In order to have multiple instances of a widget, you must install the applications that provide widgets with a unique application name and context root for each widget instance.
   1. Deploy the widget application on the Business Space deployment target (the same server or cluster on which the BSpaceEAR_server_node application is running) for each widget instance. The following list includes IBM business process management examples of widget Enterprise Archive (EAR) files:
      • BPMAdministrationWidgets_nodename_servername (for WebSphere Enterprise Service Bus and IBM Business Process Manager)
      • HumanTaskManagementWidgets_nodename_servername (for IBM Business Process Manager and IBM Business Monitor)
      • WBMDashboardWeb_nodename_servername (for IBM Business Monitor)
      • wesbWidgets_nodename_servername (for WebSphere Enterprise Service Bus)
   2. When deploying, update the application name and the web module context root names to a unique name. Take note of the context root names that you use.
2. Edit the new REST service endpoints for the additional application deployment targets (the server or cluster where the REST services application is deployed). Create a service endpoints file to add service endpoints.
   1. Locate the endpoint files in the install_root\BusinessSpace\registryData\product_name\endpoints directory. Copy the endpoints template file, and remove all the endpoints that you do not intend to change.
   2. Edit the endpoints file and add an additional service endpoint starting with <tns:Endpoint>, with a unique ID (<tns:id>) and the URL for the new endpoint (<tns:url>), but with the same version, and optionally all the locales as the original endpoint. The type (<tns:type>) must have the same value as the ID (<tns:id>). You can change the name and description, for example, My team's insurance task list.
   3. When adding endpoints, pay attention to the following information:
      • <tns:id>: The ID can be any string but must be unique for all registered endpoints. Ensure that this ID is unique when you are adding additional endpoints.
      • <tns:type>: The type must have the same value as <tns:id>.
      • <tns:url>: For the service endpoint, if the URL is relative, then it is assumed that the REST service endpoint is co-located with the Business Space server. If the URL is relative, make sure the URL is same as the context root you deployed, but with beginning and end directory indications, for example, <tns:url>/REST_Endpoint_for_server2/</tns:url>. If your endpoint is on a remote system, update this field with an absolute URL, but with an end directory indication.
      • <tns:description>: Type a meaningful description that further details the nature of the data set that this endpoint is working on. It could either be based on the cluster that is working on the data set or the nature of the data set, for example, insurance claim human tasks or accounting data human tasks.
   4. Save your changes.
   Example service endpoint, located in monitorEndpoints.xml:

   <tns:Endpoint>
       <tns:id>{com.ibm.wbimonitor}monitorServiceRootId</tns:id>
       <tns:type>{com.ibm.wbimonitor}monitorServiceRootId</tns:type>
       <tns:version>1.0.0.0</tns:version>
       <tns:url>/rest/bpm/monitor/</tns:url>
       <tns:description>Location of backing services for Monitor widgets
   </tns:description>
     </tns:Endpoint>

3. In the service endpoints file, add a widget endpoint for each widget instance.
   1. Edit the endpoints file that you created in step 2. Add an additional widget endpoint starting with <tns:Endpoint> and with a unique ID (<tns:id>). The type (<tns:type>) must have the same value as the ID (<tns:id>). The URL for the new endpoint (<tns:url>) should be the same as the context root you deployed in step 1., but with beginning and end directory indications, for example, <tns:url>/BSpaceWidgetsWPS2/</tns:url>. The widget endpoint you add should contain the same version and can optionally contain all the locales as the original endpoint. You can change the name and description.
   2. When adding endpoints, pay attention to the following information:
      • <tns:id>: The ID can be any string but must be unique for all registered endpoints. Ensure that this ID is unique when you are adding additional endpoints.
      • <tns:type>: The type must have the same value as <tns:id>.
      • <tns:url>: For the widget endpoint, make sure the URL is same as the context root you deployed, but with beginning and end directory indications, for example, <tns:url>/BSpaceWidgetsWPS2/</tns:url>.
      • <tns:description>: Type a meaningful description that further details the nature of the data set that this endpoint is working on. It could either be based on the cluster that is working on the data set or the nature of the data set, for example, insurance claim human tasks or accounting data human tasks.
   3. Save your changes.
   Example widget endpoint, located in monitorEndpoints.xml:

   <tns:Endpoint>
   <tns:id>{com.ibm.wbimonitor}monitorWidgetRootId2</tns:id>
       <tns:type>{com.ibm.wbimonitor}monitorWidgetRootId2</tns:type>
       <tns:version>1.0.0.0</tns:version>
       <tns:url>/BusinessDashboards/</tns:url>
       <tns:description>Location for Monitor widgets</tns:description>
     </tns:Endpoint>

4. Create a widget catalog file to add new widget definitions.
   1. Locate the widget catalog file in the install_root\BusinessSpace\registryData\product_name\catalogs directory. Copy the catalog template file. For the new file name, use the following standard: catalog_widget.xml (with no spaces in the file name), where widget is the same as the id value of the <catalog> element in the file. Remove all the <category> elements that you do not intend to change. For the category that you are working with, remove all the <entry> elements that you do not intend to change.
   2. Add an <entry> with a unique ID, for example, id="{com.ibm.bspace.widget}widget_id and a unique name, for example, unique-name="{com.ibm.bspace.widget}widget_name. You can keep all the other definitions.
   3. Change the title and description to make the new widget available as a distinct widget in Business Space that outlines the nature of the new endpoint. For example, you could name your widget My team's insurance task list in the <title>. The title should help the business users choose the right widget. The description should help the business users understand the nature of the data and the functionality of the widget that they are selecting.
   4. Edit the new widget catalog XML file to reference the new widget endpoint: Change the definition to match the <tns:id> of the widget endpoint you added in step 3.a.

      For example, change it to: ...

      <definition>endpoint://{com.ibm.wbimonitor}monitorWidgetRootId2/com/ibm/wbimonitor/common/iWidgets/instances_iWidget.xml</definition>

      ...

   5. In the <metadata> of the catalog file, make sure the endpoint:// matches the type and the ID in the endpoint file (<tns:type> and <tns:id>).
   6. In the <metadata> of the catalog file, make sure the "refVersion" : matches the version in the endpoint file (<tns:version>).
   7. Save your changes.
   You can use the widget definition in the example code snippet below as a basis to make your changes::

   <entry id="{com.ibm.wbimonitor}instances" 
   unique-name="{com.ibm.wbimonitor}instances">
               <title>
                   <!-- END NON-TRANSLATABLE -->
                   <nls-string xml:lang="en">Instances</nls-string>
                   <!-- START NON-TRANSLATABLE -->
               </title>
               <description>
                   <!-- END NON-TRANSLATABLE -->
                   <nls-string xml:lang="en">Instances</nls-string>
                   <!-- START NON-TRANSLATABLE -->
               </description>
   	      	<shortDescription>
                       <!-- END NON-TRANSLATABLE -->
   	            	<nls-string xml:lang="en">This widget displays a dashboard with 
   the available monitoring context in either individual instances or user-
   defined groups of context instances.</nls-string>
                       <!-- START NON-TRANSLATABLE -->
               </shortDescription>							
               <definition>endpoint://{com.ibm.wbimonitor}monitorWidgetRootId
   /com/ibm/wbimonitor/common/iWidgets/instances_iWidget.xml</definition>
               <content>endpoint://{com.ibm.wbimonitor}monitorWidgetRootId/img/
   thumb_instances.gif</content>
               <preview>endpoint://{com.ibm.wbimonitor}monitorWidgetRootId/img/
   prev_instances.gif</preview>
   			<previewThumbnail>endpoint://{com.ibm.wbimonitor}monitorWidgetRootId/
   img/prev_instances.gif</previewThumbnail>
   			<help>endpoint://{com.ibm.bspace}bspaceWidgetHelpRootId/topic/
   com.ibm.bspace.help.widg.mon.doc/topics/help_instance_whatis.html</help>
               <icon>endpoint://{com.ibm.wbimonitor}monitorWidgetRootId/img/
   icon_instances.gif</icon>
   			<metadata name="com.ibm.mashups.builder.autoWiringEnabled">true
   </metadata>
               <metadata name="com.ibm.bspace.version">7.0.0.0</metadata>
               <metadata name="com.ibm.bspace.owner">International Business 
   Machines Corp.</metadata>    
               <metadata name="com.ibm.bspace.serviceEndpointRefs">
   [{"name":"serviceUrlRoot", "required":"true", 
   "refId":"endpoint://{com.ibm.wbimonitor}monitorServiceRootId", 
   "refVersion":"1.0.0.0"}]</metadata>			
           </entry>

5. Place the new service endpoint file and the new widget catalog file in a compressed file, and run the updateBusinessSpaceWidgets command, using the -widgets parameter to specify the compressed file location.