JavaScript Helper Functions

Automation Rules include a library of Helper Functions that help to solve common tasks in JavaScript code.

Loading Helper Functions

Helper Functions are not available by default. They need to be loaded into JavaScript rule.
There are several ways to load them:

const utils = require("utils");

const utils = require("utils");

return utils.createResource("Task", {
  Project: { Id: args.Current.Project.Id },
  UserStory: {Id: args.ResourceId},
  Name: "Created Automatically"
});

const {createResource, updateResource, addDays} = require("utils");

const { createResource } = require("utils");

return createResource("Task", {
  Project: { Id: args.Current.Project.Id },
  UserStory: { Id: args.ResourceId },
  Name: "Created Automatically"
});

The List of Helper Functions

Commands

Command for creating a new resource:
createResource(resourceType: string, fields?: ResourceFields)

const utils = require("utils");

return utils.createResource("UserStory", {
  Project: { Id: args.Current.Project.Id },
  Feature: { Id: args.ResourceId },
  Name: "Created Automatically"
});

Command for updating an existing resource:
updateResource(resourceType: string, resourceId: number, fields: ResourceFields)

const utils = require("utils");

return utils.updateResource("Feature", args.ResourceId, { Release: { id: 100 } });

Command for deleting an existing resource:
deleteResource(resourceType: string, resourceId: number)

const utils = require("utils");

return utils.deleteResource("TeamAssignment", 50);

Command for moving an existing resource to another state:
moveToState(resourceType: string, resourceId: number, stateKind: 'Initial' | 'Planned' | 'Final')

const utils = require("utils");

return utils.moveToState("Epic", args.ResourceId, "Final");

Command for moving an existing resource to another state by its name:
moveToStateByName(resourceType: string, resourceId: number, stateKind: string)

const utils = require("utils");

return utils.moveToStateByName("UserStory", args.ResourceId, "In Progress");

Command for sending HTTP request:
sendHttpRequest(url: string, options?: { method?: 'POST' | 'PUT' | 'DELETE', body?: any, headers?: { [key: string]: string } })

const utils = require("utils");

return utils.sendHttpRequest("https://hooks.slack.com/services/...", {
  body: { 
    text: `A new Bug with id # ${args.ResourceId} was added` 
  }
});

const utils = require("utils");

return utils.sendHttpRequest("https://webhook.site/...",
  {
    method: "POST",
    body: "Hello", 
    headers: {"additional-info": "test message" }
  }
);

Working with dates

Functions that add some period to a date

Add the specified number of milliseconds to the given date:
addMilliseconds(date: DateLike, milliseconds: number): Date

Add the specified number of seconds to the given date:
addSeconds(date: DateLike, seconds: number): Date

Add the specified number of minutes to the given date:
addMinutes(date: DateLike, minutes: number): Date

Add the specified number of hours to the given date:
addHours(date: DateLike, hours: number): Date

Add the specified number of days to the given date:
addDays(date: DateLike, days: number): Date

Add the specified number of weeks to the given date:
addWeeks(date: DateLike, weeks: number): Date

Add the specified number of full months to the given date:
addMonths(date: DateLike, months: number): Date

Add the specified number of full years to the given date:
addYears(date: DateLike, years: number): Date

Here is an example of calculating a Date basing on the other Date:

const utils = require("utils");

const kickStartDate = new Date("2019-03-15T12:00:00Z");
const demoDate = utils.addDays(kickStartDate, 14);

console.log(kickStartDate); // 2019-03-15T12:00:00Z
console.log(demoDate); // 2019-03-29T12:00:00Z

Functions that calculate difference between the given dates

The number of milliseconds between the given dates:
differenceInMilliseconds(date: DateLike, deduction: DateLike): number

The number of seconds between the given dates.
The result is truncated to zero decimal places by default. Pass "true" as the third argument to get
floating point result:
differenceInSeconds(date: DateLike, deduction: DateLike, asFloat?: boolean): number

The number of minutes between the given dates:
differenceInMinutes(date: DateLike, deduction: DateLike, asFloat?: boolean): number

The number of hours between the given dates:
differenceInHours(date: DateLike, deduction: DateLike, asFloat?: boolean): number

The number of days between the given dates:
differenceInDays(date: DateLike, deduction: DateLike, asFloat?: boolean): number

The number of weeks between the given dates:
differenceInWeeks(date: DateLike, deduction: DateLike, asFloat?: boolean): number

The number of months between the given dates:
differenceInMonths(date: DateLike, deduction: DateLike, asFloat?: boolean): number

The number of years between the given dates:
differenceInYears(date: DateLike, deduction: DateLike, asFloat?: boolean): number

Checks if the given dates are equal and returns true or false:
equalDates(date: DateLike, other: DateLike): boolean

const utils = require("utils");

const plannedFeatureStartDate = "2019-04-01T00:00:00Z";
const plannedFeatureEndDate = "2019-05-15T00:00:00Z";
const featureDurationInWeeks = utils.differenceInWeeks(plannedFeatureEndDate, plannedFeatureStartDate, true);

console.log(featureDurationInWeeks); // 6.285714285714286

Working with numbers and strings

Round function

Rounds to a specified number of decimal places:
round(value: number, precision?: number): number

const utils = require("utils");

const spentHours = args.Current.TimeSpent; // 11
const spentDays = spentHours / 8;  // 1.375
const roundedSpentDays = utils.round(spentDays, 2);

console.log(roundedSpentDays); // 1.38

Truncate function

Truncates string if it's longer than the given length. The last characters of the truncated string are replaced with "...":
truncate(text: string, length?: number): string

const utils = require("utils");

const name = args.Current.Name;
const truncatedName = utils.truncate(name, 50);

console.log(truncatedName); // Lorem ipsum dolor sit amet, consectetur adipisc...