Sample Custom Scripts for Form Rules

Tabulated below are some of the sample scripts that can be performed as actions in request/problem/change/release Form Rules.

Requirement

Script

Examples

Remarks

Alert (Requests, Problems, Changes & Releases)

await CS.alert(“message”);

await CS.alert("Alert message");

 

Confirm (Requests, Problems, Changes & Releases)

var confirm = await CS.confirm(“message”);

if(confirm){

}

else{

}

var confirm = await CS.confirm(“Do you want to proceed");

if(confirm){

}

else{

}

Properties
1. width [optional] - defines a custom width (in pixels) for the dialog.

Note : Ensure that the width (if needed) is provided in an object along with the message. Refer CS.alert.

Page Redirect (Requests, Problems, Changes & Releases)

await CS.alert(options);

Page redirection for internal links
await CS.alert({
     title: "Redirection Alert",
     message: "You are being redirected to Request list view",
     button_options: {
         label: "Proceed",
         redirectTo: "/ui/requests"
     }
});
  
Page redirection for external links
await CS.alert({
     title: "Redirection Alert",
     message: "You are being redirected to an external website in a new tab",
     button_options: {
         label: "Proceed",
         redirectTo: "https://www.zoho.com",
         target: "_blank"
     }
});

Properties
1. title, message - defines custom text content to display in the alert’s title and message part.
2. button_options - defines redirection details.

  • label - defines the alert button’s label content.

  • redirectTo - defines URL for navigation. When redirecting to external links, ensure that the redirectTo property value contains the full URL, including the protocol. For example, using “www.zoho.com” is invalid and hence use “https://www.zoho.com”.

  • target [optional] - If left undefined, the redirection will take place in the current tab. Setting the value to “_blank” will open the specified URL in a new tab.

3. width [optional] - defines a custom width (in pixels) for the dialog.

Get API (Requests, Problems, Changes & Releases)

await CS.API.get(“url”,”input_data”);

await CS.API.get('/api/v3/requests/technician/',{list_info:{search_criteria:{field:'roles.name',condition:'is',value:'SDAdmin'}}});

To make internal API calls

Hide Fields (Requests, Problems, Changes & Releases)

CS.hideFields(fields)

CS.hideFields(["level","priority","urgency"]);

 

Show Fields (Requests, Problems, Changes & Releases)

CS.showFields(fields)

CS.showFields(["level","priority","urgency"])

 

Disable Fields (Requests, Problems, Changes & Releases)

CS.disableFields(fields)

CS.disableFields(["level","priority","urgency"]);

 

Enable Fields (Requests, Problems, Changes & Releases)

CS.enableFields(fields)

CS.enableFields(["level","priority","urgency"]);

 

Mandate Fields (Requests, Problems, Changes & Releases)

CS.mandateFields(fields)

CS.mandateFields(["level","priority","urgency"]);

 

Non-Mandate Fields (Requests, Problems, Changes & Releases)

CS.nonMandateFields(fields)

CS.nonMandateFields(["level","priority","urgency"]);

 

Add Options (Requests, Problems, Changes & Releases)

CS.addOptions(field,options)

CS.addOptions("urgency",["100000000000007061","100000000000007067"]);

Ensure that they are Pick Type fields and an array.

Remove Options (Requests, Problems, Changes & Releases)

CS.removeOptions(field,options)

CS.removeOptions("status",["100000000000007061","100000000000007067"]);

Same as above.

Reset Options (Requests, Problems, Changes & Releases)

CS.resetOptions(fields);

CS.resetOptions(["priority","impact"]);

Same as above.

Clear Options (Requests, Problems, Changes & Releases)

CS.clearOptions(fields)

  • CS.clearOptions(["urgency"]);

  • CS.clearOptions(["urgency","priority"]);

Same as above.

Set a Field Value (Requests, Problems, Changes & Releases)

CS.setValue(field,value)

CS.setValue("subject","This is a test subject");

CS.setValue("urgency",{"name":"High","deleted":false,"id":"100000000000007061"});

CS.setValue("due_by_date", Date.now());

 

Get Field Values (Requests, Problems, Changes & Releases)

await CS.getValue(field)

var status=CS.getValue("status");

var created_date=CS.getValue("created_date");   

 

To retain the existing field values and store them in a variable.

Clear Field Values (Requests, Problems, Changes & Releases)

CS.clearValue(fieldnames)

CS.clearValue(["priority","impact"]);

 

Set Criteria (Requests, Problems, Changes & Releases)

CS.setCriteria(<field_name>,<criteria>);

 

 

Set Tasks (Requests)

CS.setTasks(tasksArray)

CS.setTasks([{"id":"100000000000033123","value":"Task 1"},{"id":"100000000000033125","value":"Task 2"}]);

Applicable only for request templates configured with tasks.

Unset Tasks (Requests)

CS.unsetTasks(tasks)

CS.unsetTasks([{"id":"100000000000033123","value":"Task 1"},{"id":"100000000000033125","value":"Task 2"}]);

Same as above.

Show Tasks (Requests)

CS.showTasks(tasks)

CS.showTasks([{"id":"100000000000033123","value":"Task 1"},{"id":"100000000000033125","value":"Task 2"}]);

Same as above.

Hide Tasks (Requests)

CS.hideTasks(tasks)

CS.hideTasks([{"id":"100000000000033123","value":"Task 1"},{"id":"100000000000033125","value":"Task 2"}]);

Same as above.

Show Resources (Requests)

CS.showResources(resources)

CS.showResources(["resources.res_100000000000030756"]);

Applicable only for request templates configured with resource questions.

Hide Resources (Requests)

CS.hideResources(resources)

CS.hideResources(["resources.res_100000000000030756"]);

Same as above.

Set Date Constraint (Requests, Problems, Changes & Releases)

CS.setDateConstraint(<field_names>,<constraint>);

const current_time = new Date().getTime();

var thirty_days = 30*24*60*60*1000;

CS.setDateConstraint("scheduled_start_time",{minDate:current_time,maxDate:current_time+thirty_days});

Set constraints for date fields

Show Field Errors (Requests, Problems, Changes & Releases)

CS.showErrors({

field_name: <field_name>,

message: <message>,

error_key: <unique_error_identifier>

});

 errors.push({

   "field_name": "scheduled_end_time",

   "message": "Duration of the Change scheduled must not exceed 30 days",

   "error_key": "scheduled_end_time_ERR1"

  });

  CS.showErrors(errors);

Display field specific error messages beneath the fields.

Note: Using CS.abort() to abort form submission after CS.showErrors() is unnecessary, as the form is automatically aborted after CS.showErrors().

Clear Field Errors (Requests, Problems, Changes & Releases)

CS.clearErrors({
    field_name: <field_name>,
    error_key: <unique_error_identifier>
});

  

Clear field specific error messages created with Show Field Error.

Get Local Data (Requests, Problems, Changes & Releases)

CS.dataStore.get(name)

CS.dataStore.get(“Technician");

Uses the form's local data storage which the other custom scripts, configured for the same form, can access and return the data mentioned in the parameter. If the parameter is not passed, all the data stored is returned

Set Local Data (Requests, Problems, Changes & Releases)

CS.dataStore.set(name,value)

CS.dataStore.set(“Technician",”John”);

Uses the form’s local data storage which the other custom scripts, configured for the same form, can access, and assign the data to the key mentioned in the parameter. By default, the dataStore contains the logged-in user’s information such as email, id, first & last name, photo url, etc which can be accessed by CS.dataStore.get(“CS_context”).

On Field Change (Requests, Problems, Changes & Releases)

await CS.onFieldChange(<field_name>,<cbk>);

  

Triggers actions on field change in forms

On Form Submit (Requests, Problems, Changes & Releases)

CS.onFormSubmit(<cbk>);

  

Triggers actions on submitting forms

Abort (Requests, Problems, Changes & Releases)

CS.abort(<value>);

  

Aborts form submission

 

Please note that all the given scripts should end with CS.end();


Guidelines for Using CS.end() statement:

When writing custom scripts, follow these guidelines to ensure smooth execution and proper completion handling:

1. Mandatory Completion Statement: Always conclude your script with a single CS.end() call to ensure all actions are processed properly.

2. Event Listener Completion: When using event listeners (like CS.onFieldChange or CS.onFormSubmit), include a single CS.end() within each callback function to mar¸k the end of the actions you want to perform for that event.

3. Single Use of CS.end(): Only use CS.end() once per section of the script, whether it’s at the end of the main script or within an event listener. Calling it multiple times in the same section is not recommended, as it can lead to unexpected results. Make sure all actions you want to complete are listed before your single CS.end() call.

4. Avoid Additional Statements After CS.end(): Although CS.end() doesn’t function as a return statement, it’s best not to place any additional actions after CS.end(). Doing so can cause unintended behaviors and makes the script harder to follow.

Example Script

// Set value for the impact_details field

CS.setValue('impact_details', "Please provide additional impact details here");


// Event listener for category field change

await CS.onFieldChange("category", () => {

   CS.setValue('description', "Default category has been updated");

   CS.end(); // Single completion statement in the callback

});


// Event listener for form submission

CS.onFormSubmit(async () => {

   const subject = await CS.getValue('subject') || "Problem occurred";

   CS.setValue('subject', "Ticket ID - " + Date.now() + ' : ' + subject);

   CS.end(); // Single completion statement in the callback

});


// Single completion statement at the end of the script

CS.end();

 

In this example, CS.end() is used once at the end of each event listener and once at the end of the main script. This ensures all specified actions are completed as intended. Avoid placing any further actions after CS.end() within the same section to prevent unwanted effects.

 

Sample Custom Scripts for Form Rules (Requests)

Example 1: To check if onboarding date is 10 days after the current date

var on_date = await CS.getValue("udf_fields.udf_date1");

var curr_date = Date.now();

var diff =  Math.round((on_date.value-curr_date)/(1000*60*60*24));

if(diff<10){

      await CS.alert("OnBoarding process will take minimum 10 days time");

      CS.clearValue('udf_fields.udf_date1');

}

CS.end();

 

Example 2: To abort form submit when the category satisfies a particular condition.

async function checkValueandAbort(){
	var category = await CS.getValue('category');
	if(category != null && category.name == 'Desktop Hardware')
	{
		await CS.alert('Aborting Form Submit since category is Desktop Hardware');
		CS.abort();
		CS.end();
	}
	else
	{
		CS.end();
	}
}
CS.onFormSubmit(function(){
	checkValueandAbort();
});
CS.end();

 

Example 3: To set subject as a combination of category and subcategory 

var cat = await CS.getValue("category");

var subcat = await CS.getValue("subcategory");

if(cat !=null && subcat!=null){

var sub = cat.name + subcat.name;
CS.setValue("subject",sub);
}

CS.end();

 

 

 

Sample Custom Scripts for Form Rules (Changes)

 

Example 1: Abort Form Submission Conditionally

async function checkAndAbort(){

 var stage = await CS.getValue("stage");

 var status = await CS.getValue("status");

 var back_out = await CS.getValue("back_out_plan");

 var sch_start = await CS.getValue("scheduled_start_time");

 var description = await CS.getValue("description");

 var change_risk = await CS.getValue("risk");

 if(((stage.internal_name = "planning" && status.internal_name == "planning_in_progress") 

&& !(back_out.back_out_plan_description != null && sch_start != null && description != null 

&& change_risk != null && change_risk.id != null))){

  await CS.alert("Please enter value in following Back out Description, Scheduled Start, Description, Change Risk");

  CS.abort();

 }

 CS.end();

}

CS.onFormSubmit(function(){

 checkAndAbort();

});

CS.end();

 

 

Example 2: Show Error on field if the scheduled range exceeds 30 days

 

var errors = [];

var endTime = await CS.getValue("scheduled_end_time");

var startTime = await CS.getValue("scheduled_start_time");

if(endTime != null && startTime != null){

 if(Math.round((endTime.value-startTime.value)/(1000*60*60*24)) > 30){

  errors.push({

   "field_name": "scheduled_end_time",

   "message": "Duration of the Change scheduled must not exceed 30 days",

   "error_key": "scheduled_end_time_ERR1"

  });

  CS.showErrors(errors);

 }

}

CS.end();

 

 

Example 3: Scheduled Start/End date selection restriction

 

var created_time = await CS.getValue("created_time");

var thirty_days = 30*24*60*60*1000;

if(created_time != null){

 CS.setDateConstraint("scheduled_start_time",{minDate:created_time.value,maxDate:parseInt(created_time.value)+thirty_days});

 CS.setDateConstraint("scheduled_end_time",{minDate:created_time.value,maxDate:parseInt(created_time.value)+thirty_days+thirty_days});

}else{

 const current_time = new Date().getTime();

 CS.setDateConstraint("scheduled_start_time",{minDate:current_time,maxDate:current_time+thirty_days});

 CS.setDateConstraint("scheduled_end_time",{minDate:current_time,maxDate:current_time+thirty_days+thirty_days});

}

await CS.onFieldChange("scheduled_start_time",scheduleStartConstraints);

await CS.onFieldChange("created_time",createdTimeConstraints);

async function scheduleStartConstraints(){

 var start_time = await CS.getValue("scheduled_start_time");

 if(start_time != null){

  CS.setDateConstraint("scheduled_end_time",{minDate:start_time.value,maxDate:parseInt(start_time.value)+thirty_days});

 }

 CS.end();

};

async function createdTimeConstraints(){

 var start_time = await CS.getValue("scheduled_start_time");

 created_time = await CS.getValue("created_time");

 if(created_time != null){

  CS.setDateConstraint("scheduled_start_time",{minDate:created_time.value,maxDate:parseInt(created_time.value)+thirty_days});

  CS.setDateConstraint("scheduled_end_time",{minDate:created_time.value,maxDate:parseInt(created_time.value)+thirty_days+thirty_days});

  if(start_time !=null){

   CS.setDateConstraint("scheduled_end_time",{minDate:start_time.value,maxDate:parseInt(start_time.value)+thirty_days});

  }

 }

 CS.end();

}

CS.end();

 

Sample Custom Scripts for Form Rules (Release)

Example 1: Assign Release Engineer Role 

This script executes an internal API call to assign a Technician with SDAdmin role to the Release Engineer.

var category = await CS.getValue("category");

var impact = await CS.getValue("impact");

var site = await CS.getValue("site");

if(category != null && category.name == "Desktop Hardware" && impact != null && impact.name == "AffectsR Business"){

var tech_data = await CS.API.get("/api/v3/releases/release_engineer/",{list_info:{search_criteria:[{field:"sites",condition:"like",value:{"id":site.id}},{field:"roles.name",condition:"is",value:"SDAdmin",logical_operator:"and"}]}});

tech_data = JSON.parse(tech_data);

var tech = tech_data.release_engineer[0];

CS.setValue("release_engineer",tech);

}

CS.end();

Example 2: Set Release Title 

This script sets the release title based on the Category and Subcategory fields

var cat =  await CS.getValue("category");

var subcat = await CS.getValue("subcategory");

if(cat != null && subcat != null){

var sub = cat.name +" "+ subcat.name;

CS.setValue("title",sub);

}

CS.end();

Example 3: Confirm Date Validation 

This script prompts the user for confirmation after performing date validation.

var endTime = await CS.getValue("scheduled_end_time");

var startTime = await CS.getValue("scheduled_start_time");

if(endTime != null && startTime != null){

var diff = Math.round((endTime.value-startTime.value)/(1000*60*60*24));

if(diff < 3){

var confirm= await CS.confirm("Scheduled end should not be within 3 days. Do you want to continue?");

if(!confirm){

CS.clearValue("scheduled_end_time");

CS.abort();

}

}

}

CS.end();