Variables

Detailed Overview of Variables in Zoho People Extension

1. Read/Write: This permission makes the variable visible in the users organization, where they can view and update its value. However, if you change the value in the developer console, those updates cannot be pushed through an upgrade and won’t reflect in the users organization. Such changes apply only to new sign-ups. During future extension upgrades, you can update all other details of the variable except its value.
   
   
2. Read Only: A Read Only variable is visible but cannot be modified in the users organization, and its value does not change upon upgrades from the developer console. However, except the variable value of the other variable data can be updated during the extension in the next version upgrade. 
   
   
3. Hidden: The Hidden variable is visible in the Developer Console for developers to manage, but it remains hidden for the end users within the user's organization. Any changes to the values of the variable in the developer console can not be upgraded to the users account. However, the changes will reflect on new sign-ups and except the variable value the other data of the variable can be updated during the extension in the next version upgrade. 
   
   
4. System: A System variable is visible in the Developer Console for developers to manage and remains hidden for the end users in the user's organization. Any changes to the values of the variable in the user's organization is restricted for this permission type. Changes made to the variable value in the developer console are reflected to the users account during upgrade. 
   

1. In the users organization the value of the variables can be updated via API for all the categories except the SYSTEM Permission variable.
   
2. HIDDEN and SYSTEM permission variables cannot be used as merge fields in other components.
3. Except the SYSTEM permission variable all other permission variables can have its own On Change Script function.
   

Variables can be used in the following contexts

1. Custom Functions - Dynamically access values in code logic and calculations.
2. Email Templates - Personalize messages using pre-defined variable values.
3. Record Templates - Inject data dynamically when creating or displaying records.
4. Mail Merge Templates - Use variables in document generation for seamless data population.
5. API Integrations - Access variable values through APIs for external systems or integrations.
6. On Change Script Functions - A separate custom function support. Each variable can have its own On Change script function which will be triggered when the variable value is updated.

Variables Property Packaging

On Change Script Function

In the Zoho People Extension Developer Console, developers can define Change Scripts to handle logic that should be executed whenever a global variable’s value is updated in the user's organization.

How It Works

Script Setup

1. Go to the Field Value - On Change tab in your desired variable configuration.
2. Click Create Script.
3. In the editor, use the variableMap object to access the previous and current values.

Sample Syntax

1. oldValue - The value of the variable before the change.
2. newValue - The value after the update.
   

You can use these values to build your own logic.

For example:

if (oldVal != newVal)

{

   // Run custom logic here

   info "Variable updated from " + oldVal + " to " + newVal;

}

1. Recalculate dependent fields whenever a configured variable is updated.
2. Notify users or admins when important settings are changed.
3. Reset values or workflows when thresholds are modified.
4. Update API calls or integrations that rely on global settings.

Installation Setup

1. When the user installs the extension and if the extension contains any variables, the Authorize Variables tab will be displayed on the installation page.
   
   
   
   
2. In this tab, variables with Read/Write and Read-Only permission types are visible. The Read-Only variables are not editable, while the user can configure the Read/Write variables directly on the installation page.
3. If the user skips this step during installation, they can later edit the variable values either through the extension configuration slider or from the Variables tab inside the Developer Space.
   

Changes and Impacts

Adding a new variable

1. Introducing a new global variable through an upgrade will not interfere with any existing configurations in users organization.
2. The variable becomes available for use in new workflows, scripts, or field configurations.
3. Existing features and user-defined processes will continue to function the same.
4. You can treat it as a clean addition, no retroactive effect on current setups.
   

Updating an existing variable 

1. Updating the description or name of a variable has no impact on existing references or functionality.
2. These are purely cosmetic or informational changes.
   

1. Hidden/System variables may no longer appear in configuration UIs.
   
2. End users may lose the ability to edit values.
   

1. Any script, workflow, or process depending on the old value may behave differently.
2. Developers can use Change Scripts to programmatically handle these transitions.
3. However, end users must manually update their custom logic to adapt to the new value.
   

Even a small value change could affect thresholds, conditions, or calculations relying on the old setting.

Deleting a variable

Deleting a variable is a destructive change. It can have lasting effects on your users data and configurations. Please consider the consequences carefully before proceeding, and only move forward if absolutely necessary.

1. Any process, field, script, or workflow that references the deleted variable will break.
2. This may cause runtime errors, missing values, or logic failures across the extension.
3. There is no automatic fallback or replacement unless explicitly coded.
   

Removing a variable can disrupt live user environments. Only delete variables that are obsolete, unused, and have no downstream dependencies and preferably during a major version upgrade with clear release notes.