Local documents

Local documents are created and used within a business process instance. Local documents are helpful as they can add new content that your users require when they are working with your business process.
To allow local documents to be created and used by your users, you must set up the capability for local documents in your process at development time. At run time, your users work with a user interface you create that includes document controls. You and your users must be aware that local documents have a duration, though you can create a permanent document on an external ECM system based on a local document.

Local documents at development time

You must do set up work at development time to allow your users to create local documents. Begin by checking that Allow locally managed documents is selected in the Folder Management section of the Folders tab in the editor. See Selecting IBM Business Automation Workflow or an external ECM system to manage folders.

Create coaches that provide a user interface for your users. To add, remove and view local documents, a coach must include a Document Explorer control that is configured with the BPM document store. Specifically, set the Folder ID and Server Name configuration options in the Folder Configuration section. Use variables that contain values from a script, which retrieves data from the current process instance. For example, for a client-side human service:
tw.local.folderId = tw.system.processInstance.processInstanceFolderId;
tw.local.serverName = tw.system.processInstance.caseFolderServerName;
For a business process definition (BPD) or server-side service implementation:
tw.local.folderId = tw.system.currentProcessInstance.processInstanceFolderId;
tw.local.serverName = tw.system.currentProcessInstance.caseFolderServerName;
See Document Explorer.

Local documents are, in structure, workflow documents. They can be constructed and worked with programmatically by using REST APIs and JavaScript APIs. The local documents that you create are automatically added to the BPM folder of the instance you attach the document to unless you specify the input parameter hideInPortal as true. Use the Create document operation of the BPM document store to create a local document using a content integration step in a service implementation..

To add an already existing local document to a BPM folder, use the Add document to folder and Remove document from folder operations that are used with the BPM document store.

Local documents at run time

A user works with local documents through a user interface as defined by a document explorer element. Selecting Add Local Document from the + icon, leads to the Add Local Document dialog, where the user follows this set of steps.
  1. Select the type of content, a file, or a link to a URL.
    • Browse to the file, if a file is selected.
    • Enter the URL address, if a URL is selected.
  2. Enter a name for the local document. A name is required.
  3. Add a check mark to Add another document, if you want to continue creating more documents.
  4. The local document is created when you click OK.

Duration of a local document

Business process instances, that is, business processes that are in use, often last a long time. During that time, new ECM content becomes available that can be helpful to the users of the business process. Local documents allow users to bring that ECM content into the business process for the duration of the business process.

For example, your business process might process loans. You might create a local document for a new type of loan during the weeks that your process is running. This new loan contract might undergo several revisions as people begin to use it. You realize that the final revised loan contract might be useful to many people in your organization, so you add the final revised loan contract to an external ECM server for permanent use. Why? Local documents are deleted when the process instance is deleted from the BPM database. Furthermore, if the Allow content operations after completion check box is not selected in the Overview section of a process, you cannot create, modify, or delete existing documents that are attached to the instance.
The diagram shows that local documents are deleted when the process instance is deleted from the BPM database.

If you think a local document can be useful for other processes, you can take steps to turn it into a permanent document on an external ECM system. See How to make local documents permanent.

How to make local documents permanent

A local document might be suited to becoming a permanent document on an external ECM system. Creating a permanent document from a local document can be done through an integration service that follows these steps.
  1. Start by creating an integration service with a Content Integration node. Your integration service then can use the operations in the next steps to move your local document content to a document on an external ECM system. See Building a service that integrates with an ECM system or a BPM store.
  2. Retrieve the content of the local document, that is, the Business Automation Workflow document, by using a Get document content operation on the BPM document store. See Working with document content.
  3. Create a document on an external ECM system by using a Create document operation. Use the output from the previous operation for the content of the new document by using the Content stream (ECMContentStream) input parameter. See Outbound operations for external ECM systems and BPM stores.
  4. Optionally, add a reference to the new document you created in the current process instance by using an Add document to folder operation on the BPM managed store. See Data mapping in Enterprise Content Management operations.
  5. Delete the local document, that is, the Business Automation Workflow document, by using a Delete document operation on the BPM document store. See Data mapping in Enterprise Content Management operations.
Note: Uploading a document with no content and a file size of zero bytes has limitations. Although such a file can be successfully uploaded, its MIME type will not be set. This is because the MIME type is determined by the file content, and with no content in a zero-byte file, no data is sent to the backend. As a result, the backend repository cannot set the MIME type.