Many Ziflow customers use Ziflow API & webhooks to integrate with internal or third-party services. This document provides common JsonPath variables and webhooks.
Webhooks
Action & Type | Endpoint URL | Code | Notes |
Create a new folder. (POST) |
|
{ "name": "New Folder Name" } | This creates a new folder based on an action. Variables can be used to name the folder according to a custom property. |
Turn the minor version on or off. (PUT) |
| { "minor_version": false or true } | To turn on, set the value to true. To turn it off, set the value to false. |
Move proof to folder. (PUT) |
|
{ "folder_id": "PLACE FOLDER ID HERE" } | To find the folder ID, open the folder in webapp and copy the ID from the end of the URL. e.g. https://demo.ziflow.io/#/folders/50826969-889a-49a6-a8fa-ea8b8dc56cee |
Automate deadline from intake form submission. (PUT) |
| #{$.{"stages":$append($spread($.proof.stages)[id][[0..1-2]],$append($spread($.proof.stages)[id][[1..100]],$.proof.stages[1-1].{"id":id,"deadline":"${$.proof.custom_properties.[?(@.id=='PLACE PROPERTY GROUP ID HERE')].properties[?(@.id=='PLACE PROPERTY ID HERE')].value}"&"T12:00:00.000Z"}[]))}}# |
This automatically pulls the requested due date property from an intake form and sets that date as the deadline within the assigned workflow template. |
Turn off a download of the original file for the previous version. (PUT) |
|
{ "allow_source_download": false } | Use it to turn off the download original file setting for a previous proof version. |
Update a Proof Brief. (PUT) |
| {"brief": { "text": "Put Brief Verbiage Here" }} | With this webhook, you can update a brief section on a proof. |
Add a Reviewer (allows to enable “manage” unlike the zibot). (PUT) |
|
[ { "email": "#{$.form.submitter_email}#", "view": true, "comment": true, "decision": false, "manage": false, "share": true } ] |
Edit “Proof ID” and “Stage ID” as needed; this refers to the first stage of the proof created by a “Create Proof” zibot, with that zibot being the first zibot in a flow. |
JsonPath variables
Name | JSONata Variable | Notes |
Proof ID | #{$.proof.id}# | Use this if you want to reference a proof ID. |
Previous Proof Version ID |
#{$.proof.versions[-2].version_id}# | You can use this in a webhook to change the previous version after a new version is added for e.g Turn off download of original file for previous version. |
Proof Custom Property (single line text) | #{$.proof.custom_properties[name="Property Group Name"].properties[name="Property Name"].value}# | This can be used when referencing a text property in either webhook bodies or paths. When you just use the second version, you need to make sure to add the # on either side. That denotes that you’re using JSONata instead of just JSON, which allows you to use the more simplified referencing for the name of the property group and property. |
Proof Custom Property (single select list) |
#{$.proof.custom_properties[name="Property Group Name"].properties[name="Property Name"].value_enum[*].value}# | This can be used when referencing a single select lists property in either webhook bodies or paths. When referencing a value, use |
Does a Custom Property value exist (single or multi select list)? | #{$exists($.proof.custom_properties[name="group name"].properties[name="custom property name"].value_enum[0].value)}# |
Use in a path with that token on the left and then is/is not and true/false depending on if you’re looking for there to be a value or not. |
Form Custom Property (text or dates) | #{$.form.custom_properties[name="Property Name Here"].value}# |
This is used when referencing a custom property on an intake form. It can also be used in webhook bodies or paths. |
Form Custom Property (single select list or radio button) | #{$.form.custom_properties[name="Property Name Here"].value_enum[0].value}# |
This is used when referencing a custom property on an intake form. It can also be used in webhook bodies or paths. |
Does an Intake Form Property value exist (single select list)? | #{$exists($.form.custom_properties[name="property name"].value_enum[*].value)}# | Use in a path with that token on the left and then is/is not and true/false depending on if you’re looking for there to be a value or not. |
Form Submitter Email |
#{$.form.submitter_email}# | Use this if you want to reference someone who submitted an intake form. |
Stage Name |
#${$.stage.name}# | Used when referencing a specific stage name. Also can be used to push the current stage name to a column in another tool (ex: monday.com, Airtable, etc.) |
Reviewer Email |
#{$.reviewer.email}# | Used when referencing a reviewer by email. You can also use this when configuring flows with paths. |
ID from First Zibot |
#{$.zibot[0].data.id}# | Can be used to put in a PM tool’s URL in a webhook to reference the ID of a task/card/issue that Ziflow created in a previous step of a connect flow. |
Proof ID when used in an Intake Form Flow (and the first zibot of flow is “create proof”). |
#{$.zibot[0].data.id}# | URL for webhooks: https://api.ziflow.io/v1/proofs/{$.zibot[1].data.id}/stages/{$.zibot[1].data.stages[0].id}/reviewers Take out the /stages part if you’re only wanting to refer to the proof, not the stages. |
Specify the Name of the Custom Property that triggers a “proof is updated - custom property” flow |
#{$exists($.trigger.proofUpdateInfo.fields.new_value[name="Asana"].properties[name="Asana Task ID"].name)}# is true | Can be used in the path to specify the name of the custom property that was changed when the trigger is that a proof was updated. Then, you can limit the flow to only trigger if a certain custom property is updated. |
Specify the Time/Date that a proof is approved. | #{$fromMillis($.trigger.proofSerializedModel.calculatedProofStatusDate)}# |
It can be used as a token to populate a custom property. |
Text of Comment Made |
#{$.comment.comment}# | This can add comments made on a proof as a subtask to a task in a PM tool (e.g Asana). |
Link Directly to a Comment | {$.proof.public_link} | This will take someone to the proof with the specific comment opened up in the comment bar. |
Label of a Comment | #{$.comment.labels.label}# | Will display the value of the label on a comment. |
Text to Review from Intake Form |
#{$.trigger.proofSerializedModels.formTextToReview}# | It can be sent as a value to a column in a PM tool to display the text entered when submitting text via the intake form. |
Check if a value is null with $boolean | #{$boolean(zibot[1].data.data.items.board.workspace_id)}# |
This is a token example, but use $boolean to get a true/false for not null/null. |
Proof Thumbnail | #{$.proof.thumbnail_link}# | For sending a thumbnail preview to a PM Tool. |
URL when referencing Proof ID in an Intake Form Flow and adding Reviewers | https://api.ziflow.io/v1/proofs/#{$.zibot[1].data.id}#/stages/#{$.zibot[1].data.stages[0].id}#/reviewers# |
Might be helpful if you want to add reviewers to the proof created via an intake form flow. |
Workflow Template Name | #{$.proof.workflow_template.name}# | Use this to reference a workflow template. |
Folder Name | #{$.proof.folder.name}# | Use this to reference a folder name. |
Proof Stage Status (Completed/In progress/View only) | #{$.proof.stages[$.name="XYZ"].status.status}# | This can be used if you want to trigger a Zibot action based on a stage status. |
Proof Stage Status (Approved, Changes Required, etc) | #{$.proof.stages[name="XYZ"].status.decision_status}# | This can be used if you want to trigger a Zibot action based on a stage decision. |
Proof Version | #{$.proof.version}# | Use this to reference a proof version. |
Proof Source File Name | #{$.proof.source_files.name}# | Use this to reference a proof source file name. |
Stage Deadline | #{$.proof.stages[n].deadline}# | The number inside the [] indicates the stage number (n+1) |
Integration property ID | #{$.zibot[0].data.integration_properties[application_name="Asana"].groups.properties[name="Task"].value}# | This references ID from an integration property if you don't want to use a clickable token for some reason. |
Check if the stage name exists on a proof | #{$exists($.proof.stages[name="Stage name"].name)}# |
Use this to verify if a particular stage name exisis on a proof. |
Using regex in JSONata
You can use regular expressions when building flows/paths using JSONata (query and transformation language) to work with JSON data. Many regex functions can help you with formatting data according to your needs.
Please refer to the JSONata docs for more information about using regular expressions.
Testing your regex expressions combined with Ziflow data can be done using the JSONata Exerciser. You can send a built token #{$}# to the Webhook.site to view request details. To achieve this, add a Webhook Zibot to your Ziflow flow with a POST request to the Webhook site using a created regex token.
Please note that using Webhook.site + https://try.jsonata.org/ !!!
JSONata expressions with regex
Comment text, including the email address of the mentioned reviewer. | #{$replace($.comment.comment, /\$\{reviewer[^\}]+\}/, $.proof.stages.members[id=$match($$.comment.comment, /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/).groups[0]].email)}# |