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.
  

Workflow Scenarios

Setting up a new workflow rule

• Name your workflow
• Choose when to trigger the workflow
• Workflow types
• Filter the triggers
• Actions
• Other Actions

Email Alerts

In-app Notifications

Field Updates

Webhooks

• Create a Webhook
• Webhook Examples
• Secure Your Webhooks
  
• Validate Webhooks
• Other Actions
  • Delete Webhooks
  • Filter Webhooks

Custom Functions

Schedules

---

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:

• Click Settings on the top right corner of the page.
• Click Workflow Rules under Automation.
• Click + New Workflow Rule.

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.

Delete a workflow rule: To delete the workflow rule:

• Click Settings on the top right corner of the page.
• Click Workflow Rules under Automation.
• Hover the cursor over the workflow rule that you want to delete and click the Trash button.

Edit a workflow rule: To edit a workflow rule:

• Click Settings on the top right corner of the page.
• Click Workflow Rules under Automation.
• Hover the cursor over the workflow rule that you want to edit and click Edit.

Or, you can edit a workflow rule by simply clicking the required workflow rule.

Filter workflow rules:
To filter the workflow rules:

• Click Settings on the top right corner of the page.
• Click Workflow Rules under Automation.
• 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:

• Click Settings on the top right corner of the page.
• Click Workflow Actions under Automation.
• In the Workflow Actions pane, click Email Alerts.
• Click + 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:

• Click Settings on the top right corner of the page.
• Click Workflow Actions under Automation.
• In the Workflow Actions pane, click Email Alerts.
• Hover the cursor over the email alert that you want to delete and click the Trash button.

Filter email alerts:
To filter the email alerts:

• Click Settings on the top right corner of the page.
• Click Workflow Actions under Automation.
• In the Workflow Actions pane, click 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:

• Click Settings on the top right corner of the page.
• Click Workflow Rules under Automation.
• Click + 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:

• Click Settings on the top right corner of the page.
• Click Workflow Actions under Automation.
• In the Workflow Actions pane, click Field Updates.
• Click + 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:

• Click Settings on the top right corner of the page.
• Click Workflow Actions under Automation.
• In the Workflow Actions pane, click Field Updates.
• Hover the cursor over the field update that you want to delete and click the Trash button.

Filter field updates:
To filter the field updates:

• Click Settings on the top right corner of the page.
• Click Workflow Actions under Automation.
• In the Workflow Actions pane, click 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 facilitate communication with third-party applications by sending instant web notifications every time an event occurs in Zoho Books. With Webhooks, you can configure HTTP & HTTPS URLs and associate them with workflow rules to automate the notification process. Read our help document on webhook examples to know more about when and how you can use webhooks.

For general information about webhooks, visit webhooks.org.

Create a Webhook

To set up a webhook:

• Click Settings on the top right corner of the page.
• Click Workflow Actions under Automation.
• In the Workflow Actions pane, click Webhooks.
• Click + New Webhook in the top right corner.

• On the New Webhook page, enter the following details:
  • Enter a name for the webhook in the Name field.
  • Select the module for which you want to create the webhook from the dropdown next to the Module field.
  • Add a description about the webhook in the Description field, if required.

• In the URL & Parameters field, select the HTTP method and enter the URL of the third-party application. The HTTP methods available in Zoho Books are listed below:

  • Post: Requests that the data sent must be considered as new
  • Put: Requests that the data sent should be considered as a modified version of the one already present
  • Delete: Requests that the data must be deleted.

You can also add additional query parameters by clicking Add Parameters and entering the required values in the Key and Value fields. You can add custom parameters like Auth Token, Security Token, API Key, etc.

• Check the I want to secure this webhook option if you want to secure your webhook. Enter the secret key in the Secret Token field. This will help to verify whether the webhook was sent from Zoho Books. It should be alphanumeric and range between 12-50 characters.

• In the Headers section, you can include any additional information that you want to be included in the HTTP request. Click + Add New Headers if you want to add additional headers.

• In the Authorization Type section, choose how you want to authorize the webhook.

  • Self-Authorization: Select this option to set up your webhook by providing the authorization details manually.
  • Connections: Select this option to set up your webhook using a connection. Read our help document on Connections to learn how to create connections.

• In the Body section, choose how you want to send the data. You can choose between Default Payload, x-www-form-urlencloded, and Raw body parameters.

  • Default Payload: In the default payload format, all the parameters associated with the module will be sent to the request body in the application/json format content type.
  • x-www-form-urlencoded: In the x-www-urlencoded format, the data will be encoded and sent to the server.
  • Raw: In the raw format, you can choose the parameters sent to the request body. The content type will be application/json.

• Click Save and Execute to check if the webhook works properly, or click Save if you want to execute it later.

Secure Your Webhooks

Securing your webhooks can help verify that the webhooks were sent from Zoho Books. To do this, you have to set up your server so that it listens for webhooks from Zoho Books. When your server receives a webhook from Zoho Books, a hash value must be generated based on the payload and your secret token. Once done, check if it matches the hash value from Zoho Books and thereby validate the source of the webhook. This can add a layer of security by enabling your server to disregard third-party webhooks pretending to originate from Zoho Books.

Validate Webhooks

When your server receives the webhook, a hash value will have to be generated for the payload in the same way that Zoho Books generated it. This is necessary to produce the same hash value to validate the webhook.

The following parameters (if available) are used to generate the hash value:

• Query string parameters.
• Default payload or customized raw JSON payload.
• x-www-form-urlencoded payload (key-value pairs).

Construct a string by sorting the payload’s key-value pairs in alphabetical order. The pairs must be sorted in alphabetical order with respect to their keys.

Once you’ve sorted the key-value pairs and constructed the string, append the raw JSON to the end of the string.

Examples

1. Default Payload

Query string parameters’ key-value pairs:

subscription\_id=90343, name=basic

Default payload/raw JSON:

{"created\_date":"2019-03-06","event\_id":"5675"}

The constructed string would be:

namebasicsubscription\_id90343{"created\_date":"2019-03-06","event\_id":"5675"}

2. x-www-form-urlencoded

Query string parameters’ key-value pairs:

customer\_name=Brandon, status=active

x-www-form-urlencoded payload’s key-value pairs:

addon\_description=Monthly addon, quantity=1

The constructed string would be:

addon\_descriptionMonthly addoncustomer\_nameBrandonquantity1statusactive

The hash value can be computed by applying the HMAC-SHA256 algorithm on this string, along with the secret token that was used in Zoho Books.

You can then validate the webhook by checking if the hash value computed from your side matches the one in the header (X-Zoho-Webhook-Signature) of the webhook from Zoho Books.

Other Actions

Delete Webhooks

To delete a webhook:

• Click Settings on the top right corner of the page.
• Click Workflow Actions under Automation.
• In the Workflow Actions pane, click Webhooks.
• Hover the cursor over the webhook that you want to delete and click the Delete button.

• In the pop up that appears, click Yes.

The webhook will be deleted. If you’ve used in the webhook in a workflow rule, ensure that you update the workflow rule as the workflow rule might not get triggered.

Filter Webhooks

To filer the webhooks:

• Click Settings on the top right corner of the page.
• Click Workflow Actions under Automation.
• In the Workflow Actions pane, click 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.

---

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:

• Click Settings on the top right corner of the page.
• Click Workflow Actions under Automation.
• In the Workflow Actions pane, click Custom Functions.
• Click + 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	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	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	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.

• Scenarios
• Creating New Schedules
• Sample Function

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.

Creating New Schedules

To create a custom schedule:

• Click Settings on the top right corner of the page.
• Click Workflow Actions under Automation.
• In the Workflow Actions pane, click Custom Functions.
• Click + 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.

• 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.

• 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.

• Click Save or Save and Execute to run it.

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&nbsp;" + 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.&nbsp;<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.