Skip to main content
Version: 2024.1

Attachments operations

Rest API allows user to perform all basic operations on attachments, such as view, add, update and delete. ‘Get attachment’ beside described below scopes requires at least view attachment privileges – Access all workflow instances and attachments set in Designer Studio. All of the other operations require at least attachment edit privileges – Access and edit all workflow instances.

There are two ways of interacting with attachments via API. The first allows changes and updating or creating a workflow instance. The second works on the attachment itself regardless of the instance.

Operations on attachments with a workflow instance endpoints​

Get attachment metadata​

GET /api/data/v6.0/db/{dbId}/elements/{id} [Scopes: App.Elements.Admin.All; App.Elements.Read.All; App.Elements.ReadWrite.All; User.Elements.Admin.All; User.Elements.Admin.<ProcGuid>; User.Elements.Read.All; User.Elements.Read.<ProcGuid>; User.Elements.ReadWrite.All; User.Elements.ReadWrite.<ProcGuid>] – is a basic endpoint to get the workflow instance data. Along with all the instance data we will also get attachments metadata, they are available in the attachments property. Below is example response. The Root node is an array containing all attachments from selected element.

"attachments": [
    {
      "id": 1569,
      "author": {
        "bpsId": "t.green@webcon.pl",
        "name": "Thomas Green"
      },
      "updatedBy": {
        "bpsId": "t.green@webcon.pl",
        "name": "Thomas Green"
      },
      "creationDate": "2020-02-07T06:51:44.559Z",
      "modificationDate": "2020-02-07T09:37:13.729Z",
      "version": 2,
      "name": "Webcon_invoice_01_2020.pdf",
      "description": "",
      "group": "Invoices"
    }
  ]

The ‘element’ endpoint does not return the content of attachments, for this we will have to use one of the methods described later in the article.

Start an instance with attachment​

The basics on how to start new instance are described in this article, here we will focus on adding attachments. To add one or more attachments simply extend the start instance request with an additional attachment node, that is an array of attachments. Each attachment object has:

  • name – required value with desired name for attachment, it should contain file extension
  • content – required value that should be sent in form of base64 string with file content
  • description – optional field for attachment description
  • group – optional parameter for specifying attachment’s group, it should be set in ID#name format. When the group identifier is not sent, the attachment will be added to the default group Here is simple example of request body, and curl used to start new instance with an attachment:
{
  "workflow": {
    "guid": "a31da521-1352-4c63-8be6-5887a8fddc19"
  },
  "formType": {
    "guid": "64148798-6847-49e0-8450-52969c6db3f3"
  },
  "attachments": [
    {
      "content": "U2FtcGxlIHZhbHVlIFdFQkNPTg==",
      "name": "Thomas Green CV.pdf",
      "group": "3#Application files"
    }
  ]
}
curl -X POST "http://dev20/WEBCONBPS/api/data/v6.0/db/1/elements?path=default" 
-H "accept: application/json" 
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn (…) eyJiYWWqrZ6FdBI " 
-H "Content-Type: application/json" 
-d "{ \"workflow\": { \"guid\": \"a31da521-1352-4c63-8be6-5887a8fddc19\" }, \"formType\": { \"guid\": \"64148798-6847-49e0-8450-52969c6db3f3\" }, \"attachments\": [ { \"content\": \"U2FtcGxlIHZhbHVlIFdFQkNPTg==\", \"name\": \"Thomas Green CV.pdf\" \"group\": \"3#Application files\" } ]}"

You can add a new attachment to the existing workflow instance in the same way, just use the endpoint for instance update – PATCH /api/data/v6.0/db/{dbId}/elements/{id} [Scopes: App.Elements.Admin.All; App.Elements.ReadWrite.All; User.Elements.Admin.All; User.Elements.Admin.<ProcGuid>; User.Elements.ReadWrite.All; User.Elements.ReadWrite.<ProcGuid>]

Update existing attachments​

To update attachments on ongoing workflow instance we will use instance update endpoint – PATCH /api/data/v6.0/db/{dbId}/elements/{id} [Scopes: App.Elements.Admin.All; App.Elements.ReadWrite.All; User.Elements.Admin.All; User.Elements.Admin.<ProcGuid>; User.Elements.ReadWrite.All; User.Elements.ReadWrite.<ProcGuid>] The request is similar to the one used for adding new attachments. The main difference is an id property, that is required to identify file that we want to update. Other properties are optional and only those that have been sent will be updated, the rest of the attributes of the attachment will remain unchanged. Here is an example request:

curl -X PATCH "http://dev20/WEBCONBPS/api/data/v6.0/db/1/elements/1393" 
-H "accept: application/json" 
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn (…) eyJiYWWqrZ6FdBI" 
-H "Content-Type: application/json" 
-d "{\"attachments\":[{\"id\":86,\"content\":\"U2FtcGxlIHZhbHVlIFdFQkNPTg==\",\"description\":\"Personal data protection clause updated\"}]}"

Delete attachment from a workflow instance​

To delete attachment from a workflow instance you can use the same endpoint as for the update. Just send the attachment id, as well as the property delete set to true. Here is example request:

curl -X PATCH "http://dev20/WEBCONBPS/api/data/v6.0/db/1/elements/1393" 
-H "accept: application/json" 
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn (…) eyJiYWWqrZ6FdBI" 
-H "Content-Type: application/json" 
-d "{\"attachments\":[{\"id\":86,\"delete\":true}]}"

Methods of creating, updating and deleting attachments via elements update endpoint can be combined in any way, so you can add, modify or delete different attachments in one request.

Direct operations on attachments​

In addition to modifying attachments when updating an instance, we can modify them independently using dedicated endpoints. These operations require the same set of user privileges as mentioned in the introduction.

Get attachments​

There are three ways to get attachments data beside the one that was described in first section:

  • Get all attachments from selected instance. This can be done on endpoint

GET /api/data/v6.0/db/{dbId}/elements/{id}/attachments [Scopes: App.Elements.Admin.All; App.Elements.Read.All; App.Elements.ReadWrite.All; User.Elements.Admin.All; User.Elements.Admin.<ProcGuid>; User.Elements.Read.All; User.Elements.Read.<ProcGuid>; User.Elements.ReadWrite.All; User.Elements.ReadWrite.<ProcGuid>] The response contains exactly the same properties as mentioned earlier in the section about the get instance endpoint, but the attachment object is extended with the content property. Content is returned in the base64 format.

  • Get single attachment selected by its ID. Endpoint:

GET /api/data/v6.0/db/{dbId}/elements/{id}/attachments/{attid} [Scopes: App.Elements.Admin.All; App.Elements.Read.All; App.Elements.ReadWrite.All; User.Elements.Admin.All; User.Elements.Admin.<ProcGuid>; User.Elements.Read.All; User.Elements.Read.<ProcGuid>; User.Elements.ReadWrite.All; User.Elements.ReadWrite.<ProcGuid>] Response contains one attachment object with exactly same model as method above.

  • Get just the attachment content. Enpoints:

GET /api/data/v6.0/db/{dbId}/elements/{id}/attachments/{attid}/content [Scopes: App.Elements.Admin.All; App.Elements.Read.All; App.Elements.ReadWrite.All; User.Elements.Admin.All; User.Elements.Admin.<ProcGuid>; User.Elements.Read.All; User.Elements.Read.<ProcGuid>; User.Elements.ReadWrite.All; User.Elements.ReadWrite.<ProcGuid>] Response contains object with only one property – content, its value is base64 encoded file content.

GET /api/data/v6.0/db/{dbId}/elements/{id}/attachments/{attid}/stream [Scopes: App.Elements.Admin.All; App.Elements.Read.All; App.Elements.ReadWrite.All; User.Elements.Admin.All; User.Elements.Admin.<ProcGuid>; User.Elements.Read.All; User.Elements.Read.<ProcGuid>; User.Elements.ReadWrite.All; User.Elements.ReadWrite.<ProcGuid>] Response contains file stream

Delete attachments​

To delete selected attachment you should use DELETE /api/data/v6.0/db/{dbId}/elements/{id}/attachments/{attid} [Scopes: App.Elements.Admin.All; App.Elements.ReadWrite.All; User.Elements.Admin.All; User.Elements.Admin.<ProcGuid>; User.Elements.ReadWrite.All; User.Elements.ReadWrite.<ProcGuid>] Endpoint does not require any request body. Here is an example:

curl -X DELETE "http://dev20/WEBCONBPS/api/data/v6.0/db/1/elements/1393/attachments/86" 
-H "accept: application/json" 
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn (…) eyJiYWWqrZ6FdBI"

Modify attachment​

In order to edit existing attachment use the PATCH /api/data/v6.0/db/{dbId}/elements/{id}/attachments/{attid} ([Scopes: App.Elements.Admin.All; App.Elements.ReadWrite.All; User.Elements.Admin.All; User.Elements.Admin.<ProcGuid>; User.Elements.ReadWrite.All; User.Elements.ReadWrite.<ProcGuid>]) endpoint. It uses the same value model as edit on element with the exception of id which is passed in the query. Here is an example of changing attachment content, description and group:

{
  "content": " U2FtcGxlIHZhbHVlIFdFQkNPTg==",
  "description": "Document signed by Thomas Green",
  "group": "12#Approved documents"
}

Add new attachment​

Endpoint POST /api/data/v6.0/db/{dbId}/elements/{id}/attachments ([Scopes: App.Elements.Admin.All; App.Elements.ReadWrite.All; User.Elements.Admin.All; User.Elements.Admin.<ProcGuid>; User.Elements.ReadWrite.All; User.Elements.ReadWrite.<ProcGuid>]) is used to add new attachment to an existing workflow instance. It uses the same model as modify endpoint, but the name and content are required. Remember that the file name should be sent and it should contain the extension.

Detailed descriptions of each endpoint along with data models and examples are available in swagger that comes with your WEBCON BPS installation. It is available under https://[your portal address]/api. In addition you can test each endpoint live by authorizing with an authentication token.