Integrating BPEL processes with IBM Case Manager cases

Business process management and case management are intersecting domains that are converging as corporations use both approaches to stay agile in a turbulent and competitive business market. They have some similarities in they both have processes, however, their designs are different though complementary.

Integration Designer and IBM Case Manager offer a way of using both approaches together. From a case management task, a BPEL process created in Integration Designer can be invoked. The process can be a microflow, that is, responds immediately, or long running, that is, takes longer to respond as the process is more complex. To provide access to a microflow or a long-running process, use the external service wizard in Integration Designer to create a web service.

In addition, an ECM adapter is offered to allow interaction with an IBM Case Manager repository.

The information in this section focuses on using the external service wizard in Integration Designer to create a web service. To see how to create a task in IBM Case Manager that uses this web service, see the information in IBM Case Manager.


Create a web service to implement a case management task

Case management tasks integrate with BPEL processes through a web service which you can build by using the Integration Designer external service wizard. The web service can be implemented in the following ways: a microflow process, which provides a synchronous response; a long-running process, which provides an asynchronous response; or any combination of Service Component Architecture components. To create a web service that can be used by a case management task, follow these steps:

  1. Right-click your module in the Business Integration view and select New > External Service. In the New External Service window, expand Case Management and select Web Service Implementation of a Task. Click Next.

  2. In the Specify Name and Location page, the Module and Namespace fields will be filled but can be changed. To have the generated web service artifacts to be in a folder, add the folder name you want or browse to a folder for the Folder field. In the Name field, add a name for your web service or accept the default name. Click Next.

  3. In the Set the Connection Information for the FileNet Repository page, specify the type of connection in the Connection field or accept the default (HTTP). This connection is to the FileNet repository. In the Server and Port number fields, add the appropriate values or accept the defaults (localhost with a 9080 port). Add the relative path on the server in the Path field. Note the port number and the path are in different fields, however, as you enter them the complete URL is shown beside Repository URL. In the User ID and Password fields, enter the user ID and password. Note these values will be checked and an error message will be shown if they are not valid. Click Next.

  4. In the Select a Task page, select the task you want to implement as a service. At the highest level of the tree structure are object stores. They contain solutions which, in turn, contain case types. Each case type contains the tasks that you can implement as a service. Tasks that cannot be selected are already implemented. Click Next.
  5. The Select the Input and Output Parameters page opens. For the input and output parameters of the task, select the case type properties to use. Click Next.
  6. The Set the Process Properties page gives you the following options to complete building your web service.

    • Create a microflow. Select this option if your service will invoke a business process that provides an immediate response.

    • Create a long-running business process. Select this option if your service will invoke a business process that runs for an extended time; that is, does not provide an immediate response.
    • Do not create a business process. Select this option to choose all the components your service uses. For example, your service implementation could use a mediation flow component as the service implementation.

    Select the appropriate option and click Next.

  7. The Set the Deployment Target page designates the server where the service will be deployed to and if security will be used. The information is necessary for the case management task to locate the service at run time and determine the level of security. You have the following choices.

    • You can enter the information for the Target server, that is, the Host name and Port number fields. Then you can select if your service will include security by selecting the Use security to access the web service from the case management task check box. Optionally, you can select the Use a secure socket (SSL) connection check box. SSL refers to a Secure Sockets Layer security. Selecting security does not impact your next steps, however, do some extra work after you generate the web service as indicated in the note below. Click Finish.

      Clicking the security check boxes indicates your service will use security. You must set the security up independent of this wizard. See Security for exports and imports used with case management tasks.

    • Click New and follow these steps:

      1. In the Define a New Server page, enter the appropriate values for the Server's host name, Select the server type, Server name and Server runtime environment fields. Selecting a server from the pane where the servers are listed will fill these fields for you. Click Next.
      2. The following pages may vary depending on the server you selected but the pattern is similar. For example, if you had chosen Process Server then the WAS Runtime Environment page opens. The name of the server that was previously specified previously appears in the Name field. Enter or browse to the installation directory to complete the Installation directory field. Click Next.

      3. In the WAS Settings page, add or select the appropriate values for the profile name and server connection types and administrative ports. Select if security will be enabled and, if so, the user ID and password. Enter the application server name. At this point you can click Finish and be returned to the Set the Deployment Target page where you can complete generating your service with or without security. Alternately, you can click Next and follow the next step to deploy your service to the server, which we will do for instruction purposes.
      4. The Add and Remove Projects page opens. Select your project from the Available projects pane and click Add. Click Finish.
      5. The Set the Deployment Target opens. All the fields are completed based on the information from the previous pages. You can select if your service will include security by selecting the Use security to access the web service from the case management task check box. Optionally, you can select Use a secure socket (SSL) connection check box. SSL refers to a Secure Sockets Layer security. Selecting security does not impact your next steps, however, do some extra work after you generate the web service as indicated in the note below. Click Finish.

        Clicking the security check boxes indicates your service will use security. You must set the security up independent of this wizard. See Security for exports and imports used with case management tasks.

  8. The service is generated. If had selected a microflow, you will see an export and a business process. If you had selected a long-running business process, you will see in the assembly editor an export, a business process and an import. The business process will be a skeleton business process for you to complete. If you chose to not create a business process, only the web service export will be shown in the assembly editor. In the Business Integration view beneath your module, you will find the artifacts expected such as an interface, business object, web service port, process, export and import (for a long-running business process).


The service you generated contains critical information that lets your service interact with a specific task on a specific server. Therefore you should not modify the generated code as explained in Work with generated code.



Related concepts:

Design considerations for web services used with case management tasks


Related tasks:

Editing and validating exports used with case management tasks


Related reference:

Delete a web service export used with a case management task


Editing and validating exports used with case management tasks

As the case design or BPEL process evolves, the input and output parameters can change. If the web service needs to be moved to a different server to do an integration test, for example, then the host name, port and path can change. You can edit the input and output parameters then validate your changes. A binding edit function lets you change these values when services are moved. A validate function ensures the IBM Case Manager case and the web service are able to communicate at run time, by ensuring that endpoint, input and output values and security settings are synchronized between the business process management service and IBM Case Manager.

  1. Launch the assembly editor and right-click the export. The Edit Binding and Validate functions are listed on the menu.

  2. Click Edit Binding. The Select the Input and Output Parameters page opens. The current input and output parameters for the task are shown.
  3. Change the parameters if needed and click Next. The Set the Deployment Target page opens.
  4. Change the target server, host name, port number and security options if needed. Click Finish. The generated business objects and interface are updated according to your changes.

  5. Click Validate from the menu to validate the current configuration. Validation is useful if an error occurs and you suspect the problem is in the integration of the case task, and the web service. If the integration is incorrect, a page displaying the errors appears.



Related concepts:

Design considerations for web services used with case management tasks


Related tasks:

Create a web service to implement a case management task


Related reference:

Delete a web service export used with a case management task


Delete a web service export used with a case management task

Changes to your case management task may require deleting the web service export used with it.

The following information shows how to delete a web service export used by a case management task. It also shows how to handle a special case where the export has been deleted in Integration Designer but the case management task still has code that points to a BPEL process.


Delete a web service export used with a case management task

To remove a web service export, follow these steps:

  1. In the assembly editor, right-click the export and select Delete.
  2. A message asks you to confirm the deletion with the following options:

    • Also delete the implementation in the FileNet repository (this operation cannot be undone). It is preselected and the implementation cannot be restored afterward. Removing the implementation in the FileNet repository at the time of deleting the export is recommended. If you need the implementation on the FileNet repository for an error situation or some temporary reason, see the following section on removing out-of-sync references to remove the implementation later.
    • Also delete the generated web service port. It is not preselected. To reuse the port later for another export you will create later, you should leave the check box cleared; otherwise, making this selection will delete the port defined for the web service export.

  3. Click Yes and the web service export is deleted.


Remove out-of-sync case management task references

Delete a web service export does not guarantee the corresponding code in the case management task is removed and the code may still exist.

To remove the extraneous code on the FileNet repository, follow these steps:

  1. From the menu, click Window > Preferences. Expand Business Integration and click Case Management. Click Launch the Cleanup wizard. The Set the Connection Information page opens.

  2. Set the values for the connection information. Click Next.

  3. In the Select a Task page, select the task implementation to delete from the FileNet repository. At the highest level of the tree structure are object stores. They contain solutions which, in turn, contain case types. Each case type contains implemented tasks. Click Finish to delete the task implementation. With this deletion you will now be able to select the task again when you build a new web service in Integration Designer. When finished deleting out-of-sync case management task references, click OK to close the Preferences window.



Related concepts:

Design considerations for web services used with case management tasks


Related tasks:

Create a web service to implement a case management task

Editing and validating exports used with case management tasks


Design considerations for web services used with case management tasks

You should be aware of some differences when working with case management tasks.



Related tasks:

Create a web service to implement a case management task

Editing and validating exports used with case management tasks


Related reference:

Delete a web service export used with a case management task


Security for exports and imports used with case management tasks

Work with a case management task often requires some level of security in order to protect your data.

In the final step of creating your web service, you have the option of selecting some check boxes for security. The following topics will help you with the setup and administration of security as a result of making those selections.


Implications of selecting the security check boxes

If you select the Use security to access the web service from the case management task check box, a default policy set will be applied to the web service export when it is deployed to the server. This policy set can be found if you select the export in the assembly editor and then select the Properties view. You will see the Default policy set field set to BPM FileNet Web Services. You can also find this policy set and related BPM FileNet web services policy sets in the Service Policies section of the Preferences page, which is found on the menu bar by clicking Window > Preferences. You will need to set up a Java Authentication and Authorization Service (JAAS) alias in the token you will be passing. It must have the credentials provided on the call from the case manager task. See the article Login scenarios and techniques in WebSphere Application Server using JAAS for more information on setting up and using a JAAS alias.

When you select the Use a secure socket (SSL) connection check box and also have chosen to create a long running BPEL process, the encryption of the response flow from the process back to the FileNet system is governed by the SSL configuration of the P8 Component Manager. You should ensure the P8 Component Manager is configured to use a secure socket connection in order for the response data to be encrypted as well.

When you select the Use security to access the web service from the case management task check box, it is also important to also use the Use a secure socket (SSL) connection check box as well, otherwise the user credentials will not be encrypted and flow in the clear; that is, the user credentials can be viewed.

If you select the Use a secure socket (SSL) connection check box, the secure port on the server will be used. The keys and certificates needed for the SSL must be used. See SSL, certificate, and key management enhancements for even stronger security in WAS for information on the configuration of SSL.


Lifecycle of a web service export

When you add security to a web service, it affects the service as it moves from a test environment to a production environment. Typically, when you are working with the test client in Integration Designer, you are in that test environment. When that web service is deployed to a production server or any server, do the following tasks:



Considerations when working with case management tasks

There are differences between BPEL processes and case management tasks that handle with your application.

The following sections describe areas for your attention when working with BPEL processes and case management tasks:


Handling faults

A common way of handling exceptions in BPEL processes is to use business faults. However, you will find the interface editor in Integration Designer will not let you add faults to the generated interface. IBM Case Manager tasks do not support business faults. Given this circumstance, what could you do to handle an exception in another way?

There are several techniques which avoid the use of business faults on the interface:


Work with generated code

The external service wizard produces Web Services Description Language (WSDL) code and business objects (XSDs). Exports, imports and stubs for the BPEL process are also among the generated artifacts. These artifacts also contain the module name containing the artifacts. The FileNet repository is highly dependent on the content of these generated files. As a rule, you should not modify them as the implementation on the FileNet repository and the web service will become out-of-sync. If you do make a change like renaming the generated export or import, use the edit binding function to synchronize the implementations as discussed in Editing and validating exports used with case management tasks.

A seeming inconsistency may appear in the name of a case property because in Case Manager a user could change the display name though not the symbolic name. When a web service is created, Integration Designer will show the display name but use the symbolic name in the generated code. In the business object, you will see the symbolic name.


Long-running processes

Use the generated long-running process stub for developing your long-running process. In other words, do not try to connect to an existing long-running process rather than using the generated stub. Inside the generated long-running process stub are elements needed for a BPEL process that is in-sync with the particular case management task associated with the web service.


Manage configuration changes

Changes to the original configuration created in Integration Designer will likely occur. Input and output parameters for a task can change as case management applications change. Configuration changes can occur because services have been moved to another server, which you may or may not know about. To manage expected and unexpected changes, use the edit binding and validate functions as discussed in Editing and validating exports used with case management tasks.


Boundary cases

Boundary cases are situations that are not common but could occur. The boundary cases that follow are situations where there is only a request, that is, a one-way input; only a response, that is, only an output, and lastly the case where there is no input or output. In these situations, follow the steps provided.

Microflow

Input only

  1. Generate a correct input business object and an empty output business object.
  2. Generate a two-way interface; that is, an interface with a request-response operation.
  3. Generate receive and reply activities in your BPEL process. At run time, receive a correct input business object from the FileNet repository and reply with an empty output business object to the FileNet repository.

Output only

  1. Generate an empty input business object and a correct output business object.
  2. Generate a two-way interface; that is, an interface with a request-response operation.
  3. Generate receive and reply activities in your BPEL process. At run time, receive an empty input business object from the FileNet repository and reply with a correct output business object to the FileNet repository.

No input or output

  1. Generate an empty input business object and output business object.
  2. Generate a two-way interface; that is, an interface with a request-response operation.
  3. Generate receive and reply activities in your BPEL process. At run time, receive an empty input business object from the FileNet repository and reply with an empty output business object to the FileNet repository.

Long-running process (macroflow)

Input only

  1. Generate a correct input and output business object. For the output business object, the only property should be the correlation ID.
  2. Generate a two-way interface; that is, an interface with a request-response operation.
  3. Generate receive, assign and invoke activities in your BPEL process. At run time, receive a correct input business object from the FileNet repository, assign the correlation ID from the input business object to the output business object, and reply with the output business object with the correlation ID to the FileNet repository.

Output only

  1. Generate a correct input and output business object. For the input business object, the only property should be the correlation ID.
  2. Generate two one-way interfaces; that is, interfaces with a request operation.
  3. Generate receive, assign and invoke activities in your BPEL process. At run time, receive the input business object with the correlation ID from the FileNet repository, assign the correlation ID from the input business object to the output business object, and reply with the output business object to the FileNet repository.

No input or output

  1. Generate a correct input and output business object. For the input and output business objects, the only property should be the correlation ID.
  2. Generate two one-way interfaces; that is, interfaces with a request operation.
  3. Generate receive, assign and invoke activities in your BPEL process. At run time, receive the input business object with the correlation ID from the FileNet repository, assign the correlation ID from the input business object to the output business object, and reply with the output business object with the correlation ID to the FileNet repository.

No process

Input only

  1. Generate a correct input business object and an empty output business object.
  2. Generate a two-way interface; that is, an interface with a request-response operation.

Output only

  1. Generate an empty input business object and correct output business object.
  2. Generate a two-way interface.

No input or output

  1. Generate an empty input business object and an output business object.
  2. Generate a two-way interface.



+

Search Tips   |   Advanced Search