Within the last weeks, one question reached me a couple of times: what is the best way to cleanup many local documents in an efficient way? Let’s put this information together here, so that everybody can read about it.
What are local documents?
Let’s start by quickly describing what local documents in the context of IBM Business Process Manager (BPM) are. Local documents, also known as process attachments or IBM BPM documents, are documents that are stored in the IBM BPM system. They are typically associated with a process instance, but can also be “global” and then are not associated with an instance.
Local documents that are associated with a process instance are an efficient way to store temporary documents without requiring an external Enterprise Content Management (ECM) system. On the other hand, local documents lack a lot of capabilities that an ECM system offers, like fine-grained access control, strongly typed document metadata or retention policies. My previous post IBM Business Process Manager 8.5.7 - Local and External Documents is describing this in more detail.
“Global” local documents are something that I do not recommend using. IBM BPM is not a content management system and if documents are not related to a process instance, then they are better stored in an external ECM system.
When do I need to manually delete local documents?
Local documents associated with process instances are automatically deleted when the process instance is deleted. But still, you need to take care of the deletion of local documents in these situations:
- “Global” local documents that are not associated with process instances are not automatically deleted by the system.
- Associated documents are not deleted when using the LSW_BPD_INSTANCE_DELETE stored procedure to delete process instances. The reason is that the stored procedure can only remove data from the IBM BPM runtime database, but local documents are stored in the IBM BPM document store. The stored procedure is deprecated, you should instead use the REST API, BPMProcessInstancesCleanup (until V8.5.6) or BPMProcessInstancesPurge command (since V8.5.7) to delete process instances.
- Associated documents are not deleted at all with IBM BPM V8.5.6 without the Basic Case Management feature because of a bug. You should upgrade this system based on our product maintenance strategy, but even after the upgrade you will still have the orphaned local documents where the process instance was already deleted before the upgrade.
How do I delete local documents?
To delete local documents, there are three APIs available:
- REST API: DELETE document, this operation can only be performed for local documents associated with process instances
- Content Integration operation Delete document against the IBM BPM document store
When building a solution that creates local documents, especially when they are global, you should think about how and when they will be deleted.
How do I cleanup all the existing local documents in my system?
Let’s get back to the original question: there is an IBM BPM system where it was not taken care that more and more local documents are created, how can they be deleted?
- Local Document Administration - 8550-02.twxView Details
- Local Document Administration - 8560-02.twxView Details
- Local Document Administration - 8570-02.twxView Details
Import it, then modify the Operators team in that process application to add a user that you want to make this cleanup available. This user will find a new section in the Process Admin Console:
On this page, you can define which local documents you want to delete. After clicking Start, the human service implementation will trigger an Undercover Agent that will start a process instance. This process instance will search the documents that are to be deleted based on your selection and deletes them.
The human service will show a continuously updating status page with the progress of the operation.
Optionally, you can cancel the deletion here. Once it is finished, you get a confirmation for this:
We discussed what local documents are and why you need to take care about deleting them. We looked at a sample to delete the local documents in a batch operation.