Skip to content

REST call

The REST Call rule makes a REST call to an external system. More information about REST can be found here.

When a REST Call rule is executed on a document, BizzStream sends the document as it is stored in the database. This implies that when a user/visitor changed the document but did not execute an action that contains a Save Document rule, the changes will not be send to the external system.

When the option Save Response has been enabled, BizzStream will try to update fields in the document with values found in the response of the external system. When the response includes fields that are also defined in the document definition, BizzStream assigns the fields in the document the value that is found in the response. Fields in the response that are not defined in the document definition are ignored.

Note: BizzStream does not take the user permissions into account when updating the document. This implies that fields to which the user does not have edit permissions will also be updated if these are included in the response of the REST call.

Note: The REST Call rule is subject some limitations. Click here to find out more.

Availability

The rule can be added to:

  • User actions
  • Bulk actions
  • Scheduled actions
  • Rest actions

Properties

Property Required Description
Label No A brief description of the rule. This description is visible in the list of rules and meant to distinguish similar rules from each other.
Description No A longer description of the rule. You can use this field to describe the purpose of the rule is.
URL Yes The URL to which the REST call is made.
Method Yes The HTTP method of the REST call. Possible values are POST, PUT, DELETE and PATCH.
Header Yes This is a JSON object that contains the HTTP header.
Save Response No When checked, BizzStream will try to save the response of the external system into the document (see above).
Execute Only If No The condition that needs to be met in order for this rule to execute. If this field is empty, the rule will always be executed.

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 by using the REST call, BizzStream tries to replace internal IDs with external IDs when:

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

When BizzStream receives a response from an external system that contains external IDs, BizzStream will automatically convert these to internal IDs.

Showing notifications

It is possible for external systems to show a notification to a BizzStream user/visitor. External systems can do so by including fields in the notification that trigger BizzStream to display notifiactions. These notifications have the same style as notifications displayed by the Show Notification rule.

A notification is displayed for each of the following elements that is present in the response of the REST call:

Response Element Field Name Displayed As
Header errorText Error
Header successText Success
Header infoText Info
Body _errorText Error
Body _successText Success
Body _infoText Info

For instance, imagine that the REST call responds with the following header

{
     errorText: "Oops, something went wrong"
}

and this footer

{
    _errorText: "We could not process this stuff.",
    _infoText: "But the call was processed."
}

Then BizzStream displays 3 notifications:

  • Error: "Oops, something went wrong."
  • Error: "We could not process this stuff."
  • Info: "But the call was processed."

Note: Notifications will only be shown when the REST call is part of a user action.