This tutorial includes sample code for download. If you wish to follow along with the tutorial and perform the scenario for yourself, you should have an installation of IBM BPM V8.5 or higher. Extract the provided zip file to your C:\ drive, then import into your Process Center the TWX file BPM_Document_Store_Sample - 1.0.twx that is in the C:\BPM85DocumentStore\twx folder.
ECM systems manage documents of different types, such as records, images, and web pages, throughout their lifecycle. You can access and update such documents from a business process inside IBM BPM by using special ECM operations in services such as an integration service or a human service.
Since version 8.0 of IBM BPM, integration with ECM systems has been based on Content Management Interoperability Services (CMIS). CMIS (Figure 1) is an open standard administered by the Organization for the Advancement of Structured Information Standards (OASIS) that defines an abstraction layer for controlling diverse document management systems and repositories using web protocols.
Figure 1. CMIS standard
A new feature added in IBM BPM V8.5 is an internal CMIS repository, known as the BPM document store, that provides the ability to support embedded ECM and uses consistent access mechanisms for integrating to it, like those that have been used since 8.0 for external ECM systems as shown in Figure 2.
Figure 2. CMIS access to internal documents
Note that the internal BPM document store is not a fully featured ECM and is not intended as a replacement for an enterprise-scale ECM. Refer to the IBM BPM Information Center for details on the full set of capabilities and restrictions concerning the new document store feature.
The content integration capabilities using the internal BPM document store in IBM BPM allow for a number of typical scenarios:
- Accessing and displaying documents in a Coach as part of the actions a user needs to perform in a process activity
- Starting a business process as the result of a document event (such as the creation of a new document or an update made to an existing document)
- Resuming a business process that is paused while it awaits an expected document event (such as the receipt of identification documents to be used as confirmation of entitlement)
Of these, this tutorial focuses on the last one, because it's the most complex scenario, and because it contains aspects of the other two scenarios and therefore is is a more comprehensive illustration of the feature's capabilities. The logical scenario is illustrated as a BPMN (Business Process Model and Notation) process in Figure 3.
Figure 3. BPMN scenario involving asynchronous inbound events
In this scenario some automatic processing (Initial Checks) is performed before an outbound message needs to be sent to request additional information from the customer. This outbound message is logical in that it could well be performed by a participant in the Order Management role calling the customer directly or it might be in the form of an email being sent. The Customer role shows the corresponding receipt of the message followed by some internal processing and then sending an outbound message as the response. This is all outside the control of the Order Management process, which will only know this phase has completed when the inbound message is received by the intermediate message event that precedes the Verification user activity. The rest of this tutorial will demonstrate how to achieve this scenario using the internal BPM document store in IBM BPM 8.5.
A content-driven scenario demonstration
The scenario has been provided in the BPM Document Store Sample process application. If you want to follow along and run the scenario for yourself, you should download and import that sample into your Process Center. Once imported, open and run ECM Await Document Process by clicking the run icon, as shown in Figure 4.
Figure 4. Run process from Process Designer
When the process starts, switch to the Process Inspector view in Process Designer. You should see that the first activity in the process is active and awaiting action as shown in Figure 5. You can now run this activity to launch the associated Coach and interact with it.
Figure 5. Process in the Process Inspector view
Figure 6 shows some sample data entered into the Coach. Most important is the highlighted field for the customer's identifier, which you should take note of as you'll need it to match the documents that you'll upload later in the scenario.
Figure 6. Completed customer application information
Once the user activity is completed (after clicking Submit) the Process Inspector shows that the process has moved on to the next activity (Figure 7), which is an intermediate content event (a special type of message event that is associated with an event in the CMIS content store). The process will remain at this step until a content event arrives that correlates to this process instance (that is, an event for the same customer uniquely identified by the customer identifier field).
Figure 7. Process awaiting inbound content event
In order to move the process instance past this activity, you need to generate a document event. This will be done on receipt of the expected document from this customer. You upload the document by running the provided human service Document Upload Client CS, as shown in Figure 8.
Figure 8. Service for uploading documents to document store
When you first run this service, there shouldn't be any existing documents in the internal BPM document store and the Coach should appear as shown in Figure 9.
Figure 9. Initial UI with no existing documents
To upload a document, click Create Document to open the dialog shown in Figure 10.
Figure 10. Wizard for uploading documents showing default values
For the first test, we'll deliberately supply values that won't correlate
on the process instance. The process instance correlation rules (we'll
examine how this is achieved later) decree that the process instance is
expecting a specific document type (
Application). In the
dialog, select one of the other document types and supply example data for
the other fields as suggested in Figure 11 (remembering to use
the same customer identifier as you used in the initial data entry step).
Click OK to complete the creation step.
Figure 11. Create document with sample values (no correlation)
You should now be able to verify in Process Inspector that the process
instance remains at the activity awaiting a content event, and no
correlation has happened due to the fact you explicitly chose a document
type other than
Application. You can now correct this by
clicking Create Document again, and this time supplying
the correct combination of document type and customer identifier as shown
in Figure 12. This time, upload a file by clicking
Browse and selecting the Sample Document.pdf, which
you should find in C:\BPM85DocumentStore\upload if you extracted the
supplied zip file to your C:\ directory.
Figure 12. Create document with sample values (should correlate to process instance)
This time the correlation should succeed and the process instance should move on to the final activity (Confirm Application), as shown in Figure 13.
Figure 13. Process showing confirmation step awaiting action
To complete the scenario (and verify the expected document has indeed been received by the process instance), launch the final activity, which should result in the Coach displayed as shown in Figure 14. If you want to see the document in full screen, click Open in new window as highlighted in the figure.
Figure 14. Confirmation activity displayed with initial values
In order to complete the scenario, the user performing the activity completes the form as shown in Figure 15 and clicks Confirm. The process instance should then show as completed in Process Inspector.
Figure 15. Confirmation activity completed
Key components used to build the scenario
The scenario we just demonstrated has been achieved using a number of key techniques that we'll examine in this section:
- Configuring an intermediate content event to receive the inbound document message within the business process
- Defining of an event subscription to detect the creation of a document in the internal BPM document store
- Providing an enhanced version of the Document List Coach control that allows for the setting of metadata properties on an uploaded document
Configuring an intermediate content event
The intermediate content event defined on the process shown in Figure 16 is associated with a UCA (undercover agent) that has been defined as part of an event subscription.
Figure 16. Intermediate content event configuration
In order to ensure the correct document receipt event is associated with the particular instance of the business process, a correlation needs to be defined as highlighted in the Data Mapping section in Figure 17.
Figure 17. Intermediate content event data mapping
Defining an event subscription
In order to send the event representing the creation of a new document, you need to specify an event subscription against the internal BPM document store, as shown in Figure 18. The relevant important settings are highlighted. Note that other Event Types can also be detected, such as an existing document being updated.
Figure 18. Event subscription
The configured Attached Service acts as the subscription handler containing
the logic to decide what to do when a document creation event is detected.
The highlighted called service in Figure 19 is a special
Content Integration element that allows for invoking the defined
operations on the content store, in this case the
document operation to retrieve the
Figure 19. Subscription handler – call to get document
Recall that in the runthrough of our scenario, we showed that it requires a special combination of the document type and customer identifier in order to trigger the correlation to the waiting process instance. The logic to achieve this is performed in a service named Check Application Info, which is called from the subscription handler as shown in Figure 20.
Figure 20. Subscription handler – call to Check Application Info
The created document will have metadata associated with it in the form of document properties. You'll see in the next section how these are specified upon uploading. These document properties are checked in the Check Application Info service (Figure 21) and the result matches if the expected document type is detected.
Figure 21. Logic to check document properties
After a decision gateway validates whether the document matches the defined type, an Invoke UCA step (Figure 22) will send the event through for any listening business process instances that have the respective UCA defined.
Figure 22. Subscription handler – call to invoke UCA
The UCA definition is shown in Figure 23. Note the documentation that explains the special use of a Service implementation in order to pass through the business data field to be used for correlation.
Figure 23. UCA definition
Using the Document List control
The Content Management Toolkit provides a Document List control for displaying documents in a document store and to allow for adding and modifying documents within it. That control allows for defining static properties that apply to every uploaded document; however, the requirements of this scenario are that dynamic metadata properties be added to each uploaded document. We've provided an enhanced version of the Document List control (named Extended Document List), which is shown used in the Coach in Figure 24.
Figure 24. Usage of Extended Document List Coach View
Figure 25. Provided Document List Coach View
Figure 26. Extended Document List Coach View
The reason for needing to extend the control is to allow for dynamic property setting on a document by document basis. The configuration settings inherited from the base Document List control (Figure 27) show that there is a provision to specify static properties. However, every subsequent uploaded document would have the same properties, so this is not sufficient for the requirements of the scenario.
Figure 27. Upload properties configuration options in Document List
with the comments convention starting with
// EXTENSION : as
illustrated in the code fragment shown in Figure 28. The code
provides for adding additional fields on the dialog that is displayed when
the user creates a document. Those field values are then set as document
properties on the document that is uploaded to the document store. You can
in understanding the code enhancements.
Figure 28. Example of extension logic in JS file
This tutorial demonstrated a content-driven scenario using the BPM document store embedded ECM capability introduced in IBM BPM V8.5. You've seen how to correlate the receipt of a document with an existing process instance that is expecting that document as evidence to support an application. You've learned about the features in IBM BPM used to achieve the scenario, including some enhancements to the provided Document List Coach control that allow a user to specify metadata properties when uploading documents to the BPM document store.
- Working with documents in the IBM BPM V8.5 Information Center: Information on using the BPM document store.
- Integrating IBM Business Process Manager V8 with an Enterprise Content Management system: For background information on ECM support in IBM Business Process Manager in general.
- IBM Software Services for WebSphere: Find out how IBM expertise in cutting-edge and proven technologies can help you achieve your business and IT goals.
- developerWorks BPM zone: Get the latest technical resources on IBM BPM solutions, including downloads, demos, articles, tutorials, events, webcasts, and more.
- IBM BPM Journal: Get the latest tutorials and columns on BPM solutions in this quarterly journal.