Appian BPM: using documents within custom data type objects

A common problem that developers encounter in most BPM’s is that business objects only support primitive data types as attributes. They do not support document data type as an attribute. This article describes the approach to reference documents in business objects in a relatively simple manner in any BPM and uses Appian BPM to demonstrate the approach. In Appian BPM, the Document data type is used to work with files that flow through processes. This component allows multiple files to be attached.To upload a file from an Appian BPM task form, the SAIL Component “a!fileUploadField” is available. Using “a!fileUploadField”, a single file can be uploaded. However, the same component can be extended further to upload multiple files, one at a time and also display their information. SAIL Recipes has an example of such a multiple file upload extension.

Let’s consider an insurance application where multiple documents can be captured using the multiple file upload component as shown below.

These documents are easily accessible throughout the process using the Document data type variable but if we need to store additional data for each of the documents or use these documents in Business objects (Custom Data type in Appian) in the same or other processes then it is currently not possible to do this using the out-of-box functionality. This can be easily addressed by storing the references to these documents in those business objects. Below are some details around how Document data type works with the UI component “a!fileUploadField” and how it can be referenced withinCustom Data Type objects (CDTs) to store data related to a document (e.g. document metadata or document categorization details).

In the Appian BPM task form,when a file is uploaded through the “a!fileUploadField” component, Appian first uploads the file to temporary location with a temporary id. The file gets copied to the desired location and the corresponding document reference is updated with the correct document id only when the user submits the form. The Document data type variable reference should be used to refer to the actual file in Appian BPM only after the form is submitted and the correct reference is populated.

Internally, the Appian Document data type is mapped to a Long value called documentid. If the document is required to be referenced outside of the process in an external structure such as a CDT, then the document’s documentid can be stored in a CDT as a Long data type. To display the file in the SAIL interface based on this documentid,the “todocument” function can be used to convert it into a Document data type.

The grid below shows the insurance application details (which is a CDT)and refers to the insurance documents (uploaded through multiple file upload extension shown in previous image) through the Long value for the documentid’s.This approach allows us to store the document reference and its associated data in one CDT.

To Summarize:

1. Whenever you use the “a!fileUploadField” component, please make sure that you use the document reference only after the page is submitted and the actual reference is availablein the Document data type variable.

2. The Appian BPM Document data type is mapped to a long value internally so it can be easily stored in an external structure as a reference to allow it’s usage at a later point.