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

Header Parameters

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:

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"
    }'