public interface DocumentAPI
A document can be stored directly with the process instance, or by reference. If you store a document by reference, the process instance contains a document object that has metadata describing the document: its name, content MimeType, the name of the file of the document, and a URL giving the location of the document. The choice of direct local storage or storage by reference depends on the performance profile of document access within an instance of the process. If you require frequent and rapid access to update the document and the document is not large, use direct storage. If the document is large or is not accessed frequently within a process instance, or is not updated by the process, store it by reference.
Multiple versions of a document can be stored. You can retrieve the latest version or the version that was current at a given milestone (for example process instantiation, or activity completion).
Modifier and Type | Method and Description |
---|---|
Document |
addDocument(long processInstanceId,
String documentName,
String description,
DocumentValue documentValue)
Attach a new document to a process instance.
|
Document |
attachDocument(long processInstanceId,
String documentName,
String fileName,
String mimeType,
byte[] documentContent)
Attach the given document to the specified process instance.
|
Document |
attachDocument(long processInstanceId,
String documentName,
String fileName,
String mimeType,
String url)
Attach a document by reference to the specified process instance.
|
Document |
attachNewDocumentVersion(long processInstanceId,
String documentName,
String contentFileName,
String contentMimeType,
byte[] documentContent)
Attach a new document version to the specified process instance.
|
Document |
attachNewDocumentVersion(long processInstanceId,
String documentName,
String fileName,
String mimeType,
String url)
Attach a new version of a document by reference to the specified process instance.
|
void |
deleteContentOfArchivedDocument(long archivedDocumentId)
Remove the content of an archived document while keeping it's metadata.
|
ArchivedDocument |
getArchivedProcessDocument(long archivedProcessDocumentId)
Get an ArchivedDocument based on it's id.
|
ArchivedDocument |
getArchivedVersionOfProcessDocument(long sourceObjectId)
Get the latest version of the document with the specified identifier.
|
Document |
getDocument(long documentId)
Get the document with the specified identifier.
|
Document |
getDocumentAtActivityInstanceCompletion(long activityInstanceId,
String documentName)
Get the version of the named document when the specified activity completed.
|
Document |
getDocumentAtProcessInstantiation(long processInstanceId,
String documentName)
Get the version of the named document that was current when the specified process instance is instantiated.
|
byte[] |
getDocumentContent(String storageId)
Get content of the document with the specified identifier.
|
List<Document> |
getDocumentList(long processInstanceId,
String name,
int fromIndex,
int numberOfResult)
Get a document list that have the specified name on the process
|
Document |
getLastDocument(long processInstanceId,
String documentName)
Get the last version of the named document for the specified process instance.
|
List<Document> |
getLastVersionOfDocuments(long processInstanceId,
int pageIndex,
int numberPerPage,
DocumentCriterion pagingCriterion)
Get the latest version of all documents attached to the specified process instance.
|
long |
getNumberOfDocuments(long processInstanceId)
Get the number of documents attached to the specified process instance.
|
Document |
removeDocument(long documentId)
Remove the document with the specified identifier and returns it.
|
SearchResult<ArchivedDocument> |
searchArchivedDocuments(SearchOptions searchOptions)
Search for archived documents that meet the search options.
|
SearchResult<ArchivedDocument> |
searchArchivedDocumentsSupervisedBy(long userId,
SearchOptions searchOptions)
Search for archived documents that match the search options and are supervised by the specified user.
|
SearchResult<Document> |
searchDocuments(SearchOptions searchOptions)
Search for documents that match the search options.
|
SearchResult<Document> |
searchDocumentsSupervisedBy(long userId,
SearchOptions searchOptions)
Search for documents that match the search options and are supervised by the specified user.
|
void |
setDocumentList(long processInstanceId,
String name,
List<DocumentValue> documentsValues)
Get a document list that have the specified name on the process
|
Document |
updateDocument(long documentId,
DocumentValue documentValue)
Attach a new document version to a process instance.
|
Document attachDocument(long processInstanceId, String documentName, String fileName, String mimeType, String url) throws ProcessInstanceNotFoundException, DocumentAttachmentException
The document itself does not contain content but is a reference to external content specified by its URL.
processInstanceId
- The identifier of the process instancedocumentName
- The name of the documentfileName
- The filename of the document contentmimeType
- The MimeType of the document content (optional)url
- The URL of the document contentProcessInstanceNotFoundException
- If the identifier does not refer to an existing process instance.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DocumentAttachmentException
- when an error occurs while attaching the documentDocument updateDocument(long documentId, DocumentValue documentValue) throws ProcessInstanceNotFoundException, DocumentAttachmentException, AlreadyExistsException
Depending on the DocumentValue given the document will be internal (with content) or external (with url). The document state is archived and is then updated to the new version
documentId
- The identifier of the document to updatedocumentValue
- The value of the documentProcessInstanceNotFoundException
- If the identifier does not refer to an existing process instance.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DocumentAttachmentException
- when an error occurs while attaching the documentAlreadyExistsException
- If the document already exists.Document addDocument(long processInstanceId, String documentName, String description, DocumentValue documentValue) throws ProcessInstanceNotFoundException, DocumentAttachmentException, AlreadyExistsException
processInstanceId
- The identifier of the process instancedocumentName
- The name of the documentdescription
- The description of the documentdocumentValue
- The value of the documentProcessInstanceNotFoundException
- If the identifier does not refer to an existing process instance.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DocumentAttachmentException
- when an error occurs while attaching the documentAlreadyExistsException
- If the document already exists.Document attachDocument(long processInstanceId, String documentName, String fileName, String mimeType, byte[] documentContent) throws ProcessInstanceNotFoundException, DocumentAttachmentException
The content is stored to enable later retrieval.
processInstanceId
- The identifier of the process instancedocumentName
- The name of the documentfileName
- The name of the file containing the documentmimeType
- The MimeType of the document content (optional)documentContent
- The content of the documentProcessInstanceNotFoundException
- If the identifier does not refer to an existing process instance.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DocumentAttachmentException
- when an error occurs while attaching the documentDocument attachNewDocumentVersion(long processInstanceId, String documentName, String fileName, String mimeType, String url) throws DocumentAttachmentException
processInstanceId
- The identifier of the process instancedocumentName
- The name of the documentfileName
- The name of the file containing the documentmimeType
- The MimeType of the document content (optional)url
- The URL of the document contentInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DocumentAttachmentException
- when an error occurs while attaching the new version of the documentDocument attachNewDocumentVersion(long processInstanceId, String documentName, String contentFileName, String contentMimeType, byte[] documentContent) throws DocumentAttachmentException
The content is stored to enable later retrieval.
processInstanceId
- The identifier of the process instancedocumentName
- The name of the documentcontentFileName
- The name of the file containing the content of the documentcontentMimeType
- The MimeType of the document content (optional)documentContent
- The content of the documentInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DocumentAttachmentException
- when an error occurs while attaching the new version of the documentDocument getDocument(long documentId) throws DocumentNotFoundException
documentId
- The identifier of the document to retrieveDocumentNotFoundException
- If the specified identifier does not refer to an existing document.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.Document removeDocument(long documentId) throws DocumentNotFoundException, DeletionException
this archive and delete mapping on the process, i.e. the content of the document itself will be kept in database, use
deleteContentOfArchivedDocument(long)
to delete the content
documentId
- The identifier of the document to retrieveDocumentNotFoundException
- If the specified identifier does not refer to an existing document.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DeletionException
List<Document> getLastVersionOfDocuments(long processInstanceId, int pageIndex, int numberPerPage, DocumentCriterion pagingCriterion) throws ProcessInstanceNotFoundException, DocumentException
processInstanceId
- The identifier of the process instancepageIndex
- The index of the pagenumberPerPage
- The number of documents to list per pagepagingCriterion
- The sort criterion for the returned listProcessInstanceNotFoundException
- If the identifier does not refer to an existing process instance.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DocumentException
- when any other error occurs during document handlingbyte[] getDocumentContent(String storageId) throws DocumentNotFoundException
storageId
- The identifier of the document to retrieve the content fromDocumentNotFoundException
- If the specified identifier does not refer to an existing document.InvalidSessionException
- when the session is note validDocument getLastDocument(long processInstanceId, String documentName) throws DocumentNotFoundException
processInstanceId
- The identifier of the process instance that the document is attached todocumentName
- The name of the documentInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DocumentNotFoundException
- If the specified documentName does not refer to an existing document attached to this process instanceDocument getDocumentAtProcessInstantiation(long processInstanceId, String documentName) throws DocumentNotFoundException
processInstanceId
- The identifier of the process instancedocumentName
- The name of the documentInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DocumentNotFoundException
- If the specified documentName does not refer to a document attached to the specified process instance.Document getDocumentAtActivityInstanceCompletion(long activityInstanceId, String documentName) throws DocumentNotFoundException
activityInstanceId
- The identifier of the activity instancedocumentName
- The name of the documentDocumentNotFoundException
- If the specified documentName does not refer to an existing document attached to the process instance that contains the activity.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.long getNumberOfDocuments(long processInstanceId) throws DocumentException
processInstanceId
- The process instance identifierInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DocumentException
- when an error occurs during document handlingSearchResult<Document> searchDocuments(SearchOptions searchOptions) throws SearchException
searchOptions
- A SearchOptions
object defining the search optionsInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.SearchException
- when an error occurs during the searchSearchResult<Document> searchDocumentsSupervisedBy(long userId, SearchOptions searchOptions) throws UserNotFoundException, SearchException
userId
- The identifier of the supervising usersearchOptions
- A SearchOptions
object defining the search optionsInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.UserNotFoundException
- when the specified userId does not refer to an existing userSearchException
- when an error occurs during the searchSearchResult<ArchivedDocument> searchArchivedDocuments(SearchOptions searchOptions) throws SearchException
searchOptions
- A SearchOptions
object defining the search optionsInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.SearchException
- when an error occurs during the searchSearchResult<ArchivedDocument> searchArchivedDocumentsSupervisedBy(long userId, SearchOptions searchOptions) throws UserNotFoundException, SearchException
userId
- The identifier of the supervising usersearchOptions
- A SearchOptions
object defining the search optionsInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.UserNotFoundException
- when the specified userId does not refer to an existing userSearchException
- when an error occurs during the searchArchivedDocument getArchivedProcessDocument(long archivedProcessDocumentId) throws ArchivedDocumentNotFoundException
archivedProcessDocumentId
- The identifier of the documentInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.ArchivedDocumentNotFoundException
- when the specified identifier does not refer to an archived documentArchivedDocument getArchivedVersionOfProcessDocument(long sourceObjectId) throws ArchivedDocumentNotFoundException
sourceObjectId
- The identifier of the documentInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.ArchivedDocumentNotFoundException
- If the identifier does not refer to any existing archived document.List<Document> getDocumentList(long processInstanceId, String name, int fromIndex, int numberOfResult) throws DocumentNotFoundException
processInstanceId
- The identifier of the process instance that contains the listname
- The name of the documentfromIndex
- The index of the first element to be retrieved (it starts from zero)numberOfResult
- The max number of result to getDocumentNotFoundException
void setDocumentList(long processInstanceId, String name, List<DocumentValue> documentsValues) throws DocumentNotFoundException, DocumentException
processInstanceId
- The identifier of the process instance that contains the listname
- The name of the document listdocumentsValues
- the values to set the list withDocumentException
- If an error occursDocumentNotFoundException
BaseElement.getId()
void deleteContentOfArchivedDocument(long archivedDocumentId) throws DocumentException, DocumentNotFoundException
After calling this method you will not be able to retrieve the content of the document since it will be erased from the database. This method can be useful for keeping history of a document without overloading the database.
archivedDocumentId
- The identifier of the archived document to remove content onDocumentNotFoundException
- If the identifier does not refer to any existing archived document.DocumentException
- If an error occursBaseElement.getId()
Copyright © 2018 Bonitasoft S.A.. All rights reserved.