
Automation
Automation allows you to create a set of rules for modules of Zoho Books based on which appropriate actions would be performed. A good example would be the case where a congratulatory e-mail is sent automatically to the team members when a quote for goods worth over $1000 gets accepted by a client.
In the next few steps, you will be learning about:
- Creating and describing a Workflow.
- Deciding when to execute the workflow.
- Setting the conditions for executing the workflow.
- Associating actions such as Email Alerts, Field Updates and Webhooks with a workflow.
- Connecting to an external web service provider using Webhooks.
To get started with workflows, navigate to > Automation.
Setting up a new workflow rule
- Name your workflow
- Choose when to trigger the workflow
- Workflow types
- Filter the triggers
- Actions
- Other Actions
Setting up a new workflow rule
A workflow rule consists of actions that comprises of Email Alerts, Field Updates and Webhooks that play an essential role in executing a task. A workflow rule may employ one or more actions to accomplish the task. To set up a workflow rule in Zoho Books, navigate to > Automation> Workflow Rules.
Name your workflow
Field | Description |
---|---|
Workflow Rule Name | Give a unique name for the workflow rule. |
Module | Select the module for which you wish to create a workflow. |
Description | Give a small description for your workflow rule. |
Choose when to trigger a workflow
You can choose when to trigger the workflow based on the parameters you select in the following fields.
Workflow Type
There are two types of workflows:
- Event Based
- Date Based
Event Based: If the workflow is Event Based, then the workflow is triggered when a module is:
- Created
- Edited
- Created or Edited
- Deleted
When a module is Edited or Created or Edited, additional fields appear.
Field | Description |
---|---|
Execute the workflow when | There are 3 options to choose from -When any field is updated. -When any selected field is updated. -When all selected field are updated. If you select When any selected field is updated or When all selected fields are updated in the drop down, an additional box will appear where you can select any 3 fields of the module. |
Just Once or Overtime? | Just Once- The workflow would be executed when the criteria is met for the first time. Everytime- The workflow would be executed everytime the criteria is met. |
Date Based:
If the workflow is Date Based, additional fields appear.
Field | Description |
---|---|
Date of Execution | Select the workflow to be triggered on any number of days before or after Module Date, Expiry Date or Created Time from the drop down.![]() |
Execution Time | You may choose the exact time of execution by selecting the corresponding hh or mm . |
Execution Cycle | You may choose the frequency of triggering a workflow by choosing Once, Monthly or Yearly from the drop down.![]() |
Filter the triggers
Filter the triggers section allows you to set one or more conditions based on which the action will be executed.
Field | Description |
---|---|
Condition | The filter will be triggered based on the criteria you set. You can also add multiple criteria by clicking on + Add Criteria based on which the workflow rule will be executed.![]() The condition for the next criteria may be AND or OR depending on whether you wish to include both or either one of the criteria. Also, you can change the criteria pattern as you want by selecting Change Criteria. |
Field Attributes | The field is used to select an attribute from the list that broadly covers the terms that are related to the module.![]() |
Rules | Select the rules based on which the system should filter the trigger. If the field has alphanumeric values, the rules are,![]() If the field has only numerical values, then the rules are, ![]() |
Value Field | Enter the value of the attribute for which the filter must be applied. |
Editing Criteria Pattern:
You can edit the criteria pattern to suit your requirements by selecting Change Criteria. The editor allows you to define a pattern of your choice using simple AND/OR logic. For example, if you wish to trigger the workflow rule When Quote Number is 1 AND either Quote Status isn’t Invoiced OR Total is equal to 500,
The pattern is (((1)AND 2) OR 3). If you feel the criteria pattern does not match your requirement, you can edit it to be (1AND (2 OR 3)).
Click Save to continue.
Note: You can have a maximum of 10 criteria for each Workflow Rule.
Actions
Once the rules have been set, the actions to be taken upon encountering the conditions has to be decided. You can customize the actions to suit your business needs and program it to act immediately or at a particular time.
Immediate Actions:
Field | Description |
---|---|
Type | Select one of the three types of actions, -Email Alerts -Field Updates -Webhooks You can also add multiple actions by clicking on +Add New Actions. |
Name | The field should contain the name of the Email Alerts, Field Updates or Webhooks. For example, in the case of an email alert, you can either pick the ones from the list you have already created or you can add a new one by selecting + Add New Email Alert.![]() Follow the same steps for Field Updates and Webhooks. |
Details | The details of the action is displayed here. |
Time Based Actions:
If you wish to schedule actions for a particular time, select the check box next to Would you like to add time based actions?. This will display additional fields to enter the desired time.
Field | Description |
---|---|
Execution Time | Enter the desired number of days before or after, -Rule Trigger Date -Module Date -Expiry Date -Created Time -Modified Time |
Next, select the type of action that you wish to take. It can be an Email Alert, Field Update or a Webhook. You can also add multiple time based actions by selecting +Add New Time Based Action.
Note: You can add a maximum of 5 time based actions. Also, each time based action can have a maximum of 5 actions.
Finally, click Save to create the workflow rule to implement it for the modules in Zoho Books.
Other Actions
You can also mark your workflow rules as Active or Inactive. To do so, hover the cursor and select mark as active or mark as inactive. To delete the workflow rule, click on the Trash icon.
Edit a workflow rule:
You can edit a workflow rule by simply clicking on one of the workflow rules from the list or by hovering over a workflow rule and select edit.
Filter workflow rules:
To filter the workflow rules list, follow these steps:
- Navigate to
> Automation > Workflow Rules.
- Under Module, select one from the drop down to filter the workflows based on the module for which the workflow has been created.
You can also filter workflow rules based on whether they are active or inactive. Based on your selection, the corresponding workflow rules will be displayed as a list.
Note:
- You can create a maximum of 10 workflow rules for each module.
- Workflow Rules cannot be applied on invoices that were imported into Zoho Books.
Email Alerts
The following steps will explain how to set up an email alert for any module in Zoho Books.
Creating a new Email Alert:
To set up an email alert, navigate to > Automation > Email Alerts and click on + New Email Alert.
Field | Description |
---|---|
Name | Give a unique name for the email alert. |
Module | Select the module for which you wish to create an email alert. |
Email Template | You can pick a template from the drop down or click on + Add New Email Template if you wish to create a new one.![]() |
Email Recipients | Pick contacts from the drop down, to whom you wish to send the email alerts. |
Additional Recipients | If you wish to send out email alerts to more people, enter their email addresses separated by a comma. Please note that you can add a maximum of 10 additional recipients. |
Click on Save to create a new email alert. You can now select one of the many email alerts created, from the drop down, to notify you when a workflow is triggered.
Other Actions
Delete an email alert:
To delete an email alert, hover the cursor next to an email alert on the list and click on the Trash icon.
Filter email alerts:
To filter the email alerts list, follow these steps:
- Navigate to
> Automation > Email Alerts.
- Under Module, select a module from the drop down for which the email alert has been created.
Based on your selection, the corresponding email alerts will be displayed as a list.
Note:
- You can create a maximum of 5 email alerts for each workflow rule.
- A maximum of 500 email alerts can be triggered per day.
In-app Notifications
Zoho Books lets you create in-app notifications to notify your users of an event or a significant activity that has taken place in your organization. You will be able to set this for all the modules and also choose when to trigger the notification.
Scenario: Let’s say the sales team has made a sale worth 100000 in your organization. All the admins and users of the organization may not be aware of the sale. Triggering an in-app notification for invoices whose total is above the organization’s average sale value would have notified all the users of the organization.
Similarly, you will be able to set up a workflow rule to trigger in-app notifications for your organization. Here’s how:
- Go to Settings > Automations > Workflow Rules > + New Workflow Rule.
- Create a new workflow rule by entering a name and selecting the module.
- Choose when you want to trigger the notification – Event Based or Date Based.
- Set up filters and criteria for the workflow and click Next.
- Select the Action Type as In-app Notifications.
- Create a new notification by clicking + New In-app Notification under Sale.
- Enable the option to add time based actions and choose when you would like to execute the action.
- Set the criteria and click Save.
The next time the action occurs, selected recipients will be notified in the Bell icon. Click it to view the details.
Field Updates
The option of Field Updates allows you to automatically make changes to a field of a particular module for which the workflow has been triggered. For example, you can choose to automatically extend the expiry date to 30th June 2015 of a quote if the total amount is greater than or equal to $500. In this case, the Expiry Date field is changed to the above date if the Total field is “>=“500.
To set up a field update, navigate to > Automation > Field Updates and click on + New Field Update.
Field | Description |
---|---|
Name | Give a unique name for the field update. |
Module | Select a module for which you wish to create a field update. |
Update | Select the field in which you wish to make changes upon triggering a workflow from the drop down. -Reference # -Expiry Date -Sales Person -Notes -Terms & Conditions -Adjustment Description Enter the value of the field in the corresponding box. If you wish to update the field with an empty value, check the box Update with empty value?. ![]() |
Click on Save to create a new field update. You can now select one of the many field updates created to implement changes when the workflow is triggered.
Other Actions
Delete a field update:
To delete a field update, hover the cursor next to a field update on the list and click on the Trash icon.
Filter field updates:
To filter the field updates list, follow these steps:
- Navigate to
> Automation > Field Updates.
- Under Module, select a module from the drop down for which the field update has been created.
Based on your selection, the corresponding field updates will be displayed as a list.
Note: You can create a maximum of 3 field updates for each workflow rule.
Webhooks
Webhooks facilitates communication with third-party applications by sending instant web notifications every time an event occurs in Zoho Books. With Webhooks, you can configure both HTTP & HTTPS URLs and associate them in workflow rules to automate the entire notification process.
For example, you can associate your Zoho Books account with an SMS provider with a webhook to thank your customer by sending a message automatically if the total amount paid exceeds $1000.
For general information about webhooks, please refer to webhooks.org.
To set up a webhook, navigate to > Automation > Webhooks and click on + New Webhook.
Field | Description |
---|---|
Name | Give a unique name for the webhook. |
Module | Select the module for which you wish to create a webhook. |
Description | Give a small description of the webhook. |
URL to notify | Enter the URL of the external service provider’s API. For example, if you want Zoho Books to add or change data in Zoho CRM, the URL would be https://crm.zoho.com/crm. |
Method | Specify the function you want to call at the external service: POST: Requests that data sent must be considered as new. PUT: Requests that data sent should be considered as a modified version of the one already present. DELETE: Requests that the data must be deleted. |
Custom Parameters | You can add custom parameters. in the webhook such as Auth Token, Security Token, API Key etc. based on which the URL will be appended. Enter the required parameter under Parameter Name and the corresponding value under Parameter Value. If you wish to add multiple parameters, select + Add Custom Parameters. |
Entity Parameters | Append All Parameters- Select this option to send all parameters from Zoho Books to the external service. Append Selected Parameters- Select this option to send selected parameters from Zoho Books to the external service. |
URL Preview | The URL generated for this webhook will be displayed here. |
When you setup webhooks, all your contacts’ details in your Zoho Books organization (name, phone number, address and email address) will be shared with the URL you want to notify.
Entity Parameters
There are two options available while communicating data with a third party application, namely,
- Append All Parameters- Select this option to communicate all data as and when it is created.
- Append Selected Parameters- Select this option to transfer only the data you want to send. If you choose this option, additional fields appear.
Field | Description |
---|---|
Parameter Name | Enter the name of the parameter that you wish to append and select the module in the corresponding box. |
Parameter Value | Select the desired parameter from the drop down. |
Note: You can add multiple entity parameters by selecting +Add Entity Parameter. You can add a maximum of 10 entity parameters.
User Defined Parameters
If you wish to add user defined parameters while accessing an external service, select the box Add User Defined Parameters.
Field | Description |
---|---|
Parameter Name | Enter the name of the parameter which you wish to update. |
Value Description | Select a module of Zoho Books from the first drop down and select the corresponding parameter from the drop down of the adjacent box. This will generate the placeholder string for that parameter. You can enter the custom code in different formats. For example, if you wish to send a JSON or XML string with parameter values from a quote, you can use the user defined parameters and placeholders format. If you wish to include the placeholder in the string, select Insert Placeholder. |
Click on Save to create a webhook. You can now select one of the many webhooks created to connect with an external service provider when a workflow rule is triggered.
Other Actions
Delete a webhook:
To delete a webhook, hover the cursor next to a field update on the list and click on the Trash icon.
Filter webhooks:
To filer the webhooks list, follow these steps:
- Navigate to
> Automation > Webhooks.
- Under Module, select a module from the drop down for which the webhook been created.
Based on your selection, the corresponding webhook will be displayed as a list.
Note:
- You can create only 1 webhook for each workflow rule.
- A maximum of 500 webhooks can be triggered per day.
Events
The Events section in Zoho Books enables you resend/check the status of your webhooks.
To check the status of your webhook,
- Use the filter to sort your webhooks based on their status.
To resend a webhook,
Navigate to Events tab and click the event for which the webhook has to be sent again.
Click Resend to resend the webhook.
Custom Functions
Custom functions in Zoho Books allows you to write small pieces of code to automate your business processes. Be it providing a special discount on your customers’ invoice, or adding a late fee when an invoice becomes overdue, all you have to do is write a piece of code using Deluge script and link it to a workflow rule and automation of the process will be taken care of.
What is Deluge?
Deluge(Data Enriched Language for the Universal Grid Environment) is an online scripting language integrated with Zoho Creator. It enables users to add logic to the application, incrementally, making it more powerful and robust.
To know about Deluge, refer the Deluge Reference Guide.
If you wish to learn Deluge by writing code samples, click here.
Creating and Executing a Custom function
To setup a custom function,
- Navigate to Gear icon > Automation > Custom Functions and click on + New Custom Function.
- Enter a name for your custom function and provide a small description.
- Choose the module for which you wish to create the custom function.
- Now, type in or drag the parameters that are mentioned on the left side of the script-box.
- Choose the parameters of your choice and set the conditions for your custom function.
- Once done, click Save for the changes to take effect.
Now, the next step is to create a workflow rule using the newly created custom function.
- Head back to the Automation section and click on Workflow Rules.
- Create a new workflow and set the triggers.
- Now, under the Actions tab, choose Custom functions and select your newly created custom function.
- Click Save.
Now, whenever the criteria is met, the workflow rule will be triggered, which in turn will trigger the custom function.
Default fields
As of now, custom functions support User, Organization, Quote, Invoice, Sales Order, Purchase Order, Customer, Recurring Invoice, Expense, Bill, Recurring Bill, and Item modules.
These modules will have the following fields from which you can get the necessary parameters for your custom function.
user
The user field supports the following parameters:
Key Fields | Description |
---|---|
name | Name of the user |
zuid | ZUID of the user |
organization
The organization map supports the following fields:
Key Fields | Description |
---|---|
organization_id | Your organization ID |
name | Organization name |
time_zone | Time zone of your organization |
language_code | Organization’s language |
date_format | Your organization’s date format |
currency_id | Currency ID |
currency_code | Currency code |
currency_symbol | Currency symbol |
address | Organization address |
phone | Organization’s contact number |
fax | Fax number |
website | Organization URL |
Email address | |
portal_name | Portal name of your organization |
Sample map:
{
"time_zone": "Asia/Calcutta",
"language_code": "en",
"currency_id": "7605000000000099",
"phone": "99999999999",
"fax": "check",
"website": "",
"email": "charles@zylker.com",
"address": {
"zip": "624001",
"country": "India",
"city": "New Delhi",
"street_address2": "Block 15",
"street_address1": "6/35 Garden Lane,",
"state": "Delhi"
},
"organization_id": "12345678",
"name": "Zlyker Industries",
"date_format": "dd MMM yyyy",
"currency_symbol": "Rs.",
"portal_name": "zylkerindustry",
"currency_code": "INR"
}
quote
The quote map supports the following fields:
Key Fields | Description |
---|---|
quote_id | Quote ID |
quote_number | Your quote number |
date | Quote date |
reference_number | Reference number of your Quote |
status | Status of your quote |
customer_id | ID of the customer who is assigned to the quote |
customer_name | Your customer’s name |
currency_id | Currency ID |
currency_code | Currency code |
currency_symbol | Currency symbol |
exchange_rate | Exchange rate involved in the quote |
expiry_date | Expiry date of the quote |
discount_amount | Discount amount |
discount | Discount |
shipping_charge | Shipping charge entered in the quote |
adjustment | Adjustments |
sub_total | Sub total of the quote |
total | Quote total |
tax_total | Total tax amount in the quote |
billing_address | Billing address of the customer |
shipping_address | Shipping address of the customer |
notes | Notes |
terms | Terms and conditions |
custom_fields | Quote custom fields |
salesperson_id | ID of the salesperson |
salesperson_name | Name of the salesperson |
Sample map:
{
"total": "12000.0",
"terms": “checking",
"quote_id": "7605000000320001",
"date": "2016-06-03",
"quote_number": "EST-000026",
"shipping_address": {
"zip": "94588",
"country": "USA",
"address": "4910 Hopyard Rd",
"city": "Pleasanton",
"state": "CA",
"fax": “Fax Number”
},
"salesperson_name": “Salesperson”,
"adjustment": "0.0",
"currency_symbol": "Rs.",
"salesperson_id": "7605000000336089",
"currency_code": "INR",
"shipping_charge": "0.0",
"custom_fields": [
{
"customfield_id": "7605000000190011",
"is_active": true,
"show_in_all_pdf": false,
"value_formatted": "Check-6",
"data_type": "autonumber",
"index": 1,
"label": "auto number",
"show_on_pdf": false,
"value": "Check-6"
}
],
"currency_id": "7605000000000099",
"exchange_rate": "1.0",
"status": "invoiced",
"sub_total": "12000.0",
"customer_name": “Customer”,
"discount_amount": "0.0",
"discount": "0.0",
"tax_total": "0.0",
"reference_number": “Ref number”,
"notes": "Looking forward for your business.",
"expiry_date": "2016-06-03",
"customer_id": "7605000000258011",
"billing_address": {
"zip": "94588",
"country": "USA",
"address": "4910 Hopyard Rd",
"city": "Pleasanton",
"state": "CA",
"fax": "Fax Number"
}
}
invoice
The invoice map supports the following fields:
Key Fields | Description |
---|---|
due_date | Invoice due date |
payment_expected_date | Expected payment date for the invoice |
reference_number | Reference number of the invoice |
customer_id | Customer ID |
customer_name | Name of the customer who is assigned to the invoice |
currency_id | Currency ID |
currency_code | Currency code |
currency_symbol | Currency symbol |
exchange_rate | Exchange rate involved in the invoice |
discount_amount | Discount amount involved in the invoice |
discount | Discount involved in the invoice |
shipping_charge | Shipping charge entered in the invoice |
adjustment | Adjustments |
sub_total | Sub total of the invoice |
tax_total | Total tax amount in the invoice |
total | Total amount |
balance | Balance |
price_precision | Number of Decimal places |
billing_address | Billing address of the customer |
shipping_address | Shipping address of the customer |
notes | Notes |
terms | Terms and conditions |
custom_fields | Invoice custom fields |
salesperson_id | ID of the salesperson |
Sample map:
{
"total": "0.0",
"payment_terms": "0",
"terms": “Checking”,
"price_precision": "2",
"payment_expected_date": "2016-06-31”,
"date": "2016-06-30",
"shipping_address": {
"zip": "94588",
"country": "USA",
"address": "4910 Hopyard Rd",
"city": "Pleasanton",
"state": "CA",
"fax": "Fax Number"
},
"balance": "0.0",
"adjustment": "0.0",
"currency_symbol": "Rs.",
"salesperson_id": “7605000000336089”,
"currency_code": "INR",
"shipping_charge": "0.0",
"custom_fields": [
{
"customfield_id": "7605000000336081",
"is_active": true,
"show_in_all_pdf": false,
"value_formatted": "INV-8",
"data_type": "autonumber",
"index": 1,
"label": "AutoNumber",
"show_on_pdf": false,
"value": "INV-8"
},
{
"customfield_id": "7605000000351027",
"is_active": true,
"show_in_all_pdf": true,
"value_formatted": "01 Aug 2016",
"data_type": "date",
"index": 2,
"label": "Date",
"show_on_pdf": true,
"value": "2016-08-01"
}
],
"currency_id": "7605000000000099",
"exchange_rate": "1.0",
"status": "draft",
"sub_total": "12000.0",
"customer_name": “Customer”,
"invoice_number": "INV-000087",
"discount_amount": "12000.0",
"discount": "100.00%",
"tax_total": "0.0",
"reference_number": “checking”,
"due_date": "2016-06-30",
"invoice_id": "7605000000369043",
"notes": "Thanks for your business.",
"customer_id": "7605000000258011",
"billing_address": {
"zip": "94588",
"country": "USA",
"address": "4910 Hopyard Rd",
"city": "Pleasanton",
"state": "CA",
"fax": "Fax Number"
}
}
sales order
Key Fields | Description |
---|---|
date | Sales Order date |
tax_total | Total tax amount in the sales order |
zcrm_potential_id | ID of the potential in Zoho CRM |
discount_amount | Discount amount involved in the sales order |
salesorder_id | Sales order ID |
discount | Discount |
shipment_date | Date on which shipment is made |
billing_address | Billing address of the customer |
line_items | Line items |
currency_code | Currency code |
total | Total amount |
delivery_method_id | Delivery method ID |
terms | Terms and conditions |
delivery_method | Method of delivery |
shipping_address | Shipping address of the customer |
exchange_rate | Exchange rate involved in the sales order |
currency_symbol | Currency symbol |
custom_fields | Sales order custom fields |
quote_id | Quote ID |
reference_number | Reference number of the sales order |
salesperson_name | Name of the salesperson involved |
salesperson_id | ID of the salesperson involved |
shipping_charge | Shipping charge entered in the sales order |
salesorder_number | Your sales order number |
sub_total | Sub total of the sales order |
zcrm_potential_name | Name of the potential in Zoho CRM |
adjustment | Adjustments made |
customer_name | Name of the customer who is assigned to the sales order |
customer_id | ID of the customer who is assigned to the sales order |
currency_id | Currency ID |
status | Status of your sales order |
Sample map:
{
"date": "2016-05-23",
"tax_total": "0.0",
"zcrm_potential_id": "",
"discount_amount": "1200.0",
"salesorder_id": "7605000000295003",
"discount": "10.00%",
"shipment_date": "2016-05-23",
"billing_address": {
"zip": "94588",
"country": "USA",
"address": "4910 Hopyard Rd",
"city": "Pleasanton",
"state": "CA",
"fax": "Fax Number"
},
"line_items": [
{
"bcy_rate": 12000,
"line_item_id": "7605000000295011",
"quantity": 1,
"item_id": "7605000000259147",
"tax_name": "",
"description": "",
"discount": 0,
"item_total": 12000,
"item_custom_fields": [
],
"tax_id": "",
"is_invoiced": true,
"item_order": 0,
"tags": [
],
"stock_on_hand": "",
"unit": "",
"rate": 12000,
"tax_type": "tax",
"name": "Moto",
"tax_percentage": 0
}
],
"currency_code": "INR",
"total": "10820.0",
"delivery_method_id": "7605000000461053",
"terms": "Terms & Conditions",
"delivery_method": "Door Delivery",
"shipping_address": {
"zip": "",
"country": "",
"address": "",
"city": "",
"state": "",
"fax": ""
},
"exchange_rate": "1.0",
"currency_symbol": "Rs.",
"custom_fields": [
{
"customfield_id": "7605000000321009",
"is_active": true,
"show_in_all_pdf": true,
"value_formatted": "Text",
"data_type": "string",
"index": 1,
"label": "Text",
"show_on_pdf": true,
"value": "Text"
}
],
"quote_id": "7605000000405047",
"reference_number": "Reference",
"salesperson_name": "Arun",
"salesperson_id": "7605000000135003",
"shipping_charge": "10.0",
"salesorder_number": "SO-00002",
"sub_total": "12000.0",
"zcrm_potential_name": "",
"adjustment": "10.0",
"customer_name": "Arun",
"customer_id": "7605000000101007",
"currency_id": "7605000000000099",
"status": "invoiced"
}
purchase order
The purchase order map supports the following fields:
Key Fields | Description |
---|---|
date | Date of the purchase order |
delivery_address | Delivery address |
tax_total | Total tax amount in the purchase order |
delivery_org_address_id | ID of delivery org address |
purchaseorder_id | Purchase order ID |
expected_delivery_date | Expected delivery date |
billing_address | Billing address of purchase order |
line_items | Line items in the purchase order |
currency_code | Currency code |
total | Total of the purchase order |
delivery_customer_id | Delivery customer ID |
exchange_rate | Exchange rate involved in the purchase order |
currency_symbol | Currency symbol |
custom_fields | Purchase order custom fields |
ship_via_id | ID of mode of shipping |
vendor_name | Name of the vendor |
reference_number | Reference number of your purchase order |
purchaseorder_number | Purchase order number |
delivery_date | Delivery date |
vendor_id | Vendor ID |
sub_total | Sub-total of the purchase order |
ship_via | Means of shipping |
attention | Attention |
crm_owner_id | ID of Zoho CRM owner |
currency_id | Currency ID |
status | Status |
Sample map:
{
"date": "2016-07-11",
"delivery_address": {
"zip": "94588",
"country": "USA",
"address": "4910 Hopyard Rd",
"city": "Pleasanton",
"state": "CA",
"fax": "Fax Number"
},
"tax_total": "0.0",
"delivery_org_address_id": "7605000000054013",
"purchaseorder_id": "7605000000378500",
"expected_delivery_date": "",
"billing_address": {
"zip": "94588",
"country": "USA",
"address": "4910 Hopyard Rd",
"city": "Pleasanton",
"state": "CA",
"fax": "Fax Number"
},
"line_items": [
{
"bcy_rate": 1000,
"line_item_id": "7605000000378504",
"quantity": 1,
"item_id": "7605000000298021",
"tax_name": "",
"description": "",
"item_total": 1000,
"tax_id": "",
"item_order": 0,
"tags": [
],
"unit": "No",
"account_id": "7605000000000403",
"rate": 1000,
"tax_type": "tax",
"account_name": "Advertising And Marketing",
"name": "Moto G Turbo Edition",
"tax_percentage": 0
}
],
"currency_code": "INR",
"total": "1000.0",
"delivery_customer_id": "",
"exchange_rate": "1.0",
"currency_symbol": "Rs.",
"custom_fields": "[]",
"ship_via_id": "7605000000461053",
"vendor_name": "Mr. Vendor",
"reference_number": "Reference",
"purchaseorder_number": "PO-00006",
"delivery_date": "2016-07-11",
"vendor_id": "7605000000112009",
"sub_total": "1000.0",
"ship_via": "Door Delivery",
"attention": "Arun",
"crm_owner_id": "",
"currency_id": "7605000000000099",
"status": "billed"
}
customer
The customer map supports the following fields:
Key Fields | Description |
---|---|
owner_id | ID of associated owner |
billing_address | Billing address associated to customer |
source | Source of the customer |
contact_id | Contact ID |
payment_terms | Payments terms associated to customer |
currency_code | Currency code |
language_code | Language code |
contact_type | Type of the contact |
Twitter info | |
zcrm_contact_id | ID of the contact in Zoho CRM |
shipping_address | Shipping address associated to customer |
pricebook_id | ID of pricebook associated |
contact_name | Name of contact |
website | Website of contact |
owner_name | Name of contact owner |
currency_symbol | Currency symbol |
zcrm_account_id | ID of Zoho CRM account |
custom_fields | Custom fields associated with customer |
Facebook info | |
pricebook_name | Name of pricebook associated |
primary_contact_id | ID of primary contact |
company_name | Name of the company |
contact_salutation | Contact salutation |
crm_owner_id | ID of CRM owner |
currency_id | Currency ID |
payment_terms_label | Payment terms label |
status | Status |
Sample map:
{
"owner_id": "",
"shipping_address": {
"zip": "94588",
"country": "USA",
"address": "4910 Hopyard Rd",
"city": "Pleasanton",
"state": "CA",
"fax": "Fax Number"
},
"source": "user",
"contact_id": "7605000000197147",
"payment_terms": "0",
"currency_code": "INR",
"language_code": "en",
"contact_type": "customer",
"twitter": "",
"zcrm_contact_id": "",
"billing_address": {
"zip": "94588",
"country": "USA",
"address": "4910 Hopyard Rd",
"city": "Pleasanton",
"state": "CA",
"fax": "Fax Number"
},
"pricebook_id": "",
"contact_name": "Arun",
"website": "www.zoho.com",
"owner_name": "",
"currency_symbol": "Rs.",
"zcrm_account_id": "418070000000135001",
"custom_fields": [
{
"customfield_id": "7605000000063049",
"is_active": true,
"show_in_all_pdf": false,
"value_formatted": "1234",
"data_type": "number",
"index": 1,
"label": "Unpaid Invoices",
"show_on_pdf": false,
"value": "1234"
}
],
"facebook": "",
"pricebook_name": "",
"primary_contact_id": "7605000000197149",
"company_name": "Zoho",
"contact_salutation": "",
"crm_owner_id": "",
"currency_id": "7605000000000099",
"payment_terms_label": "Due on Receipt",
"status": "active"
}
recurring invoice
The recurring invoice map supports the following fields:
Key Fields | Description |
---|---|
end_date | End date of the recurring invoice profile |
tax_total | Total tax amount in the recurring invoice |
discount_amount | Discount amount involved in the recurring invoice |
repeat_every | Repetition period of recurring invoice profile |
discount | Discount involved in the recurring invoice |
taxes | Taxes associated with the recurring invoice |
billing_address | Billing address of the customer |
line_items | Line items in the recurring invoice |
payment_terms | Payments terms associated to customer |
currency_code | Currency code |
last_sent_date | Date of the last sent invoice |
total | Total amount |
recurrence_name | Name of the recurring invoice profile |
shipping_address | Shipping address of the customer |
next_invoice_date | Date of the next invoice to be sent |
recurrence_frequency | Frequency of the recurring invoice profile |
recurring_invoice_id | ID of the recurring invoice profile |
contact_persons | Contact persons involved in recurring invoice |
start_date | Starting date of the recurring invoice profile |
exchange_rate | Exchange rate involved in the recurring invoice |
currency_symbol | Currency symbol |
custom_fields | Recurring invoice custom fields |
salesperson_name | Name of the sales person involved |
salesperson_id | ID of the sales person involved |
shipping_charge | Shipping charge entered in the recurring invoice |
sub_total | Sub-total of the recurring invoice |
adjustment | Adjustments made |
customer_name | Name of the customer involved |
customer_id | ID of the customer involved |
status | Status of the recurring invoice profile |
Sample map:
{
"end_date": "2016-10-15",
"tax_total": "0.0",
"discount_amount": "1.0",
"repeat_every": "2",
"discount": "1.00%",
"taxes": "[]",
"billing_address": {"zip":"","fax":"","address":"","state":"","country":"","city":""},
"line_items": [{"tags":[],"tax_name":"","tax_type":"tax","item_custom_fields":[],"product_type":"service","line_item_id":"348960000000103013","discount":0,"unit":"","item_order":0,"rate":100,"item_id":"","description":"%(d)%-%(m-2)%-%(y)%","name":"","quantity":1,"tax_id":"","tax_percentage":0,"item_total":100}],
"payment_terms": "0",
"currency_code": "GBP",
"last_sent_date": "",
"total": "200.0",
"recurrence_name": "1",
"shipping_address": {"zip":"","fax":"","address":"","state":"","country":"","city":""},
"next_invoice_date": "",
"recurrence_frequency": "months",
"recurring_invoice_id": "348960000000103005",
"contact_persons": "[]",
"start_date": "2016-01-07",
"exchange_rate": "1.0",
"currency_symbol": "£",
"custom_fields": [{"value_formatted":"EST-001","index":1,"is_active":true,"data_type":"string","show_on_pdf":false,"value":"EST-001","show_in_all_pdf":false,"label":"Quote Number","customfield_id":"348960000000056001"},{"value_formatted":"15 Oct 2016","index":2,"is_active":true,"data_type":"date","show_on_pdf":false,"value":"2016-10-15","show_in_all_pdf":false,"label":"Date","customfield_id":"348960000000056003"},{"value_formatted":"true","index":3,"is_active":true,"data_type":"check_box","show_on_pdf":false,"value":true,"show_in_all_pdf":false,"label":"Invoice Factoring","customfield_id":"348960000000056079"},{"value_formatted":"£100.00","index":4,"is_active":true,"data_type":"amount","show_on_pdf":true,"value":100,"show_in_all_pdf":true,"label":"Amount","customfield_id":"348960000000060003"},{"value_formatted":"10%","index":5,"is_active":true,"data_type":"percent","show_on_pdf":true,"value":10,"show_in_all_pdf":true,"label":"Percentage","customfield_id":"348960000000060005"}],
"salesperson_name": "Arun N",
"salesperson_id": "348960000000111001",
"shipping_charge": "100.0",
"sub_total": "100.0",
"adjustment": "1.0",
"customer_name": "iArun",
"customer_id": "348960000000051041",
"status": "expired"
}
expense
The expense map supports the following fields:
Key Fields | Description |
---|---|
date | Date |
payment_mode | Mode of payment |
custom_fields | Expense custom fields |
vendor_name | Name of the vendor involved |
is_billable | Billability of the expense |
line_items | Line items in the expense |
project_name | Name of the project involved |
reference_number | Reference number of the expense |
currency_code | Currency code |
total | Total |
project_id | ID of the project involved |
vendor_id | ID of the vendor involved |
sub_total | Sub-total on the expense |
customer_name | Name if the customer involved |
customer_id | ID of the customer involved |
expense_id | Expense ID |
currency_id | Currency ID |
Sample map:
{
"date": "2016-10-08",
"payment_mode": "Cash",
"custom_fields": "[]",
"vendor_name": "Vendor",
"is_billable": "true",
"line_items": [{"tags":[],"tax_name":"Standard Rate","item_order":1,"tax_type":"tax","account_id":"348960000000000400","description":"Notes","tax_amount":16.67,"product_type":"goods","tax_id":"348960000000044037","line_item_id":"348960000000184015","tax_percentage":20,"item_total":83.33,"account_name":"Office Supplies"}],
"project_name": "",
"reference_number": "12345",
"currency_code": "GBP",
"total": "100.0",
"project_id": "",
"vendor_id": "348960000000051033",
"sub_total": "83.33",
"customer_name": "Accounts",
"customer_id": "348960000000111017",
"expense_id": "348960000000184003",
"currency_id": "348960000000000103"
}
bill
The bill map supports the following fields:
Key Fields | Description |
---|---|
date | Date on the bill |
bill_id | ID of the bill |
purchaseorder_ids | ID of the purchase order involved |
tax_total | Total tax amount in the bill |
exchange_rate | Exchange rate involved in the bill |
currency_symbol | Currency symbol |
custom_fields | Bill custom fields |
due_date | Due date of the bill |
vendor_name | Name of the vendor involved |
billing_address | Billing address |
line_items | Line items in the bill |
payment_terms | Payments terms associated to vendor |
payment_expected_date | Expected payment date |
reference_number | Reference number of the bill |
currency_code | Currency code |
total | Total on the bill |
bill_number | Bill number |
payment_made | Payment made for the bill |
balance | Balance amount |
recurring_bill_id | ID of the recurring bill profile |
vendor_id | ID of the vendor involved |
sub_total | Sub-total on the bill |
status | Bill status |
Sample map:
{
"date": "2016-10-12",
"bill_id": "348960000000193039",
"purchaseorder_ids": "[]",
"tax_total": "0.0",
"exchange_rate": "1.0",
"currency_symbol": "£",
"custom_fields": "[]",
"due_date": "2016-10-15",
"vendor_name": "Vendor",
"billing_address": {"zip":"","fax":"","address":"","state":"","country":"","city":""},
"line_items": [{"tags":[],"tax_name":"","project_name":"","tax_type":"tax","account_id":"348960000000000412","customer_name":"","is_billable":false,"product_type":"goods","line_item_id":"348960000000193047","invoice_number":"","sku":"","purchaseorder_item_id":"","account_name":"Credit Card Charges","unit":"1","item_order":0,"rate":33000,"bcy_rate":33000,"item_id":"348960000000087031","description":"","project_id":"","name":"refrigerator","tax_id":"","quantity":1,"invoice_id":"","tax_percentage":0,"customer_id":"","item_total":33000}],
"payment_terms": "3",
"payment_expected_date": "",
"reference_number": "1",
"currency_code": "GBP",
"total": "33000.0",
"bill_number": "Bill-001",
"payment_made": "0.0",
"balance": "33000.0",
"recurring_bill_id": "",
"vendor_id": "348960000000051033",
"sub_total": "33000.0",
"status": "open"
}
recurring bill
The recurring bill map supports the following fields:
Key Fields | Description |
---|---|
end_date | End date of the recurring bill profile |
tax_total | Total tax amount in the recurring bill |
exchange_rate | Exchange rate involved in the recurring bill |
custom_fields | Recurring bill custom fields |
repeat_every | Repetition period of recurring bill profile |
taxes | Taxes involved in the recurring bill |
vendor_name | Name of the vendor involved |
line_items | Line items in the recurring bill |
payment_terms | Payments terms associated to vendor |
currency_code | Currency code |
last_sent_date | Date of the last sent bill |
total | Recurring bill total |
next_bill_date | Date of the next bill |
recurring_bill_id | ID of the recurring bill |
recurrence_name | Name of the recurring bill profile |
vendor_id | ID of the vendor involved |
sub_total | Sub-total on the recurring bill |
recurrence_frequency | Frequency of the recurring invoice profile |
payment_terms_label | Payment terms label |
status | Status of the recurring bill profile |
start_date | Starting date of the recurring bill profile |
Sample map:
{
"end_date": "2016-10-15",
"tax_total": "0.0",
"exchange_rate": "1.0",
"custom_fields": "[]",
"repeat_every": "1",
"taxes": "[]",
"vendor_name": "Vendor",
"line_items": [{"tags":[],"tax_name":"","account_id":"348960000000000403","tax_type":"tax","product_type":"goods","line_item_id":"348960000000193067","account_name":"Advertising And Marketing","unit":"","item_order":0,"rate":900,"bcy_rate":900,"item_id":"348960000000051011","description":"","name":"Item","quantity":1,"tax_id":"","tax_percentage":0,"item_total":900}],
"payment_terms": "0",
"currency_code": "GBP",
"last_sent_date": "2016-10-12",
"total": "900.0",
"next_bill_date": "",
"recurring_bill_id": "348960000000193061",
"recurrence_name": "RB-001",
"vendor_id": "348960000000051033",
"sub_total": "900.0",
"recurrence_frequency": "weeks",
"payment_terms_label": "Due on Receipt",
"status": "expired",
"start_date": "2016-10-12"
}
item
The item map supports the following fields:
Key Fields | Description |
---|---|
item_id | Item ID |
custom_fields | Item custom fields |
item_type | Type of the item |
tax_name | Name of the tax involved |
purchase_rate | Purchase rate of the item |
zcrm_product_id | ID of the product in Zoho CRM |
tax_id | ID of the tax involved |
unit | Unit of the item |
account_id | Sales account ID |
purchase_account_name | Name of the purchase account |
purchase_account_id | Purchase account ID |
tax_type | Type of the tax involved |
rate | Sales rate of the item |
account_name | Name of the sales account involved |
name | Name of the item |
tax_percentage | Percentage of tax involved |
pricebook_rate | Pricebook rate |
sku | SKU of the item |
status | Status of the item |
Sample map:
{
"item_id": "348960000000051011",
"custom_fields": [{"value_formatted":"100","index":1,"is_active":true,"data_type":"decimal","show_on_pdf":true,"value":100,"show_in_all_pdf":true,"label":"Profit","customfield_id":"348960000000134003"}],
"item_type": "sales_and_purchases",
"tax_name": "",
"purchase_rate": "900.0",
"zcrm_product_id": "1665395000000205001",
"tax_id": "",
"unit": "1",
"account_id": "348960000000000388",
"purchase_account_name": "Advertising And Marketing",
"purchase_account_id": "348960000000000403",
"tax_type": "",
"rate": "1000.0",
"account_name": "Sales",
"name": "Item",
"tax_percentage": "0",
"pricebook_rate": "1000.0",
"sku": "SKU",
"status": "active"
}
A few example explaining how these fields would help in fetching the necessary parameters:
Example 1:
To fetch quote id, use:
quoteid = quote.get("quote_id");
Example 2:
To fetch your organization name, use:
orgid = organization.get("name");
Example 3:
To fetch a user’s name and ZUID, use:
username = user.get("name");
zuid = user.get("zuid");
To know more about how to use Deluge scripts for writing custom functions, refer the Deluge Reference Guide.
To know more about different scenarios where custom functions could be useful, refer our Custom Function Scenarios page.
Schedules
Zoho Books lets you create and run predefined tasks at the specified time intervals using schedules. You can create your tasks using a deluge script and schedule this task to be executed at a particular time or on a recurring basis.
Note: This feature is available only for certain plans of Zoho Books. Visit the pricing page to check if it’s available in your current plan.
Scenarios
Here are a few scenarios where schedules can be created to execute custom actions. However, you can create custom schedules based on your firm’s requirements.
Scenario 1: Peter runs a supermarket. At the end of every month, he wants to give a 10% off on the Next Purchase to customers whose total purchase for the month exceeds a certain amount, let’s say 1000. Peter creates a schedule to email this to selective customers on the last day of the month.
Scenario 2: Peter uses a third party application for maintaining customer and employee database internally. He would like to sync all data from Zoho Books to the other application periodically. To do so, he creates a custom schedule to sync the data at 6 pm every day.
Scenario 3: Peter sets a quarterly sales target for his territorial managers. Every four months, he has to send them their Profit and Loss reports and a congratulatory email when they have achieved their target or a motivating email for them to perform better. He writes a function and schedules it to be sent to his staff once every 4 months.
Creating New Schedules
To create a custom schedule:
- Go to Settings > Automation > Schedules > + New Schedule.
- Enter a Name for your schedule.
- Set the Frequency and recurrence pattern for the schedule to be executed. This can be daily, weekly, monthly or yearly.
Insight: The recurrence pattern lets you decide when the custom schedule should be executed. You can choose to execute it on the set frequency.
Select how frequently the task should be executed.
Daily: The task will be executed every day (or based on your recurrence pattern). You can choose to exclude the weekends.
Weekly: The task will be executed once a week. Select the day of the week on which the task should be executed.
Monthly: Task will be executed once a month. This can be a specific date or a day in a month. For example, you can choose to execute it on the 5th of every month or the Second Saturday of every month.
Yearly: Task will be executed once a year. You can select the month and specify the date of execution or specify the day. For example, the task can be executed on the first Sunday in January or just January 5.
Set the Start Date and Time.
Warning: The start date of a schedule cannot be more than one year from the creation date.
- Select when the schedule should expire. It can expire after a number of executions or on a set date or not expire at all.
- Drag and drop options to create a Deluge function that will help to create your function.
Insight: Deluge (Data Enriched Language for the Universal Grid Environment) is an online scripting language integrated with Zoho Services. It enables you to write your own functions that lets you modify the application to suit your needs, incrementally, making it more powerful and robust.
- Click Save or Save and Execute to run it.
Insight: You can create a maximum of 10 custom schedules.
Sample Function:
Here’s a sample function for Scenario 1:
organizationID = organization.get("organization_id");
name = organization.get("name");
orgEmail = organization.get("email");
salesResponse = invokeUrl
[
url: "https://books.zoho.com/api/v3/reports/salesbycustomer?organization_id=" + organizationID + "&from_date=" + toStartOfMonth(today).toString("YYYY-MM-dd") + "&to_date=" + eomonth(today,0).toString("YYYY-MM-dd")
type: GET
connection: "books_api_connection"
];
salesDetails = salesResponse.get("sales").toList();
for each sales in salesDetails
{
amount = sales.get("sales_with_tax");
if(amount > "<ENTER AMOUNT>")
{
customerName = sales.get("customer_name");
customerResponse = invokeUrl
[
url: "https://books.zoho.com/api/v3/contacts/" + sales.get("customer_id") + "?organization_id=" + organizationID
type: GET
connection: "books_api_connection"
];
customerDetails = customerResponse.get("contact");
customerEmail = customerDetails.get("email");
sendmail
[
from :zoho.adminuserid
to :customerEmail
subject :"Thank you for shopping! Here's a 10% discount!"
message :"<div>Dear " + customerName + ",<br></div><div><br></div><div>We just wanted to take a moment of our time to thank you for your continuous support.<br></div><div><br></div><div> Based on your recent purchases, we'd like to offer you a 10% off on your next purchase with us. <br></div><div><br></div><div>Please show this email during billing to avail this discount!<br></div><div><br></div><div>Regards,<br></div><div>" + name + "<br></div><div><br></div><div><br></div><div><br></div><div><br></div>"
]
}
}
Learn more from the Connections help document.
Automate your business workflow with Zoho Books’ accounting automation.