The Utilities module contains useful utility functions commonly used in other modules and project code.

Dependencies

The Utilities module is dependent on the following modules:

• Project Context

math

utilities.math contains mathematical utility functions

getRandomInt

Returns a random integer between a minimum and maximum value (inclusive).

Parameters:

• min (number): The minimum value (inclusive).

• max (number): The maximum value (inclusive).

Returns: A random integer between the minimum and maximum value (inclusive).

multiagent

utilities.multiagent contains utility functions for working with Orbita multiagent objects

randomize

Randomizes the content of a multiagent object by looking for double horizontal rule tags as a separator in the raw multiagent entries, choosing a random response from the available options for each entry, and updating the multiagent with the randomized content.

Parameters:

• rawMultiagent (object): The raw multiagent array.

• multiagent (object): The Orbita multiagent object.

• msg (object, optional): The Node-RED message object for the Orbita request.

Returns: The Orbita multiagent object with the response randomized.

getEmpty

Returns an empty Orbita multiagent object.

Parameters: None

Returns: An empty Orbita multiagent object.

string

utilities.string contains utility functions for working with strings

normalize

Formats a string to normalize it for comparison purposes.

Parameters:

• str (string): The string to normalize.

Returns: The string in lowercase with leading and trailing whitespace trimmed.

removeExcessWhitespace

Collapses any group of multiple whitespace characters in the string down to a single space.

Parameters:

• str (string): The string to clean.

Returns: The string with excess whitespace collapsed.

removeLinkTags

Strips any link tags from the string.

Parameters:

• str (string): The string to clean.

Returns: The string with link tags removed.

stripNewLines

Strips new line characters from the provided string.

Parameters:

• str (string): The string to clean.

Returns: The string stripped of new line characters.

hyphenate

Hyphenates the provided string by replacing spaces with hyphens.

Parameters:

• str (string): The string to hyphenate..

Returns: The hyphenated string.

capitalize

Will uppercase the first character of the provided string.

Parameters:

• str (string): The string to capitalize.

Returns: The capitalized string.

camelize

Will take a series of words and reduce it to a single camelcase word.

Parameters:

• str (string): The string to camelize.

Returns: The camelized string.

isString

Indicates if the provided value is a string or not.

Parameters:

• str (string): The value to check.

Returns: True if the value is a string, false otherwise.

input

utilities.input contains utility functions for cleaning and validating input

phone.clean

Strips a phone number down to just its digits.

Parameters:

• phoneNumber (string): The phone number to clean.

Returns: A string containing only the digits from the phone number.

phone.isValid

Determines the validity of the provided phone number (after cleaning it first).

Parameters:

• phoneNumber (string): The phone number to validate.

Returns: True if the phone number is valid, false otherwise.

email.isValid

Determines the validity of the provided email address.

Parameters:

• email (string): The email address to validate.

Returns: True if the email address is valid, false otherwise.

session

utilities.session contains utility functions for working with Orbita session

getSessionId

Gets the Orbita session ID from a message object.

Parameters:

• msg (object): The Node-RED message object for an Orbita request.

Returns: The Orbita session ID for the request.

isChatSession

Indicates if the provided message object originated from a chat session.

Parameters:

• msg (object): The Node-RED message object for an Orbita request.

Returns: True if the message object originated from a chat session, false otherwise.

object

utilities.object contains utility functions for working with objects

deepFreeze

Freezes an object entirely by recursively freezing all properties.

Parameters:

• obj (object): The object to freeze.

Returns: The frozen object.

clone

An alias for Lodash's clone method.

get

An alias for Lodash's get method.

set

An alias for Lodash’s set method.

unset

An alias for Lodash’s unset method.

isPureObject

Indicates if the specified object is a pure object (and not an array, function, or null).

Parameters:

• obj (object): The object to check.

Returns: True if the object is a pure object, false otherwise.

merge

An alias for Lodash’s merge method.

replaceTokens

Replaces tokens from the provided mapping in any string properties at any level in the object.

Parameters:

• obj (object): The object to replace tokens in.

• tokenMapping (object): A token mapping in the form of an object where each key is the token to replace and the value is what the token should be replaced with.

Returns: Nothing, the replacements are performed in-place.

mongo

utilities.mongo contains utility functions related to MongoDB

isValidObjectId

Checks whether or not a provided string is a valid Mongo Object ID.

Parameters:

• str (string): The ID string validate.

Returns: True if the string is a valid Mongo Object ID, false otherwise.

orbita

utilities.orbita contains utility functions that are very specific to Orbita

parseVersion

Parses an Orbita version string

Parameters:

• version (string): The version string. The expected format is “major.minor.patch” or “major.minor.patch-build”.

Returns: An object with the following properties:

• major (int): The parsed major version.

• minor (int): The parsed minor version.

• patch (int): The parsed patch version.

• build (int): The parsed build number (if any).

• isAtLeast (function): This function takes in a version to compare the parsed version to. Returns true if the parsed version is at least the same as or a later version than the specified target version, or false otherwise.

redis

utilities.redis contains functions for writing to and reading from the Redis cache

get

Gets an entry from the Redis cache by key.

Parameters:

• key (string): The key of the entry to retrieve

Returns: A promise that will resolve with the requested entry (or undefined if it does not exist in the cache)

set

Sets an entry in the Redis cache with the specified key and value.

Parameters:

• key (string): The key of the entry to set

• value (any): The value for the entry

Returns: A promise that will resolve when the value has been written to the cache

clear

Gets an entry from the Redis with the specified key by setting it to undefined.

Parameters:

• key (string): The key of the entry to clear

Returns: A promise that will resolve when the value has been cleared from the cache

data

utilities.data contains utility functions for data transformations and manipulations

map

Maps data from a source object to a new format using the provided mapping.

Parameters:

• mapping (object): A mapping object where the keys represent the property name (or path using dot syntax) on the new mapped data and the values are strings indicating where data should be pulled from in the source data. The following syntaxes are current recognized:

  • A standard property name, which will be mapped directly.

  • A property path using dot syntax, which will be followed to the value to map, or return undefined if no property exists at the path. This syntax should be used for accessing a particular value in an array, for example: arrayProperty.3 for primitive values, or arrayProperty.0.objectProperty for a property from an object in an array.

  • A conditional array expression, which will look for the first object in the array matching the condition, and return a specified (top-level only currently) property from that object. For example: arrayProperty[isActive=true].value or arrayProperty[label='some label'].value. The only acceptable condition values at the moment are true, false, or a string enclosed in single quotes.

• sourceData (object): The source data to map from.

Returns: The mapped data.

backendRequest

A helper function for making requests to the Orbita backend.

Parameters:

• path (string): The endpoint path.

• method (string): The HTTP method for the request.

• authToken (string): A valid authentication token (see getAuthToken).

• body (object, optional): The JSON body for the request.

Returns: A promise that will resolve with the status code and body of the response when the request has been fulfilled.

httpRequest

A helper function for making generic HTTP requests.

Parameters:

• path (string): The endpoint path.

• method (string): The HTTP method for the request.

• header (object, optional): The headers for the request.

• body (object, optional): The JSON body for the request.

Returns: A promise that will resolve with the status code and body of the response when the request has been fulfilled.

orbitaAPI

utilities.orbitaAPI contains wrappers for Orbita API endpoints

getAuthToken

Retrieves an Orbita authentication token for the current environment using the provided credentials

Parameters:

• serviceAccount (object): A credentials object with the following properties

  • username: The service account user’s username

  • password: The password for the service account

Returns: A promise that will resolve with an authentication token for the provided service account.

verify

Verifies the validity of a provided authentication token.

Parameters:

• authToken (string): The authentication token to verify (see getAuthToken).

Returns: A promise that will resolve with the verification response from Orbita.

user

utilities.orbitaAPI.user contains wrappers for Orbita user API endpoints.

getById

Retrieves an Orbita user by their ID.

Parameters:

• userId (string): The ID of the user.

• authToken (string): A valid authentication token (see getAuthToken).

Returns: A promise that will resolve with the Orbita user record.

schema

utilities.orbitaAPI.schema contains wrappers for Orbita schema API endpoints.

getByKey

Retrieves an Orbita schema by type and key.

Parameters:

• schemaType (string): The type of the schema. Valid values are “content”, “dynamic”, or “integrate”.

• schemaKey (string): The key of the schema.

• authToken (string): A valid authentication token (see getAuthToken).

Returns: A promise that will resolve with the Orbita schema.

getSchemaFields

Returns a simplified list of the fields of the specified Orbita schema.

Parameters:

• schemaType (string): The type of the schema. Valid values are “content”, “dynamic”, or “integrate”.

• schemaKey (string): The key of the schema.

• authToken (string): A valid authentication token (see getAuthToken).

Returns: A promise that will resolve with a simplified list of the schema fields (key and type only).

content

utilities.orbitaAPI.content contains wrappers for Orbita content API endpoints.

getAll

Retrieves all Orbita content records by type and schema key.

Parameters:

• type (string): The content type. Valid values are “content”, “dynamic”, or “integrate”.

• schemaKey (string): The key of the schema.

• authToken (string): A valid authentication token (see getAuthToken).

Returns: A promise that will resolve with all the content records for the specified schema.

getById

Retrieves an Orbita content record by type, schema key and id.

Parameters:

• type (string): The content type. Valid values are “content”, “dynamic”, or “integrate”.

• schemaKey (string): The key of the schema.

• id (string): The id of the content record.

• authToken (string): A valid authentication token (see getAuthToken).

Returns: A promise that will resolve with the content record.

getOneByProperty

Retrieves an Orbita content record by type, schema key, property and value.

Parameters:

• type (string): The content type. Valid values are “content”, “dynamic”, or “integrate”.

• schemaKey (string): The key of the schema.

• property (string): The property to check.

• value (string): The specified value of the property.

• authToken (string): A valid authentication token (see getAuthToken).

Returns: A promise that will resolve with the first content record with the specified property set to the specified value, or null if no results were found.

create

Creates an Orbita content record with the specified type, schema key, and data.

Parameters:

• type (string): The content type. Valid values are “content”, “dynamic”, or “integrate”.

• schemaKey (string): The key of the schema.

• data (object): The data for the record.

• authToken (string): A valid authentication token (see getAuthToken).

Returns: A promise that will resolve with the created content record.

update

Updates an Orbita content record with the specified type, schema key, and id with the provided data.

Parameters:

• type (string): The content type. Valid values are “content”, “dynamic”, or “integrate”.

• schemaKey (string): The key of the schema.

• id (string): The id of the content record.

• data (object): The updated data for the record.

• authToken (string): A valid authentication token (see getAuthToken).

Returns: A promise that will resolve with the updated content record.

slotType

utilities.orbitaAPI.slotType contains wrappers for Orbita slot type API endpoints.

get

Retrieves an Orbita slot type by name.

Parameters:

• name (string): The name of the slot type.

• authToken (string): A valid authentication token (see getAuthToken).

Returns: A promise that will resolve with the slot type.

create

Creates an Orbita slot type.

Parameters:

• name (string): The name of the slot type.

• items (array): An array of items in the following format:

  • value (string): The primary value

  • synonyms (array of strings): Any synonyms for the primary value.

• authToken (string): A valid authentication token (see getAuthToken).

Returns: A promise that will resolve with the newly created slot type record.

create

Updates an Orbita slot type.

Parameters:

• id (string): The ID of the slot type to update.

• name (string): The name of the slot type.

• items (array): An array of items in the following format:

  • value (string): The primary value

  • synonyms (array of strings): Any synonyms for the primary value.

• authToken (string): A valid authentication token (see getAuthToken).

Returns: A promise that will resolve with the updated slot type record.

flowStudio

utilities.orbitaAPI.flowStudio contains wrappers for Orbita Flow studio API endpoints.

getOneByProperty

Retrieves an Orbita Flow Studio flow by property and value.

Parameters:

• property (string): The property to check.

• value (string): The specified value of the property.

• authToken (string): A valid authentication token (see getAuthToken).

Returns: A promise that will resolve with the first Flow Studio flow with the specified property set to the specified value, or null if no results were found.

orbitaUtilities

utilities.orbitaUtilities contains wrappers for Orbita Utilities endpoints

orbita

utilities.orbitaUtilities.orbita contains wrappers for the Orbita Utilities wrapper for Orbita API endpoints

getProject

Retrieves an Orbita project from a specified environment by ID.

Parameters:

• environmentId (string): The ID of the environment (in Orbita Utilities)

• projectId (string): The ID of the project (in Orbita)

• apiKey (string): A valid Orbita Utilities API key

Returns: A promise that will resolve with the Orbita project.

getAllSchemas

Retrieves all available schemas for an Orbita project from a specified environment by ID.

Parameters:

• environmentId (string): The ID of the environment (in Orbita Utilities)

• projectId (string): The ID of the project (in Orbita)

• apiKey (string): A valid Orbita Utilities API key

Returns: A promise that will resolve with the available schemas for the Orbita project.

environment

utilities.orbitaUtilities.environment contains wrappers for the Orbita Utilities environment endpoint

getById

Retrieves an environment from Orbita Utilities by ID.

Parameters:

• environmentId (string): The ID of the environment

• apiKey (string): A valid Orbita Utilities API key

Returns: A promise that will resolve with the environment.

clientProject

utilities.orbitaUtilities.clientProject contains wrappers for the Orbita Utilities client project endpoint

getById

Retrieves a client project from Orbita Utilities by ID.

Parameters:

• clientProjectId (string): The ID of the client project

• apiKey (string): A valid Orbita Utilities API key

Returns: A promise that will resolve with the client project.

versionControl

utilities.orbitaUtilities.versionControl contains wrappers for the Orbita Utilities version control endpoint

requestDifferenceForConfiguration

Requests a difference for a particular version control configuration.

Parameters:

• configurationId (string): The version control configuration ID.

• apiKey (string): A valid Orbita Utilities API key

Returns: A promise that will resolve with the Git diff when the request has been fulfilled by Orbita Utilities.

requestSnapshotForConfiguration

Requests a snapshot for a particular version control configuration.

Parameters:

• configurationId (string): The version control configuration ID.

• author (string): The author of the commit.

• commitMessage (string): The commit message.

• apiKey (string): A valid Orbita Utilities API key

Returns: A promise that will resolve when the request has been fulfilled by Orbita Utilities.

configuration

utilities.orbitaUtilities.versionControl.configuration contains wrappers for the Orbita Utilities version control configuration endpoint

getById

Retrieves a version control configuration from Orbita Utilities by ID.

Parameters:

• configurationId (string): The version control configuration ID.

• apiKey (string): A valid Orbita Utilities API key

Returns: A promise that will resolve with the version control configuration.

sync

utilities.orbitaUtilities.sync contains wrappers for the Orbita Utilities sync endpoint

status

utilities.orbitaUtilities.sync.status contains wrappers for the Orbita Utilities sync status endpoint

getCurrent

Retrieves the current sync status information from Orbita Utilities.

Parameters:

• apiKey (string): A valid Orbita Utilities API key

Returns: A promise that will resolve with the current sync status information.

content

utilities.orbitaUtilities.sync.content contains wrappers for the Orbita Utilities content sync endpoint

requestSynchronization

Requests a synchronization of content from one project to another in Orbita Utilities.

Parameters:

• sourceEnvironmentId (string): The ID of the environment to sync from (in Orbita Utilities)

• sourceProjectId (string): The ID of the project to sync from (in Orbita)

• schema (object): The raw data from Orbita of the schema to sync

• destinationEnvironmentId (string): The ID of the environment to sync to (in Orbita Utilities)

• destinationProjectId (string): The ID of the project to sync to (in Orbita)

• apiKey (string): A valid Orbita Utilities API key

Returns: A promise that will resolve with the response to the content synchronization request from Orbita Utilities.

flowStudio

utilities.orbitaUtilities.sync.flowStudio contains wrappers for the Orbita Utilities flow studio sync endpoint

requestSynchronization

Requests a synchronization of flow studio flows from one project to another in Orbita Utilities.

Parameters:

• sourceEnvironmentId (string): The ID of the environment to sync from (in Orbita Utilities)

• sourceProjectId (string): The ID of the project to sync from (in Orbita)

• destinationEnvironmentId (string): The ID of the environment to sync to (in Orbita Utilities)

• destinationProjectId (string): The ID of the project to sync to (in Orbita)

• apiKey (string): A valid Orbita Utilities API key

Returns: A promise that will resolve with the response to the flow studio synchronization request from Orbita Utilities.