Automation

Automation allows you to create rules that trigger actions automatically. You can set up workflow rules, define conditions for execution, and associate actions such as email alerts, in-app notifications, field updates, webhooks and custom functions. Additionally, you can create schedules for workflow rules and view logs of executed workflows.

Workflow Rules

You can automate tasks such as sending emails, updating fields, and triggering webhooks or custom functions by creating workflow rules in Zoho Books. The workflow rule executes automatically once the conditions are met.

Create a New Workflow Rule

To create a new workflow rule:

• Go to Settings.
• Select Workflow Rules under Automation.
• Click + New Workflow Rule in the top right corner.
• In the New Workflow Rule pop-up, fill in the following fields:
  • Workflow Rule Name: Enter a name for the workflow rule.
  • Description: Add a description if necessary.
  • Module: Select the module for the workflow rule from the drop-down menu.
• Click Next.
• Under WORKFLOW RULE EXECUTION CONDITION, fill in the following fields:
  • Workflow Type: Choose either Event Based or Date Based.
  • Action Type: Select the action type that triggers the workflow.
  • Execute the workflow when: Choose the actions that trigger the workflow (Edit, Edited or Created).
  • Execute when the record is: Select either Edited for the first time or Edited each time.

• Click Next.
• Click + New Criteria to create a new criteria for the workflow rule:
• In the right sidebar, click Yes to add criteria or No to skip.
• Select a field, the comparator, and enter the necessary value.
• Click + Add Criterion or + to create additional criteria if necessary.
• If you add multiple criteria, select either AND or OR from the dropdown based on how you want the criteria to work. You can also edit the criteria pattern by manually entering the criteria in the CRITERIA PATTERN field.
• Once you’ve added the necessary criteria, click Done.
• Add actions by selecting from the options below:
  • + Immediate Actions: Triggers actions immediately when the criteria are met.
    • In the right sidebar, select the type of workflow action you want to associate with the workflow rule from the Type dropdown. Next, from the Name dropdown, choose the workflow action you created and configured, or click + New %Workflow Action% from the dropdown to add a new workflow action.
    • Click + Add New Action to add more actions if necessary.
    • Click Associate to finish associating actions with the criteria.
  • + Time Based Actions: Triggers actions based on the scheduled time.
    • In the right sidebar, In the EXECUTION TIME field, set the time for when the action will be executed.
    • Select the type of workflow action you want to associate with the workflow rule from the Type dropdown. Then, from the Name dropdown, choose the workflow action you created and configured, or click + New %Workflow Action% from the dropdown to add a new workflow action.
    • Click + Add New Action to add more actions if necessary.
    • Click Associate to finish associating actions with the criteria.
• Click Save to finalize and save the workflow rule.

Now, once you’ve created the workflow rule, whenever an action occurs that matches the trigger you set in the workflow rule, the rule will execute, and the specified action will take place.

Other Actions in Workflow Rules

Change the Order of Workflow Rules

If you want to view specific workflow rules at the top of the List View page or in a specific order, you can reorder them. Here’s how:

• Go to Settings.
• Select Workflow Rules under Automation.
• Select the module where you want to change the order of workflow rules by clicking the Module dropdown.
• Click Change Order in the right corner.
• Now, pick and reorder the rules based on your preference.
• After making the necessary reorder, click Save Reorder.

Edit a Workflow Rule

• Go to Settings.
• Select Workflow Rules under Automation.
• Hover over and select the workflow rule you want to edit, and click Edit.
• Make your changes, and click Save.

Clone a Workflow Rule

If you need a new workflow rule with the same details present in an existing workflow rule, you can clone the existing rule. Here’s how:

• Go to Settings.
• Select Workflow Rules under Automation.
• Hover over the workflow rule you want to clone, click the dropdown to the right, and select Clone.
• In the New Workflow Rule page, review the cloned details.
• Verify the WORKFLOW RULE EXECUTION CONDITIONS, and click Update.
• Click Save.

Mark a Workflow Rule As Inactive

If you won’t be using a workflow rule for a while but want to keep it for future use, you can mark it as inactive instead of deleting it. To mark it as inactive:

• Go to Settings.
• Select Workflow Rules under Automation.
• Hover over the workflow rule you want to mark as inactive, click the dropdown to the right, and select Mark as Inactive.

Configure Notification Preferences for Workflow Rules

You can set daily limits for workflow alert triggers and add email recipients to get notified when the daily threshold is reached. You can also configure how you receive failure log notifications when a workflow rule fails. To configure:

• Go to Settings.
• Select Workflow Rules under Automation.
• Click Configure Notification Preferences in the top right corner.
• In the Configure Notification Preferences popup, fill in the following fields:
  • Usage Limit Notifications: Choose a threshold for sending notifications for workflow actions like email alerts, webhooks, and custom functions.
  • Failure Log Notifications: Select the frequency and time for notifications, and specify the email recipients who will receive the failure log updates if needed.
• Click Save.

Delete a Workflow Rule

• Go to Settings.
• Select Workflow Rules under Automation.
• Hover over the workflow rule you want to delete, click the dropdown to the right, and select Delete Workflow Rule.
• In the popup, click Yes to confirm.

Workflow Actions

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 in Email Alerts

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.

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.

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 on the top right corner of the page.

• Select Workflow Actions under Automation.

• In the Workflow Actions pane, select In-app Notifications.

• Click + New In-app Notification in the top right corner.

• On the New In-app Notification page:

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

• Go to Settings on the top right corner of the page.
• Select Workflow Actions under Automation.
• In the Workflow Actions pane, select Field Updates.
• Click + New Field Update in the top right corner.
• On the New Field Update page, enter the following details:

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 in Field Updates

Delete a Field Update

To delete a field update:

• Go to Settings on the top right corner of the page.
• Select Workflow Actions under Automation.
• In the Workflow Actions pane, select Field Updates.
• Hover the cursor over the field update that you want to delete and click the Delete icon.

Filter Field Updates

To filter the field updates:

• Go to Settings on the top right corner of the page.
• Select Workflow Actions under Automation.
• In the Workflow Actions pane, select Field Updates.
• Under Module, select a module from the dropdown for which the field update has been created.

Based on your selection, the corresponding field updates will be displayed as a list.

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:

• Go to Settings on the top right corner of the page.
• Select Workflow Actions under Automation.
• In the Workflow Actions pane, select 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 from the following 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.
  • form-data: Send data as text or files. If you select File, the custom fields for the attachment type created in the module for which you are creating this webhook will be listed in the dropdown.
  • 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.

Configuring SMS Gateways 

You can set up webhooks to send and receive message alerts through SMS gateways. All you have to do is configure the SMS gateways using the URL and follow the steps provided below. 

Bulk SMS

Bulk SMS is a popular SMS Gateway and is compatible with over 800 mobile network providers, worldwide.

URL: https://bulksms.vsms.net/eapi/submission/send_sms/2/2.0?username=%username%&password=%password%&msisdn=${CONTACT.CONTACT_MOBILE_PHONE}&message=%message_content%

To configure the URL for Bulk SMS:

• Click the Gear icon on the top right and select Automation.
• Navigate to the** Webhooks** tab and click + New Webhook.
• Copy the above URL into the URL to notify field.
• Replace the %username% and %password% placeholders in the URL with the username and password of your Bulk SMS account.
• Type your message at the end of the URL, i.e. after “message=". 
• Replace all the blank spaces in your message content by %20 and all the commas by %2C.

After formatting your message with %20 for blank spaces and %2C for commas, it should look like this:

URL: https://bulksms.vsms.net/eapi/submission/send_sms/2/2.0?username=%username%&password=%password%&msisdn=${CONTACT.CONTACT_MOBILE_PHONE}&message=Hello%20${CONTACT.CONTACT_NAME}.Thank%20you%20for%20the%20purchase%20of%20${INVOICE.INVOICE_TOTAL}

Similarly, other SMS gateways can be configured, with only the URL being different. 

SMS-Magic

SMS gateways such as SMS-Magic requires you to enter additional entity parameters to configure the webhook. 

To configure SMS-Magic:

• Enter the URL https://sms-magic.in/smapi/post in the URL to notify field.
• Click +Add Entity Paramter.
• Enter the following text in the parameter field:

<?xml version="1.0"?>
<m:Library xmlns:m="http://screen-magic.com" xmlns="http://www.defns.com">
<userid>**User_ID**</userid>
<senderid>**%Sender_ID**</senderid>
<accountid>**%Account_ID**</accountid>
<hashkey>**%hashkey%**</hashkey>
<message mobilenumber="${CONTACT.CONTACT_MOBILE_PHONE}" >
<![CDATA[${INVOICE.INVOICE_TOTAL}]]>
</message>
</m:Library>

Replace the placeholders in the URL with the User ID, Sender ID and Account ID of your SMS-Magic account. The hashkey refers to a standard hashed md5 value of a string that is a concatenation of your User ID, Password, Account ID and Sender ID.

Text Local

Text Local requires an entity parameter and a custom parameter to function.

To configure Text Local:

• Enter the URL http://api.textlocal.in/send/ in the URL to notify field.  
• Click + Add Custom Parameter.
• Add the sender and apikey parameter and replace the placeholders in the URL with the relevant information from Text Local.
• Click + Add Entity Parameter.
• Give a name for the parameter and select the required conditions from the dropdown menu. Example: numbers = ${CONTACT.CONTACT_MOBILE_PHONE} 
• Select the Add User Defined Parameters box and enter the message to be sent along with all the necessary place holders. 
• Click Save.

Other Actions in Webhooks

Delete Webhooks

To delete a webhook:

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

• 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 list, follow these steps:

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

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,

• Go to Settings on the top right corner of the page.
• Select Workflow Actions under Automation.
• In the Workflow Actions pane, select Custom Functions.
• Click + New Custom Function in the top right corner.

• On the New Custom Function page:
  • Enter a Name for your custom function and provide a small Description.
  • Choose the Module for which you want to create the custom function.
  • Choose the Programming Language in which you want to write the custom function’s code.
    • If you chose Deluge as the programming language, click Proceed and type in or drag the parameters into the Deluge editor.
    • If you chose a programming language other than Deluge, you need to enter the custom function’s code using the Zoho Finance CLI. Learn more.

• Once done, click Save.

Now, the next step is to create a workflow rule using the newly created custom function.

• Head back to the Automation pane and select 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 Users, Organization, Quotes, Invoices, Sales Orders, Purchase Orders, Customers, Recurring Invoices, Expenses, Bills, Recurring Bills, and Items 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:

Organization

The organization map supports the following fields:

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:

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:

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

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:

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:

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:

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:

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:

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:

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:

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

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:

• Go to Settings on the top right corner of the page.
• Select Workflow Actions under Automation.
• In the Workflow Actions pane, select Schedules.
• Click + New Schedule in the top right corner.

• On the New Schedule page:
  • 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.

Was this document helpful?

Yes

No

Was this document helpful?

Enter your comments or feedback on this page

Enter your email address

Refresh

Type the characters you see in the image above

By clicking Submit, you agree to our Privacy Policy .

Submit Cancel

Submit

Submit

Thank you for your feedback!