Configuration Extensions

The next step after you’ve built your extension is to configure it. The Configure section in the Zoho Books Developer Portal has two major segments:

Global Fields

Global fields are variables that store static information. They allow you to replace key values in various elements of Zoho Books easily, facilitating system-wide changes and personalization.

Let’s say you’re using an email alert component in your extension to get the email address of the user installing the extension. To do this, you can create a global field with the data type as Users. Now, when a user installs the extension, the user’s email address will be fetched using the global field and will be displayed in the deluge script. So in this case, the global field is used to fetch a user’s email address at the time of the extension’s installation.

To create a global field:

The data types supported are:

Type Description
Everyone The global field will be visible to everyone, and the value will be obtained from the user installing the extension.
Read Only The global field will be visible to all users at the time of installation but can only be edited by the extension’s developer.
Hidden The global field will be hidden from all users and can only be accessed by the extension’s developer from the developer portal.

The scopes available for a global field are:

Request Type Scope Description
Read Settings.READ Fetch the global field.
Update Settings.UPDATE Update the global field.

There might be cases where certain configurations are required for the effective functioning of an extension.

For example, if an extension requires data from a third-party app when installing the extension, users have to enter the credentials of their account in the third-party app. Using Settings Widget you can create such configurations when customizable input fields are required.

To add a widget to the extension:

Click Upload Widget New Widget pop-up

Note: The placeholders must be used as the global field identifier to facilitate read and update operations in the scripts and widgets.

Both global fields and widgets cannot be displayed together when a user installs the extension. If you want to configure a global field inside a settings widget, you can do it using the below scripts.

You can use the below script to fetch and update the global field using widget sdk:

let placeholder = 'vl__abc_field';
let { organization } = await ZFAPPS.get("organization");
let apiRootEndPoint = organization.api_root_endpoint;
let options = {
  url: `${apiRootEndPoint}/settings/orgvariables/${placeholder}`,
  method: 'GET',
  url_query: [
    {
      key: 'organization_id',
      value: organization.organization_id
    }
  ],
  connection_link_name: 'your_connection_link_name'
};
ZFAPPS.request(options).then(function (value) {
  // console.log(value)
}).catch(function (err) {
  // console.error(err)
});
let placeholder = 'vl__abc_field';
let data = { value: 'abc' };
let { organization } = await ZFAPPS.get("organization");
let apiRootEndPoint = organization.api_root_endpoint;
let options = {
  url: `${apiRootEndPoint}/settings/orgvariables/${placeholder}`,
  method: 'PUT',
  url_query: [
    {
      key: 'organization_id',
      value: organization.organization_id
    }
  ],
  body: {
    mode: 'formdata',
    formdata: [
      {
        key: 'JSONString',
        value: JSON.stringify(data)
      }
    ]
  },
  connection_link_name: 'your_connection_link_name'
};
ZFAPPS.request(options).then(function (value) {
  // console.log(value)
}).catch(function (err) {
  // console.error(err)
});

You can use the below script to fetch and update the global field using a deluge script:

placeholder = 'vl__abc_field';
organizationID = organization.get("organization_id");
apiRootEndPoint = organization.get("api_root_endpoint");
response = invokeurl
[
	url: apiRootEndPoint +'/settings/orgvariables/' + placeholder + '?organization_id=' + organizationID
	type: GET
    connection: 'your_connection_link_name'
];
info response;
placeholder = "vl__abc_field";
organizationID = organization.get("organization_id");
apiRootEndPoint = organization.get("api_root_endpoint");
data = Map();
data.put("value", "abc");

params = Map();
params.put("JSONString", data);


response = invokeurl
[
    url: apiRootEndPoint +"/settings/orgvariables/" + placeholder + "?organization_id=" + organizationID
    type: PUT
    parameters: params
    connection: "your_connection_link_name"
];
info response;

Install Actions

Sometimes, you might want your extension to run a customized script immediately after the installation or before uninstalling the extension. For example, you might want to create sample data, or send an email notification about the installation to an external system, or kickoff a batch operation to populate a new field across a large set of data. This cannot be done with the help of custom functions or workflow rules. Instead, you use Install Actions in the Zoho Books Developer Portal to do this.

On Installation

The installation script allows the extension to run a basic function whenever a user installs or updates the extension. To add an installation script to your extension:

On Installation tab

Points to remember:

On Uninstallation

The uninstallation script allows the extension to run a basic function when a user uninstalls the extension. To add an uninstallation script to your extension:

On Uninstallation tab

Points to remember:


Was this document helpful?
Yes
No
Thank you for your feedback!
Want a feature?
Suggest
Switch to smart accounting software. Switch to Zoho Books.   Start my free 14-day trial Explore Demo Account

Books

Online accounting software
for small businesses.