working with documents in IBM BPM

Document upload and download is one of the import use case in the BPM processing. In this post let us look at how to upload a document from the process instance during the process and retrieve the documents corresponding to a given process instance in a standalone human service? What is mechanism used to store the documents in IBM BPM.

In IBM BPM documents are stored using a document store (Out of Box ECM) provided by IBM BPM. It is also possible to connect to an external ECM from IBM BPM. IBPM suite provides a toolkit out of box called Content Management Toolkit which contain some predefined services and coach view to upload and access the documents to and from the IBM BPM document store. The coach view Document List can be used to upload the documents to IBPM document store or for that matter to any External ECM system which is CMIS compliant. In this post let us look at how to upload the documents to IBPM document store from process instance and associate those documents with some unique parameters such as process instance Id and retrieve them in a standalone screen based on the document parameter ( In this case let us use instance Id as document parameter). Below image shows the image of Document List Coach View from Content Management Toolkit. 

Below image shows the configuration options for the Document list coach view control.

In order to use IBPM document store for document uploads, select the option BPM Documents from the drop down as highlighted in the above figure. And also provide configuration options to BPM document options by attaching the variable to it. We will look at what configuration options need to be provided a little later in this post.

Step 1 : Upload documents from the Human service in a process

Let us assume there is process with a human service with Document List Coach view control, which can be used to upload documents. This coach view can have configuration as shown in the above figure. Let us now look at how to initialize tw.local.bpmdocoptions variable which is assigned in configuration options of this coach. Below shown is code snippet of how do we do that.

 If you carefully examine the above variable, it has two set of values namely displayOptions and uploadOptions which are used for respective purposes as the name suggests. Let us deal one by one.

In displayOptions, you can see  properties like displayMatchRule, associatedWithProcessInstance and displayProperties.  When associatedWithProcessInstance is set true, only the documents which are uploaded in a give process instance is displayed and this option will work only when this coachview is being used in a human task of process instance. displayProperties is a NameValuePair List which can be used to hold the properties for the documents as shown in above figure. displayMatchRule variable accepts three values such that 'ALL','ANY' and 'NONE', which says if all the properties that are there in displayProperties should be matched while displaying documents, or ANY of the properties should be matched or NONE should be matched (If 'NONE' it will display all documents in the system when associatedWithProcessInstance is false).

In uploadOptions, you can see parameters like addProperites, uploadProperties and some other parameters (which are of less importance in our case). The parameter addProperties determines whether to associate properties to the documents when uploading the documents to IBPM document store or not. The Parameter uploadProperties is a NameValuePair list which will hold the properties to be associated to each document while uploading.

When the properties as shown above are set to the Document List coach view, all the documents that are being uploaded uploaded will be associated with the property 'ibm_bpm_process_instanceId' with corresponding process instance id and also displays only those documents which are having this property with the given process instance id value.

Step 2: Retrieve and display instance documents in stand alone Human service 

In order to retrieve the files with desired properties, we just need to initialize the displayOptions  and attach it to coach view. It will fetch all those documents which are having the properties as specified.
Say for examples if we need the documents uploaded in process instance Id '1234', then we need to add properties as shown below.

Hope this helps !!!


  1. can we fetch documents based on Name

  2. It should be possible but you might need to use content integration components and CMIS query to do so. What is your exact requirement?

  3. I am using Internal BPM document store to store documents. i want to display the selected documents in the Document list based on the module Name.

    In document List configuration (display option) whenever i give Name as "cmis:name" and value as "file Name", No documents are getting displayed. i am not sure if i have entered the correct Name/value pair.

    Also, is there any other way to fetch selected documents and display in document list based on input module name.

  4. Hi Pradeep, I am getting "Error retriving docuemnt" when I use DocuemntList control. I am using IBM BPM 8.5.1 version. Do you see any basic mistake i am making this to work?

  5. what is the option you are using for "Configure for use with:" that BPM document or ECM ??

  6. Hi Mohan, I did not understand your question. Is it that you are asking which doc repository that I have used? I have implemented this with both ECM and BPM document store.

  7. Hi Pradeep,

    How can I upload a document from stand alone service and retrieve it in process?

    Sumit Arora

  8. Hi Pradeep,

    How can I upload a document using standalone Human service and retrieve it in Process.


  9. Hi Sumit .. You can use the same method explained above. Attach some upload properties to the document while uploading the document from stand alone human service. In the process use the same parameters to retrieve the documents. You may have to create some unique parameters for each instance at the standalone screen.

  10. Hi Pradeep none of images are loaded on this page. Can you please check.