Skip to content

Executing a REST action

Using this REST call, you can trigger a REST action that is defined in the workflow of a document definition. This section describes how you can make the REST call.

URL

api/v1/documents

Method

The method that you choose should be checked in the REST Call field of the REST action. Only the HTTP methods POST, PUT, and DELETE are supported.

URL parameters
Parameter Type Required Description
ddName String Yes The name of the document definition to which the REST action belongs.
restAction String No The name of the REST action that you want to trigger. If you do not provide a name, BizzStream tries to find a REST action that supports the same HTTP method as your REST call. If there are no such REST actions, an error is thrown. If there are multiple REST actions that support the HTTP method, BizzStream cannot determine which REST action to trigger and throws and error.
environmentId String No The ID of the environment. If you do not provide the environmentId in the header, you have to provide it in the body of the REST call.
Header Parameters
Parameter Type Required Description
Content-Type String Yes Provide the content type of your call. Only application/json is supported.
X-User-Id String Yes The ID of the user who wants to trigger the REST action. This ID is returned by the authentication call.
X-Auth-Token String Yes The authentication token that the authentication call returned.
Body

A JSON object that contains (part of) the document on which you want to execute the REST action. Depending on your goal, some fields are required:

  • Provide an internal ID in the _id field or an external ID in the externalId field if you want to execute the REST action on an existing document (see the section below for more information). If you use the POST method, the _id field is ignored and a new document is created.
  • Omit the _id and (if applicable) externalId fields if you want to create a new document. In this case, the REST action should contain a Save Document rule.
  • Provide the ID of the environment in the __environmentId_ field if you did not provide the environment parameter in the URL.
  • Provide the accessGroups field if you want to set members of access groups (see the section below for more information).
Response

The document as it is stored in the database after executing the REST action. Depending on the user's permissions, some fields may not be returned.

The response is limited to a maximum, as set with the query limit. The used value is mentioned on the limits page.

Internal and external IDs

A document can contain reference fields. These fields points to one or more (different) documents. For example, a reference field can be used to link a purchase receipt to a project. Bizzstream saves references to the documents by recording the internal BizzStream ID.

External systems often do not know how to handle the BizzStream ID of a document. When a document is sent to BizzStream using this REST call, BizzStream tries to replace external IDs with internal IDs when:

  • The document definitions of the referenced document contains an externalId field.
  • The extenalId field in the referenced document contains an actual value.

Setting access group members

If the REST action contains Save Document rule, you can set the members of access groups by including the accessGroups field in the body of the REST call. This is an array of objects that can contain the following fields:

Field Type Required Description
name String Yes The name of the access group for which you want to set the members.
memberUserNames String Array No An array that contains the usernames of the users in the access group.
memberUserEmails String Array No An array that contains the global e-mail addresses of the users in the access group.
memberGroupNames String Array No An array that contains the names of groups that should be members of the access group.
memberRelatedAccessGroupNames Object Array No An array of objects that contains information about the related access groups. Each object should contain the fields: fieldName (the name of the reference field), accessGroupName (the name of the access group in the referenced document). If the reference field belongs to a line, provide the name of this line in the lineName field.

The following is an example of a accessGroups field with one object:

"accessGroups":[
    {
        "name": "accessGroupName",
        "memberUserNames":["username1"],
        "memberUserEmails":["user@company.com"],
        "memberGroupNames":["accessGroup1"],
        "memberRelatedAccessGroupNames":[
            {
                "lineName": "purchaseLine",
                "fieldName": "article",
                "accessGroupName": "supplier"
            }
        ]
    }
]

Note: By including an object in the accessGroups field, you replace the existing members of an access group with the members that you provide in the object.

Adding or Removing attachments

In BizzStream, attachments fields are an array of attachments objects, for example:

attachmentField:[
      {
           "_id" : "W4yAtXxHhvvWPMYZH",
           "_fileName" : "pizza_salami.jpg",
           "_type" : "image/jpeg"
      },
      {
           "_id" : "naknkDw3Kd7PnZBvM",
           "_fileName" : "pizza_hawaii.jpg",
           "_type" : "image/jpeg"
      }
]
Adding attachments

You can add a new attachment to an attachment field using the save attachment REST call.

Removing attachments

You can remove attachments by removing one or more objects from the array:

attachmentField:[
      {
           "_id" : "W4yAtXxHhvvWPMYZH",
           "_fileName" : "pizza_salami.jpg",
           "_type" : "image/jpeg"
      }
]

Compared to the first example, the attachment pizza_hawaii.jpg is removed and the attachment pizza_salami.jpg remains.

Examples

curl /api/v1/documents?ddName=project&environmentId=a83rh4aX5nzBsGL3S \
    -H "X-Auth-Token: 6IrqyFhbKjpyJZ_NX6dwLmRNxWk0OVffE8aBfauNKUG" \
    -H "X-User-Id: a6gA9rYaGTFKPrT5P" \
    -H "Content-Type: application/json" \
    -X PUT \
    -d '{
        "_id":     "BPmgYZgzEPsfzbN8S",
        "name":    "Voorbeeld Project",
        "code":    "001"
    }'
curl /api/v1/documents?ddName=project&restAction=save \
    -H "X-Auth-Token: 6IrqyFhbKjpyJZ_NX6dwLmRNxWk0OVffE8aBfauNKUG" \
    -H "X-User-Id: a6gA9rYaGTFKPrT5P" \
    -H "Content-Type: application/json" \
    -X PUT \
    -d '{
        "_id":           "BPmgYZgzEPsfzbN8S",
        "name":          "Voorbeeld Project",
        "code":          "001",
        "environmentId": "a83rh4aX5nzBsGL3S"
    }'