Extension Components

Once you have created an extension as mentioned in the create extensions help document, the next step is to add components to it. Components are the building blocks of an extension. The components will be available in the Build section at the top.

Components

The Zoho Books Developer Portal supports the following components:

Preferences

You can customize extensions based on your requirements using these components from the Preferences pane:

Field Customization

If the fields in a module do not meet your requirements, you can create additional fields to store the required information using custom fields. Read our help document on Custom Fields to learn more about the feature.

Custom Buttons and Links

Create custom buttons to perform tailor-made actions for your transactions or open external links. You can create them using a deluge script and execute actions based on the functions you add. Read our help document on Custom Button and Links to learn more about the feature.

Using Related Lists, you can fetch and view data from within Zoho books as well as from other third-party services. This comes in handy when you want to cross-reference data from different entities. Read our help document on Related Lists to learn more about the feature.

Meta Fields

Meta fields are fields that you can use when the value stored in the custom field is static or constant. In the Zoho Books Developer Portal, you can use meta fields to store a plugin’s data.

Let’s use the Snail Mail extension as an example to better understand why meta fields are used. This extension enables users to send physical copies of invoices and quotes to their customers through a third-party service. When a user sends an invoice or quote, a request is dispatched to the third party, who then furnishes a response containing details about the mail delivery, such as the Date, Time, Status, Job ID, and Description.

While this data isn’t directly associated with the invoice, it serves as a historical record for each invoice. Storing this data requires additional custom fields, which will exhaust the custom fields available. Therefore, meta fields are employed for storing and retrieving this information.

Meta fields require the UPDATE and READ scope of modules in which they are used. In the above example, the INVOICE.UPDATE scope is necessary for the PUT call, while the INVOICE.READ scope is required for the GET call.

The code and sample response for these calls are given below.

1. GET

Code

api_root_endpoint = organization.get("api_root_endpoint");
organization_id = organization.get("organization_id");
invoice_id = invoice.get("invoice_id");
Body = Map();
Body.put("Job ID","123456789123456789");
Body.put("Status","Initiated");
Body.put("Date","30/03/2024");
Body.put("Time","14:00:00");
Body.put("Description","INV-003");
response = invokeurl
[
	url :api_root_endpoint + "/invoices/" + invoice_id + "/metadata/**_*****?organization_id=" + organization_id
	type :PUT
	parameters:Body.toString()
	connection:”zfsnailmail”
];

Sample Response

{
	"code": 0,
	"message": "Meta Field has been updated.",
	"metadata": {
		"data": {
			"Status": "Initiated",
			"Job ID": "123456789123456789",
			"Description": "INV-003",
			"Time": "14:00:00",
			"Date": "30/03/2024"
		},
		"visibility": "everyone"
	}
}

2. PUT

Code

api_root_endpoint = organization.get("api_root_endpoint");
organization_id = organization.get("organization_id");
invoice_id = invoice.get("invoice_id");
response = invokeurl
[
	url :api_root_endpoint + "/invoices/" + invoice_id + "/metadata/**_*****?organization_id=" + organization_id
	type :GET
	connection:”zf”snail mail
];

Sample Response

{
	"code": 0,
	"message": "success",
	"metadata": {
		"data": {
			"Status": "Initiated",
			"Job ID": "123456789123456789",
			"Description": "INV-003",
			"Time": "14:00:00",
			"Date": "30/03/2024"
		},
		"visibility": "everyone"
	}
}

The fetched data is then displayed as a related list on the corresponding invoice’s Details page.

By default, a meta field will be created for every extension, and each endpoint can store up to 64,000 characters. A unique key is generated for the meta field of each extension. To identify the unique key of the meta field:

Go to Zoho Books Developer Portal.
Switch to the Build section at the top.
Select Preferences in the left sidebar.
Select a module in the Preferences pane.
Click Learn Meta Fields at the top right corner.

In the pane that appears, go to the To Store or To Retrieve section under API Documentation.
The 5 alphabets after /pu_ in the URL field will be the unique key for the meta field of your extension.

By default, the details of the meta fields will not be shown to the users. However, if the meta field is used in a widget or related list, the meta field’s details can be accessed from the GET API call.

The table below is the list of modules that support meta fields:

Module	URL
Invoices	/invoices/(\d+)/metadata/{plugin_identifier}
Quotes	/estimates/(\d+)/metadata/{plugin_identifier}
Sales Orders	/salesorders/(\d+)/metadata/{plugin_identifier}
Credit Notes	/creditnotes/(\d+)/metadata/{plugin_identifier}
Retainer Invoices	/retainerinvoices/(\d+)/metadata/{plugin_identifier}
Customer Payments	/customerpayments/(\d+)/metadata/{plugin_identifier}
Recurring Invoices	/recurringinvoices/(\d+)/metadata/{plugin_identifier}
Delivery Challans	/deliverychallans/(\d+)/metadata/{plugin _identifier}
Bills	/bills/(\d+)/metadata/{plugin_identifier}
Expenses	/expenses/(\d+)/metadata/{plugin_identifier}
Recurring Expenses	/recurringexpenses/(\d+)/metadata/{plugin_identifier}
Purchase Orders	/purchaseorders/(\d+)/metadata/{plugin_identifier}
Vendor Payments	/vendorpayments/(\d+)/metadata/{plugin_identifier}
Recurring Bills	/recurringbills/(\d+)/metadata/{plugin_identifier}
Journals	/journals/(\d+)/metadata/{plugin_identifier}
Vendor Credits	/vendorcredits/(\d+)/metadata/{plugin_identifier}
Projects	/projects/(\d+)/metadata/{plugin_identifier}
Users	/users/(\d+)/metadata/{plugin_identifier}
Items	/items/(\d+)/metadata/{plugin_identifier}
Composite Items	/compositeitems/(\d+)/metadata/{plugin_identifier}
Packages	/packages/(\d+)/metadata/{plugin_identifier}
Customers	/customers/(\d+)/metadata/{plugin_identifier}

PDF Templates

Customize the look and feel of sales and purchase transactions to suit your brand better in Zoho Books. You can customize an existing template or create a new one. Read our help document on PDF templates to learn more about the feature.

Email Notifications

Customize the emails sent from your organization. Read our help document on Email Notifications to learn more about the feature.

Automation

You can automate your day-to-day work processes to save time and money. Here’s a list of automation tasks that can performed in Zoho Books:

Workflow Rules

A workflow rule consists of actions that comprises of Email Alerts, In-App Notifications, Field Updates, Webhooks, and Custom Functions that play an essential role in executing a task. A workflow rule may employ one or more workflow actions to automate the tasks of your organization. Read our help document on Workflow Rules to learn more about the feature.

Workflow Actions

Workflow Actions in Zoho Books allows you to automate tasks and actions based on predefined triggers or conditions. The workflow actions available in Zoho Books are:

Email Alerts

Email Alerts are automated emails that are sent when the criteria in a workflow rule are met. You can create new email alerts and use them in a workflow rule. Read our help document on Email Alerts to learn more about the feature.

In-App Notifications

In-app Notifications help you notify your users of an event or a significant activity that has taken place in your organization. Read our help document on In-App Notifications to learn more about the feature.

Field Updates

Field Updates automatically make changes to a field within a particular module when the workflow is triggered. Read our help document on Field Updates to learn more about the feature.

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 Webhooks to learn more about the feature.

Custom Functions

Custom functions in Zoho Books allows you to write small pieces of code to automate your business processes. Read our help document on Custom Functions to learn more about the feature.

Schedules

Create and run predefined tasks at a specified time or 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. Read our help document on Schedules to learn more about the feature.

WebTabs

Web Tabs are similar to browser tabs, but are accessible from within Zoho Books. They enable you to access web pages or applications that provide you with an embeddable URL. You can create a maximum of 10 web tabs in Zoho Books. This feature is available only for users in the Premium Plan (India) and Professional Plan (all other editions) of Zoho Books. Learn more about web tabs

Signals

A Signal sends in-app notifications to users in your organization whenever an action is performed in a third-party app that you had configured. Read our help document on Signals to learn more about the feature.

Widgets

Sometimes, you may want to access features from third-party applications in Zoho Books. Widgets can help you achieve this using embeddable UI components. Read out help document on Widgets to learn more about them.

Incoming Webhooks

Incoming webhooks is a method of bringing information from a third-party service or an API request to Zoho Books on occurrence of an event. In Zoho Books, you can use the action performed in the third-party service as a trigger to perform a task in Zoho Books. Read our help document on Incoming Webhooks to learn more about the feature.

When you create an incoming webhook in the developer portal, you will not be given the ZAPI Key URL to identify which organization is installing the extension. The ZAPI Key URL can be obtained by editing an existing incoming webhook.

In the On Installation tab, you have to use this snippet to fetch the organization specific ZAPI Key URL and configure the outgoing webhook in your end. Here’s how:

Go to the Configure section at the top.
Select Install Actions in the left sidebar.
Paste the script that you copied from the incoming webhook in the Deluge script in the On Installation tab.

The script will be executed automatically for the organization installing the extension on every successful installation.

Connections

You can connect to a third-party service or other Zoho applications using connections in Zoho Books. You can set up a connection from the Deluge editor page. Read our help document on Connections to learn more about the feature.

Custom Views

Create custom views to filter the records in any module based on the criteria you’ve set. Read our help document on Custom Views to learn more about the feature.

Custom Modules

There might be times when the predefined modules in Zoho Books may not be sufficient to manage all your business requirements. In such cases, you can create a custom module to record other data. Read our help document on Custom Modules to learn more about the feature.

Payment Gateway Connectors

A Payment Gateway Connector bridges software and a payment gateway, securely transferring payment data from the customer to the gateway for processing, and back to the software.

If you’re a developer, you can create an extension for payment gateways that are not currently supported by Zoho Books using Payment Gateway Connectors. Once done, you can publish and sell your extension in the Zoho Marketplace to Zoho Books users.

Zoho Books users can then install your extension for their Zoho Books organization and use it to receive payments.

To create a payment gateway extension, email us at platform-support@zohofinance.com and we will enable Payment Gateway Connectors for your organization.

Extension Creation Guidelines

Now that you’ve learned about the various components of an extension, you can begin building your extension. However, it’s crucial to ensure that your extension aligns with the Zoho Books extension guidelines. This makes it easier for your extension to be approved or to be published in Zoho Marketplace.

The guidelines that you have to follow when developing an extension are:

Common Guidelines

Do not use any unwanted components or scripts in the extension.
Do not use more than 5 custom fields in each module.
Ensure that the extension name does not contain the name of the product for which it is developed. For example, if you’re developing an extension for Twilio, the extension name should be Twilio and not Twilio for Zoho Books.

Guidelines for Connections

If you’re using connections in your extension, enable only the scopes that are required for the connection.
If the connection’s authentication type is OAuth2, include access_type=offline in the Authorize URL field.
Ensure that the connection name is a combination of the service name and the extension name, separated by a hyphen in Pascal case. For example, ZohoBooks-Twilio.
If individual users of an organization have to connect and authorize the connections used in your extension, set the value for the user access param to true.

Guidelines for Custom Scripts

If you want to publish the extension in other Zoho Finance apps, do not use any internal SDK methods. For example, instead of using zoho.books.getRecord, use invokeurl.
Include api_root_endpoint in the Invoke call’s URL.
Do not create components using scripts.
If you’re using comments in the custom scripts, ensure that you do not add personal or sensitive information as comments.
When comparing the name of a field with a string, use the API field name for comparison instead of its label name. For example, if a custom field’s label name is “Landmark” and its API field name is “cf_landmark”, compare using custom_fields.get(“api_name”)" == “cf_landmark” and not custom_fields.get(“label”) == “Landmark”.

Guidelines for Widgets

If you’re using widgets in the extension, ensure that they adhere to the style used in the Zoho Books user interface.
Ensure that the widget’s data is not displayed in the console tool.

Guidelines for Global Fields

If you’re using global fields in custom scripts, check the Allow use of Global fields in this custom function option.
If the data type of the global field is Users or Roles, and notifications are sent to the users, set the value of the is_mandatory param to true.

Guidelines for Schedules

Set the param User Access to false if you are using a connection in your schedule.

Was this document helpful?

Yes

Let us know where we can improve

By clicking Submit, you agree to our Privacy Policy .

Thank you for your feedback!

Want a feature?

Suggest

ON THIS PAGE…