Preferences

The Preferences section will help you configure your Zoho Books organisation, and also settings for various sales and purchase modules, projects, accountant and other modules.

---

---

General

This section lets you in enable certain modules in your Zoho Books organisation and consists of other generic functions.

To access the general settings:

• Go to Settings > Preferences > General.

Enable modules

Select the modules you want to enable in Zoho Books. Once you enable them, they will be shown in the left sidebar. You’ll be able to access and configure these modules only when you enable them in this page.

Zoho Inventory Add-on

If you want to integrate with Zoho Inventory, you should have created an active organisation in Zoho Inventory either in the Standard or Professional plan. After you integrate with Zoho Inventory, you can enable the add-on here. Upon enabling this add-on, all the modules pertaining to the integration will be displayed in Zoho Books, from where you can access all the required features.

Learn more about the Zoho Inventory Add-on.

First day of work week

By default, the first working day of the week is Sunday in Zoho Books. However, you can change the first day of your work week to Sunday, Monday or Saturday.

When you change the first day of your work week, the days and dates in the calendar will be updated accordingly. This will be useful when you are selecting dates for sales and purchase transactions, and other modules.

For example, let’s say you’ve set the first day of the week as Monday. When you create an invoice and select the invoice date, this is how the calendar will be displayed.

Attach links of quotes and invoices

Attach the corresponding PDF of the quote or invoice in the email while sending it to your customer.

Encrypt PDF Files

Secure your PDF files by encrypting them while sending them to your customers. When you encrypt your PDF files, they cannot be:

• edited (or)
• converted into another file format.

Discounts

If you give discounts to your customers, you can select the level of discounts applicable on the transactions.

Choose how discounts are applied in transactions:

• I don’t give discounts: If you don’t give discount to your customers, then select this option.

• At line item level: Discount is provided for every item individually in a transaction (like an invoice).

If you have applied taxes on the line item(s), the tax is calculated after the discount is applied.

• At invoice level: Discount is provided on the whole amount in the invoice.

If you select a discount to be applied at invoice level, you can also choose to apply the Discount Before Tax or Discount After Tax.

Additional charges

You can add shipping charges and adjustments for your invoices by enabling them here.

These additional charges will show up when you are creating transactions like an invoice.

Salesperson

If you have sales persons in your organisation who manage different sales transactions, then you can associate them with the corresponding transactions (like an invoice) in Zoho Books. .

To enable sales persons for your organisation, mark the box I want to add a field for salesperson.

To view all the sales done by different sales persons in your organisation go to Reports > Sales by Sales Person.

Default Account for Billable Bills and Expenses

Choose a default Income account to track the amount in billable bills and expenses, when they are invoiced. Once you select this account, the system will automatically associate the account when an expense or a bill is invoiced.

• Select the Account for tracking billable bills and expenses while invoicing.

Let’s look at a scenario to understand how configuring this preference will affect the journal that’s recorded.

Markup for Billable Bills and Expenses

The bills and expenses that you incur on behalf of your customers, which you will invoice them later are billable bills and expenses. There are two common methods of invoicing customers:

• Invoicing the actual cost: If you incur an expense of $100, you will invoice the same amount to the customer for them to pay.
• Adding a markup: If you incur an expense of $100, you can mark up the expense amount and invoice $105 to the customer. This method will generate a 5% of extra revenue to your business.

To set a default markup percentage for billable bills and expenses:

• Enter the markup percentage.

• Click Save.

Now, when you choose the billable option in a bill or an expense, the default markup percentage will be pre-filled in the Mark up by field.

Weekly Summary Report

All the admins of your organisation can receive the summary of business transactions done in the week in their email. You can also receive the report through your Slack channel if you have integrated your Zoho Books organizaton with Slack.

To enable weekly summary reports, mark the box Send Weekly Summary report.

Organization Address Format

You can change the way your organisation or business address appears on all your sales and purchase transactions.

Rearrange the existing placeholders to change the format to add new placeholders by clicking the Insert Placeholders drop-down.

After making all the changes in the General section, click Save.

---

Customer Portal

In the Customer Portal Preferences page, you can:

• Upload or remove Your organisation Logo
• Change the theme of your Organisation
• Configure Portal settings
• Set up Custom Domains

Learn more about Customer Portal Preferences.

---

Vendor Portal

In the Vendor Portal Preferences page, you can:

• Configure vendor portal preferences
• Enable notifications
• Allow vendors to upload documents
• Allow vendors to accept/reject purchase orders

Learn more about Vendor Portal Preferences.

---

Customers and Vendors

In the Customers and Vendors Preferences page, you can:

• Allow duplicates for contact display name
• Set a customer credit limit
• Change the billing address format of the customer
• Change the shipping address format of the customer

Learn more about Customer and Vendor Preferences.

---

Projects

Configure different settings related to the Projects module in Zoho Books such as:

• Round off time
• Maximum hours/day for logging time
• Timesheet Approvals

Learn more about Project Preferences.

---

Accountant

Configure different settings related to the Accountant module in Zoho Books such as:

• Chart of Accounts
• Vendor Advances
• Journal Custom Fields

Learn more about Accountant Preferences.

---

Transaction Number Series

The transactions you create in Zoho Books are numbered by the default transaction series. For instance, the first invoice you create will be numbered as INV-001, the second invoice as INV-002, followed by INV-003 and so on.

However, some businesses might require their transactions to be numbered and tracked by a different transaction series that is not the default series. Let’s take the help of a scenario to understand this better.

Similarly, you can create multiple transaction series in addition to the default transaction series. Each transaction series can be created with unique prefixes and series.

Once you’ve created a transaction series, you can select it while creating a transaction. Consequently, the transaction will be numbered based on the prefix and series that had been configured while creating the transaction series.

• Enable Transaction Series
• Add Transaction Series
• Configure Transaction Series
• Delete Transaction Series

Enable Transaction Series

To start configuring multiple transaction numbers series:

• Click Settings in the top right corner and select Preferences from the dropdown.
• Select Transaction Number Series under Preferences.
• Click Enable Transaction Number Series.

Once you enable multiple series of transaction series, you will be able to configure number series for your transactions in Zoho Books. To do that:

• Click Configure next to the Transaction Number Series section.

Add Transaction Series

You will be able to view the current transaction series for your transactions listed as the Default Transaction Series. In addition to the Default Transaction Series, you will be able to create new transaction series. To do that:

• Click Settings in the top right corner and select Preferences from the dropdown.
• Select Transaction Number Series under Preferences.
• Click Add Transaction Series in the top right corner.
• Enter the name for the transaction series.

• Enter the prefix and the series numbers for the transactions of your choice.
• Click Save.

Once you’ve created a transaction series, you will be able to select the transaction series while creating the respective transaction.

Configure Transaction Series

You can edit the transaction series you’ve created.

• Click Settings in the top right corner and select Preferences from the dropdown.
• Select Transaction Number Series under Preferences.
• Hover over the transaction number series and click the dropdown to the right of the transaction series.
• Click Configure.

• Enter the prefix and the series numbers for the transactions of your choice.
• Click Save.

Once you configure the transaction series, the transactions you create will be numbered based on the new prefix and series.

Delete Transaction Series

To delete a transaction series you’ve created:

• Click Settings in the top right corner and select Preferences from the dropdown.
• Select Transaction Number Series under Preferences.
• Hover over the transaction number series and click the dropdown to the right.
• Click Delete.

Once you delete the transaction series, you will no longer be able select the transaction. series while creating a transaction. Furthermore, the transaction series information of the deleted transaction series will not be available.

---

Record Locking

Record Locking allows you to lock the records (invoices and credit notes) in your organisation. Once locked, only the users and roles with sufficient permission will be able to edit or delete them.

Enable Record Locking

To enable Record Locking for a module:

• Go to Settings and select Preferences.
• Select the module for which you want to enable record locking.
• In the General tab, scroll down and slide the toggle next to Record Locking to Enabled.

• Click Save.

Provide Users Permission to Edit Locked Records

By default, your organisation’s admins can lock and unlock records, and edit or delete locked records. However, if you also want other users in your organisation to be able to edit locked records, you can create a new role and add users to it, or edit and provide permission to an existing role.

To provide permission to a new user:

• Go to Settings and select Users and Roles.
• Switch to the Roles tab and click New Role on the top right corner of the page.

• Enter the Role Name.

• Scroll down and go to the module for which you want to give the user the permission to edit locked records.

• Select the Edit Locked Records option for that module.

• Click Save.

To provide permission to an existing role:

• Go to Settings and select Users and Roles.

• Switch to the Roles tab.

• Click Edit next to the role for which you want to provide permission to edit the locked records.

• Scroll down and go to the module for which you want to give the user the permission to edit locked records.
• Check the Edit Locked Records option for that module.

• Click Save.

Lock a Record

Now that you’ve enabled Record Locking, you can lock individual records. To lock a record:

• Go to the module in which the record that you want to lock exists. For example, go to the Invoices module.
• Select the invoice that you want to lock.
• Click the More button and select Lock Invoice from the dropdown.

• In the pop up that appears, enter the reason for locking the invoice and click Lock.

The invoice is now locked and only users with permission to edit locked records will be able to edit or delete it.

Unlock a Record

To unlock the record that you previously locked:

• Select the record that you had locked. For example, the invoice that we locked previously.
• Click the More button and select Unlock Invoice from the dropdown.

• In the pop up that appears, enter the reason for unlocking the invoice and click Unlock.

Disable Record Locking

To disable record locking for a module:

• Go to Settings and select Preferences.
• Select the module for which you want to disable record locking.
• In the General tab, scroll down and slide the toggle next to Record Locking to Disabled.

• Click Save.

Field Customization

In Zoho Books, you can create additional fields called custom fields for different modules. You can create custom fields from the respective module’s preferences.

When will custom fields be used?
Let’s say you deal with customers from different industries. To track which industry a particular customer belongs to, you can create a custom field called Industry in the Customers and Vendors preferences.

In this section:

• Create Custom Field
• Custom Field Limitations
• Edit Custom Field
• Mark Field as Inactive/Active
• Delete Custom Field

Create Custom Field

To create a new custom field:

• Go to Settings and select Preferences.
• Select the module for which you want to add the custom field in the left menu.
• Select the Field Customisation tab at the top of the page.
• Click + New Custom Field on the top right corner of the page.
  

• Fill in the following fields:

Label Name

Select an appropriate name for your custom field. This field will be displayed when entering data in the respective transaction.

Data Type

Choose the data type for the data that you will enter or store in the custom field. Zoho Books provides the following data types for custom fields:

Text Box (Single Line)

Select the Text Box (Single Line) data type to record any additional information. You can enter a short text, numerical value, or a combination of both up to 255 characters. Only A-Z, 0-9, and special characters are supported.

Email

You can record additional email addresses using this field. For example, brandon.taylor@zylker.com.

URL

You can record and save website URLs using this field. For example, https://www.zoho.com/books

Phone

You can use the Phone data type to store additional phone numbers. For example, (123)-456-7890.

Number

The Number field can be used to store whole numbers and negative numbers. For example, 7 or -7.

Decimal

This field allows you to record decimal values that are positive or negative. For example, 12.90 or -94.53.

Amount

This field allows you to record the amount along with the default currency code set for your organisation. For example, USD50, GBP76, AUD30 etc.

Percent

You can use this data type to record values in percentage.

Date

In this field, you can record custom as well as relative date values. For example, Custom Date: 19 Jun 2019, Relative Date: Today, Tomorrow, Starting Date of Month etc.

Date and Time

The Date and Time data type is used when you have to display both the date and time values. It displays the value in YYYY-MM-DD HH:MM format.

Check Box

Using the Check Box data type, you can confirm an action or a fact, or enable an option. Here, you can also choose to have the check box ticked by default, if required.

Auto-generate Number

Using this data type, you can auto-generate values with prefixes or suffixes of your choice. Also, you can associate the custom field to existing invoices and auto-generate this number in all of them.

Dropdown

You can use the Dropdown data type in scenarios where you have to select one option from the list of options provided.

Multi-select

The Multi-select data type is similar to the dropdown data type. Using multi-select, you can select up to 30 options from the list of options available.

Lookup

The Lookup data type allows you to pull data from one module and display it inside another module. Learn more about the Lookup data type.

Text Box (Multi-line)

The Text Box (Multi-line) data type also lets you to record any additional information of your choice. You can enter text, numerical value, or a combination of both up to 36000 characters. Only A-Z, 0-9, and special characters are supported.

Attachment

You can use the Attachment data type to add files such as documents, PDFs, and images.

The formats supported for each file type are listed below:

• Images: GIF, PNG, JPG, JPEG, BMP, TIF, and TIFF types.
• Documents: XLS, XLSX, DOC, DOCX, XML, CSV, and TXT types.
• PDF

You can attach one file whose size limit is less than 7 MB.

Formula

The Formula data type enables you to build a formula that performs calculations using predefined functions, fields, and operators. Learn more about the Formula data type.

For fields that don’t contain PII, you can provide default values. The preview of the field and the text will be shown in the form itself.

Data Privacy

Select PII (Personally Identifiable Information) or ePHI (Electronic Protected Health Information) based on the information you will enter in this field.

• Select PII if the information you enter is confidential and can be used to identify a person. You can mark fields such as Text, Email, URL, Phone, Number,and Date as PII. You can encrypt and store it if the data is sensitive or store it without encryption if the data is non-sensitive. Choose if the information you enter will be sensitive or not sensitive:

  • Sensitive data. Encrypt and store it. This data can be viewed only by users with permission to access PII.
  • Not sensitive data. Store it without encryption. Only users with access to protected data can view the details. However, users can use this field to perform advanced searches.

• Select ePHI if the information that you enter can be used to identify a patient. For example, an electronic copy of a medical report will be ePHI. You can mark only fields such as Text, Email, URL, Phone, and Date as ePHI. The data will be treated as sensitive; therefore, it will undergo encryption before being securely stored. Only users with access to protected data can access the fields. Users cannot use this field to perform advanced searches.

Prevent Duplicate Values

• Select Yes if the value entered in this custom field should be unique.
• Select No if the value entered in this custom field does not have to be unique.

Default Value

The value you enter will be the default value of the custom field. For example, if you create a custom field for the Invoices module and set the Default Value as 1. It will automatically fill the custom field with 1 when you create an invoice without providing any value for the custom field.

You can also choose to inherit values from fields in other modules. To do this:

• Select Inherit value next to Default Value.

• Click the first dropdown next to the Inherit Value From field and select the module from which you want to inherit the value. You can inherit data from modules related to the module for which you’re creating the custom field. For example, if you’re creating the custom field for the Invoices module, you can inherit the fields in the Customers module.
• Now, click the second dropdown next to the Inherit Value From field and select the field of the module from which you want to inherit the value. This will be the default value for this custom field when you create transactions.

Is Mandatory

If you mark this field as mandatory, then the form in which the field appears cannot be saved if this field is left empty.

Show in all PDF

While you can enter data in the custom field and save it, you can choose whether this data is displayed in the transaction PDF or not.

Display in Portal

In case your custom field is an Attachment, enabling this option allows your customers to view the attachments you’ve added for their invoices and quotes in the portal.

• After providing data in all the fields, click Save.

From now on, when you create a record in the respective module, the custom field will be displayed.

Custom Field Limitations

There are certain limitations to the number of custom fields that can be created for each data type. Based on the limitations, custom fields are split into six sections: Numerical, Decimal, String, Boolean, Long Text, and Multi-select.

You can know the number of custom fields that are available for your use. Here’s how:

• Click the Gear icon in the top right corner and select Preferences.
• Click Invoices or any other module and select the Field Customisation tab.
• Click the Custom Fields Usage option near the + New Custom Field button.

Edit Custom Field

You can change the details you have saved for a custom field you created in Zoho Books. Here’s how:

• Go to Settings and select Preferences.
• Select the module for which you want to edit the custom field in the left menu.
• Select the Field Customisation tab at the top of the page.
• Hover over the custom field that you want to edit.
• Click Edit.

• Make the required changes and click Save.

API Field Name

Once you save a custom field, you can edit it to find the API Field Name. This name will be used when referring to this custom field for an API call.

Mark Field as Inactive/Active

If you don’t want to enter data in any custom field temporarily, you can choose to mark it as inactive.

To mark as custom field as inactive:

• Go to Settings > Preferences.
• Select the module for which you want to mark a custom field as inactive in the left menu.
• Select the Field Customisation tab on the top of the page.
• Hover over the custom field you want to mark inactive and click the Dropdown icon.
• Select Mark as Inactive.

If you have marked a custom field as inactive, you can make it active again. Here’s how:

• Hover over the custom field you want to mark active and click the Dropdown icon.
• Select Mark as Active.

Delete Custom Field

You can delete a custom field you have created in Zoho Books. Here’s how:

• Go to Settings > Preferences.
• Select the module for which you want to delete the custom field in the left menu.
• Select the Field Customisation tab in the top of the page.
• Hover over the custom field you want to mark active and click the Dropdown icon.
• Select Delete Custom Field.

If you have added data in a custom field which is associated with a transaction, you cannot delete the custom field. If you want to delete the custom field, you would have to delete the corresponding transaction.

Alternatively, you can mark the custom field as inactive.

---

Validation Rules

Validation Rules in Zoho Books help you create new rules that set restrictions for the data being recorded. So, when a user tries to enter data in a field that you have set a restriction for, it passes through the validation rule. If the value you enter in the field violates the condition you’ve set, an alert message is displayed and the transaction is not created. The user will also be able to set multiple criteria for a single validation rule.

Currently, Validation Rules are available only for Quotes and Sales Orders.

Let us understand how validation rules work with the help of few scenarios.

In this section:

• Create Validation Rule
• Multiple Criteria and Subrules
• Execute Validation Rules
• Other Actions for Validation Rules

Create Validation Rule

You can create a validation rule by setting certain criteria for the fields in a transaction. Here’s how:

• Go to Settings > Preferences.
• Select the module for which you would like to create a validation rule (for example, Quotes).
• Go to the Validation Rules tab and click + New Validation Rule.

• Choose the field for which you want to create a validation rule. This can either be a custom field or any of the default fields in a transaction.
• Add the condition to be met in the adjacent drop-down menus.
• Enter the Alert Message to be displayed when the transaction violates the validation rule.

• Click Continue and in the page that follows, click Save.

If you want to create a new validation rule for the same field:

• Select the field for which you had created a validation rule (from the list page).
• Click + Add Another Validation and repeat the steps mentioned above.

Multiple Criteria and Subrules

A validation rule is applicable for all transactions. However, if you would like to apply it for specific transactions based on multiple criteria, or create a new rule with the same condition, refer the following:

• Adding Multiple Criteria
• Adding Subrules

Adding Multiple Criteria

When you create a validation rule, it will be applicable for all transactions by default. You can also choose the rule to be applied to transactions based on specific criteria.

Here’s how you can add multiple criteria:

• Go to Settings > Preferences.
• Select the particular module and go to the Validation Rules tab.
• For new rules: While creating a validation rule, enter the details and click Continue. In the page that follows, click the Pencil icon near the rule.
  For existing rules: Click the Edit option in the validation rules list page and in the details page, click the Pencil icon near the rule.
• Click the option Based on specific criteria in the pop-up that appears.
• Set the criteria using the options provided.

• Click + Add Criteria for more options and use the - sign to remove criteria.
• Click Edit Pattern to change the criteria pattern based on your preferences and click Save.
• Click Done.

Adding Subrules

If you would like to include an additional rule to your existing condition, you can add Subrules. This is applicable only when you’ve chosen to apply the rule to transactions based on specific criteria.

Here’s how you can create subrules:

• Go to Settings > Preferences.
• Select the particular module and go to the Validation Rules tab.
• Select the field for which you have created a validation rule.
• Click + Add Subrule and a pop-up appears.

• Enter the Criteria and the Alert Message.
• Click Done.
• Verify the subrule you had created and click Save for the changes to reflect.

Execute Validation Rules

Once a Validation Rule is created and saved, it will be applicable for all transactions created henceforth. When any new transaction violates a validation rule, an alert message will be displayed to the users.

Other Actions for Validation Rules

Once you’ve created a validation rule you will be able to edit, mark it as inactive or delete them. Here’s how:

• Go to Settings > Preferences.
• Select the module for which you’ve enabled validation rules.
• Hover over the validation field to perform the following actions:
  • Edit: Change the message or the criteria of a validation rule.
  • Mark as Inactive: Temporarily disable the validation rule. You can enable it again by clicking Mark as Active.
  • Delete: Permanently delete a validation rule by clicking the Trash icon.

---

Custom Buttons & Links

In Zoho Books, you can create new buttons to perform tailor-made actions for your transactions or open external links. You can create them using deluge script and execute actions based on the functions you add.

You can create custom buttons/links for:

• Items
• Contacts - Customers
• Sales - Quotes, Invoices, Sales Orders, Retainer Invoices and Credit Notes
• Purchases - Expenses, Bills, Purchase Orders and Vendor Credits
• Projects

In this section:

• Custom Buttons

  • Use Cases for Custom Buttons
  • Create Custom Buttons
  • Execute Custom Actions
  • Reorder Custom Buttons

• Custom Links

  • Use Cases for Custom Links
  • Create Custom Links
  • Open External Links

• Edit/Delete Custom Buttons and Links

Custom Buttons

Users can create new buttons to perform a set of actions based on their requirements. Users can create custom buttons that can be be executed only by them or by everyone.

Use Cases for Custom Buttons

Here are a few cases where new buttons can be created to execute custom actions. However, you can create custom buttons based on your firm’s requirements.

Create Custom Buttons

To create a custom button:

• Go to Settings > Preferences.
• Select the module for which you want to create a custom button.
• Go to the Custom Buttons tab.
• Click + New in the top right corner.

• Enter a Custom Button Name.

• Select who can view the Custom Button, Only Me or Everyone.

You can also select the location of the custom button in the Invoices and Quotes modules. A set of arguments will be available in the Deluge editor based on the location that you select. You can use these arguments to write the custom button’s script.

Location	Description	Arguments
Details Page Menu	Places the button in the details page of invoices or quotes.	Organisation details, User details, Invoice/quote details
List Page - Action Menu	Places the button in the list page of the Invoices or Quotes module.	Organisation details, User details
List Page - Bulk Action Menu	Places the button in the action bar, when performing bulk actions in the Invoices or Quotes module.	Organisation details, List of invoices/quotes, User details

• Drag and drop options to create a Deluge function that will help create your custom buttons.

• Click Save to save your custom button.
• Click Save and Execute to apply the action on your transactions/contacts/items. In the pop-up that appears, enter your Transaction/Contact/Item ID and click Execute.

Note: The ID is a combination of numbers that can be found in the URL of a particular Transaction/Contact/Item.

Execute Custom Actions

To view and execute the custom button:

• Go to the module for which you created a Custom Button.
• Select a transaction/contact/item on which you would like to apply the custom button.
• Click More > More Actions > Custom Button Name to execute it.

Reorder Custom Buttons

This feature allows you to change the sequence of custom buttons listed on the details or list pages of a module, enhancing user interface customisation.

Let’s take a look at how to reorder the custom buttons created for the Invoices module. You can follow the same steps for the custom buttons created for other modules.

• Go to Settings on the top right corner of the page and select Preferences.
• In the Preferences pane, select Invoices.
• Switch to the Custom Buttons tab.
• Select a location other than All using the Location filter.

• Click Change Order.

• Drag and drop the custom buttons to change their order.
• Click Save Reorder after you have reordered the custom buttons.

The custom buttons will be reordered based on your preference.

---

Custom Links

Zoho Books allows you to open external links from your application by attaching links to the button you create. You can also insert placeholders in the links and drill down to the details.

Use Cases for Custom Links

To create a custom link:

• Go to Settings > Preferences.
• Select the module for which you want to create a custom link.
• Go to the Custom Buttons tab.
• Click + New drop down and select Custom Link in the top right corner.

• Enter a Custom Link Name.
• Select who can view and execute the Custom Button- Only Me or Everyone.
• Enter the URL of the external website and Insert Placeholders if you want to look up for specific details in the page.

• Click Save.

To open external links:

• Go to the module for which you created a Custom Link.
• Select a transaction/contact/item for which you would like to view the website.
• Click More > More Actions > Custom Link Name to view it.

Edit/Delete Custom Buttons and Links

To edit/delete a custom button or link that you had created:

• Go to Settings > Preferences
• Select the module for which you want to create a custom link.
• Go to the Custom Buttons tab and all the buttons created previously will be listed there.
• Hover over the buttons and you will be able to find the Edit/Delete option.

• Click the Edit or the Trash icon to edit or delete it.

---

Related Lists

The Related Lists feature allows you to fetch and view data from within the app as well as from other third-party services. This comes in handy when you want to cross-reference data from different entities.

You can create related lists for:

• Items
• Customers and Vendors
• Sales - Quotes, Invoices, Sales Orders, Retainer Invoices and Credit Notes
• Purchases - Expenses, Bills, Purchase Orders and Vendor Credits
• Projects

In this section:

• Create Related Lists
• Edit/Delete Related Lists
• Sample Function

Create Related Lists

There are two ways to create a related list:

• By creating a lookup custom field
• By writing a deluge script

By creating a lookup custom field

The lookup custom field allows you to pull data from one module and access it inside another module in Zoho Books. When you create a lookup field in one module, its associated details will be available as a related list in the other module. 

By writing a deluge script

With deluge scripts, you can connect Zoho Books with other third-party services to access their data.

To create a related list using deluge:

• Go to Settings > Preferences.
• Go to the module for which you wish to create a related list. In this case, Customers and Vendors.
• Navigate to the Related Lists tab.
• Click the New button in the top right corner or select New Related List.

• Enter a suitable title for the related list, and choose who can see this list.
• Write a deluge script to fetch data from the connected third-party service. In this case, from Zoho Desk.

• Click Save, or Save and Execute to run the function.

The lists will be displayed under the Related Lists tab in the respective modules.

Note:

• The deluge script must return a map that contains ‘header_context’ and ‘data’ in the following format:

{
header_context: [
{
key: 'customer_name',
value: 'Customer Name'
},
{
key: 'invoice_number',
value: 'Invoice Number
}
],
data: [
{
customer_name: <customer_name>,
invoice_number: <invoice_number>
}
]
}

• There are two ways to specify the value of the data node:

  • To display a customer name as a string:

customer_name: <customer_name>

• To display a customer name as a hyperlink

customer_name: {
"value": <customer_name>,
"isExternal":true, // To open the link in separate tab.
"link": <web_url_path>
}

Edit/Delete Related Lists

To edit/delete a related list that you had created:

• Go to Settings > Preferences.
• Select the module which has the related list you wish to delete.
• Click the Related Lists tab.
• Hover over the list that you wish to delete/edit.
• Click Edit to make changes to the list or click the down arrow and select Delete to permanently delete.

Sample Function

Here’s a sample function for Scenario 2 that allows Zoho Books users to access customer details in Zoho Desk:

searchMap = Map();
searchMap.put('fullName', customer.get("contact_name"));
searchMap.put('orgId', XXXXX); //Zoho desk orgId

searchList = invokeurl
[
  url : "https://desk.zoho.com/api/v1/contacts/search"
  type : GET
  parameters: searchMap
  connection: "zohodesk"
];

contacts = searchList.get('data').toList();
contact = contacts.get('0');
contactId = contact.get('id');

paramsMap = Map();
paramsMap.put('orgId', XXXXX);
paramsMap.put('include','owner');

contactInfo = invokeurl
[
  url : "https://desk.zoho.com/api/v1/contacts/" + contactId
  type : GET
  parameters: paramsMap
  connection: "zohodesk"
];

owner = contactInfo.get('owner');
happiness = contactInfo.get('customerHappiness');

headerData = List();
headerData.add({"key":"owner_name", "value":"Owner Name"});
headerData.add({"key":"good_percent", "value":"Good Percentage"});
headerData.add({"key":"bad_percent", "value":"Bad Percentage"});
headerData.add({"key":"desk_url", "value":"Desk Url"});

details = Map();
details.put("owner_name", owner.get('firstName') + owner.get('lastName'));
details.put("good_percent", happiness.get('goodPercentage'));
details.put("bad_percent", happiness.get('badPercentage'));
details.put("desk_url", {"value":contact.get('lastName'), "isExternal":true, "link":contactInfo.get('webUrl')});

listData = List();
listData.add(details);

resultMap = Map();
resultMap.put("header_context", headerData);
resultMap.put("data", listData);
return resultMap;

---