Home » User Documentation » Connectors » Custom Connectors » Scripting » Scripting Functions

Scripting Functions

9 min read

The following functions are available for use in your Scripts:

atob #

Function to decode a Base64 encoded string, using a specified source character set, back to its original value.

Supported character sets which can be used: ASCII, ISO-8859-1, UTF-7, UTF-8, UTF-16, UTF-16LE, UTF-16BE, UTF-32, UTF-32LE, UTF-32BE

Note: If no character set is provided, the default will be UTF-8.

var Utf8Base64Decoded = atob("SMSVbGzFjSBXxY1ybGQ="); // Hĕllō Wōrld
var AsciiBase64Decoded = atob("SD9sbD8gVz9ybGQ=","ascii"); // H?ll? W?rld
var IsoBase64Decoded = atob("SGVsbG8gV29ybGQ=","iso-8859-1"); // Hĕllō Wōrld

btoa #

Function to encode a string to Base64 using a specified destination character set.

Supported character sets which can be supplied: ASCII, ISO-8859-1, UTF-7, UTF-8, UTF-16, UTF-16LE, UTF-16BE, UTF-32, UTF-32LE, UTF-32BE

Note: If no character set is provided, the default will be UTF-8.

var Utf8Base64Encoded = btoa("Hĕllō Wōrld"); // SMSVbGzFjSBXxY1ybGQ=
var AsciiBase64Encoded = btoa("Hĕllō Wōrld","ascii"); // SD9sbD8gVz9ybGQ=
var IsoBase64Encoded = btoa("Hĕllō Wōrld","iso-8859-1"); // SGVsbG8gV29ybGQ=

http_request #

Function to make external HTTP requests.

When calling the http_request function, you provide a JSON object with the following properties:

method: the HTTP method, e.g. GET, POST, DELETE, PUT.
url: URL for the HTTP request.
parameters: Querystring parameters.
headers: HTTP headers.
data: HTTP request data. If sending JSON, you should use JSON.stringify() to serialize it.

Example:

function after_action() {
	var response = http_request(
		{
			'method': 'POST',
			'url': 'https://someapi.com/createsomething',
			'headers':
			{
				'Authorization': 'Bearer ' + method_auth_value,
				'Content-Type': 'application/json',
				'Accept': 'application/json'
			},
			'data': JSON.stringify( { "MyData": "some value" } )
		}
	);

	return true;
}

The Response from an http_request call is returned as a JSON object with these properties:

status_code: the HTTP Status code returned
headers: any HTTP headers
content: the Response body
request: details of the Request that was made

uuid #

Function to generate a Universally Unique Identifier (or “UUID”) string.

Example:

var uniqueId = uuid(); // uniqueId will contain a random alphanumeric string in the format "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX".

cyclr_aes_decrypt #

Function to decrypt a Base64-encoded AES-256-GCM ciphertext produced by the cyclr_aes_encrypt() Script function.

The key is derived from the passcode and salt parameters by using the Password-Based Key Derivation Function 2 (“PBKDF2”) cryptographic algorithm.

Parameters must be identical to those used during encryption.

Will throw an error if the ciphertext or authentication tag has been tampered with.

Parameter	Description
ciphertext	Required The Base64-encoded ciphertext to decrypt, as returned by `cyclr_aes_encrypt()`.
passcode	Required The password used to derive the decryption key using PBKDF2. Must match the value used to encrypt.
salt	Required The salt value used for key derivation. Must match the value used to encrypt.
hashAlgorithm	The PBKDF2 hash algorithm used for key derivation. String Options are: * SHA1 * SHA256 * SHA384 * SHA512 Defaults to SHA1 if not set. Must match the value used to encrypt.
iterations	The number of PBKDF2 iterations for key derivation. Integer Defaults to 1000 if set to 0 or not provided. Must match the value used to encrypt.

Returns: The decrypted plain text string.

Example:

var passcode = 'my-secret-password';
var salt = 'my-salt-value';

// Encrypt a value:
var ciphertext = cyclr_aes_encrypt('This is the string to encrypt.', passcode, salt);

// Decrypt it:
var plaintext = cyclr_aes_decrypt(ciphertext, passcode, salt);

// With optional parameters:
var plaintext = cyclr_aes_decrypt(ciphertext, passcode, salt, 'SHA256', 10000);

cyclr_aes_encrypt #

Function to encrypt a string using AES-256-GCM encryption.

The key is derived from the passcode and salt parameters by using the Password-Based Key Derivation Function 2 (“PBKDF2”) cryptographic algorithm.

The output can be decrypted using cyclr_aes_decrypt() with identical parameters.

Parameter	Description
content	Required The plaintext string to encrypt.
passcode	Required A password used to derive the encryption key using PBKDF2.
salt	Required A salt value used alongside the passcode for key derivation.
hashAlgorithm	The PBKDF2 hash algorithm to use for key derivation. String Options are: * SHA1 * SHA256 * SHA384 * SHA512 Defaults to SHA1 if not set.
iterations	The number of PBKDF2 iterations for key derivation. Integer Defaults to 1000 if set to 0 or not provided.

Returns: A Base64-encoded string of the binary data for the nonce, ciphertext, and GCM authentication tag.

Example:

var content = 'This is the string to encrypt.';
var passcode = 'my-secret-password';
var salt = 'my-salt-value';
var ciphertext = cyclr_aes_encrypt(content, passcode, salt);

// With optional parameters:
var ciphertext = cyclr_aes_encrypt(content, passcode, salt, 'SHA256', 10000);

cyclr_encrypt #

Function to generate a hash from a value.

Parameter	Description
algorithm	The hashing algorithm to use. String Options are: * md5 * sha1 * sha256 * sha512
data	The input data to generate a hash from.
base64Encoded	Whether the `data` parameter is base64 encoded. Boolean Defaults to `false` if not set.

Example:

var algorithm = 'sha512';
var valueToHash = 'This is the string to hash.';

var hash = cyclr_encrypt(algorithm, valueToHash);

cyclr_sign #

Function to sign a string.

Example:

var algorithm = 'HMAC-SHA1';
var signingKey = 'This is the signing key.';
var valueToSign = 'This is the string to sign.';

var signature = cyclr_sign(algorithm, signingKey, valueToSign, 'base64');

Supported algorithms are: HMAC-SHA1, HMAC-SHA256, HMAC-SHA512, RSA-SHA1, RSA-SHA224, RSA-SHA256, RSA-SHA384, RSA-SHA512.

If provided, the 4th parameter in the function call is the encoding type of the signingKey as a string. Possible values are:

UTF8 – the default if not provided.
hex
base64

cyclr_csv_parse #

Function to parse a CSV string.

var csv = '1,2,3\na,b,c\nd,e,f';
var delimiter = ',';
var hasHeader = false;

var csvRecords = cyclr_csv_parse(csv, delimiter, hasHeader);

csvRecords would then contain the following JSON object, representing the CSV content:

[
	{
		"Field1": "1",
		"Field2": "2",
		"Field3": "3"
	},
	{
		"Field1": "a",
		"Field2": "b",
		"Field3": "c"
	},
	{
		"Field1": "d",
		"Field2": "e",
		"Field3": "f"
	}
]

cyclr_xml_serialize #

Function to convert JSON to XML.

  var jsonObj = {
    "note": {
        "to": "Tove",
        "from": "Jani",
        "heading": "Reminder",
        "body": "Dont forget me this weekend!"
    }
  };
  var jsonObjAsXml = cyclr_xml_serialize(jsonObj);

  // Output:
  //<note><to>Tove</to><from>Jani</from><heading>Reminder</heading><body>Dont forget me this weekend!</body></note>

cyclr_xml_deserialize #

Function to convert XML to JSON.

  var xmlStr = '<note><to>Tove</to><from>Jani</from><heading>Reminder</heading><body>Dont forget me this weekend!</body></note>';
  var xmlAsJson = cyclr_xml_deserialize(example);

// Output:
//   {
//     "note": {
//         "to": "Tove",
//         "from": "Jani",
//         "heading": "Reminder",
//         "body": "Dont forget me this weekend!"
//     }
//   }

PGP Encryption #

Cyclr provides the following Script functions for use with Pretty Good Privacy (“PGP”) encryption:

cyclr_pgp_encrypt(textToEncrypt, pgpPublicKey)
cyclr_pgp_decrypt(encryptedPgpMessage, pgpPrivateKey, password)

These functions enable you to encrypt and decrypt data using PGP encryption and can be used on Connector Methods or directly on Steps within the Builder.

With PGP encryption, you generate a Public and a Private Key as a pair. You then encrypt text using the Public Key, and decrypt it using the Private Key.

cyclr_pgp_encrypt #

Simple Example:

function before_action() {
    method_request.messageContent = cyclr_pgp_encrypt(method_response.messageContent, "myPublicKey");
    return true;
}

Example showing realistic (but truncated) values:

var encryptedMsg = cyclr_pgp_encrypt(`A string to encrypt.`, `-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: OpenPGP.js v.1.20130420
Comment: http://openpgpjs.org

xk0EZ6OKXgECAM7iHQVl78y7/THrCBj+5+dRB3NFDcZcj4qI8//f3eg173CT
[...]
XyMhZhJGMH++oR2j/s0QW+yxR6Ac+PzC+1wDk8BUuw==
=MfCB
-----END PGP PUBLIC KEY BLOCK-----`);

cyclr_pgp_decrypt #

Simple Example:

function after_action() {
    method_response.decryptedData = cyclr_pgp_decrypt(method_response.data, "myPrivateKey", "myPassword");
    return true;
}

Example showing realistic (but truncated) values:

var decryptedMsg = cyclr_pgp_decrypt(`-----BEGIN PGP MESSAGE-----
Version: OpenPGP.js v4.10.10

wYwDbctZCAjZL9MBBAC1UOC/K1HC32gMlh1wQUT2B/CUwTBUJY9rGXCuZVuT
[...]
QIb6hK1SRamKnTK331X+WfNSChwV7lJiY8coJWBHpMNTaQ==
=OP5x
-----END PGP MESSAGE-----`, `-----BEGIN PGP PRIVATE KEY BLOCK-----
Version: BCPG v1.58

lQH+BGeE6mABBADkWBXfayPtXYK8tobIxhNZRYi0Tz7EmQ6Kaj8XWoi3ypPYRxED
[...]
Oi8Y8uDjnnyj7msKTOHrGLiX4CovtmE/QfDTXtY0g/lwA5OPnQzb7O+tme+kJuT6
c3i7fg==
=Fixv
-----END PGP PRIVATE KEY BLOCK-----`, 'E*rtAZ9m-3Hs9FgjHEyk')

Storage Functions #

Cyclr provides several storage functions available for use in Script that can be used when developing a Connector, or on a Step in a Template or Cycle.

Data they work against is locked to the Connector they’re called on. i.e. if you write data using cyclr_storage_set() on a Step from one Connector, you cannot access that same data using cyclr_storage_get() on a Step from a different Connector.

The functions come in 2 flavours:

cyclr_storage_...() and cycle_storage_...()

The cyclr_storage_...() functions access the same data on any Steps in any Cycles for a particular Connector.

The cycle_storage_...() functions work in the same way, but their data is further restricted to the context of a particular Cycle. If you write data in one Cycle, you cannot access it in another;

The storage functions available in their cyclr_ versions are shown below.

Change cyclr_ to cycle_ to use their Cycle-restricted versions.

cyclr_storage_list_values()
cyclr_storage_delete_all()
cyclr_storage_delete(key)
cyclr_storage_get(key)
cyclr_storage_set(key, value)
cyclr_storage_append(key, value)
cyclr_storage_list_keys()
cyclr_storage_increment(key, amount)
cyclr_storage_decrement(key, amount)

Libraries #

The following libraries are available within Cyclr’s script engine:

Note: It is not necessary to load these with a JavaScript require call as they are all automatically available for use in your Scripts.

Moment.js #

Library Name: moment

Description: Parse, validate, manipulate, and display dates and times in JavaScript. Cyclr also supports the Moment “Timezone” extension, which enables formatting and converting of dates in any timezone.

External Documentation:

CryptoJS #

Cyclr includes a basic implementation of CryptoJS so some features may not be present or behave differently to its official documentation.

Library Name: crypto-js

Description: JavaScript library of crypto standards.

External Documentation:

Notes on use:

The output of encrypted data is always a hexadecimal string.
The formatting options found in CryptoJS.enc are not supported when calling .toString().

Modules supported by Cyclr:

MD5
SHA1
SHA256
HmacSHA1
HmacSHA256
HmacSHA512

Example usage:

var md5Hash = CryptoJS.MD5("A string to hash.");
var sha256Hash = CryptoJS.SHA256("A string to hash.");
var hmacSha512Hash = CryptoJS.HmacSHA512("A string to hash.");

About Cyclr

Cyclr Console

Connectors

Templates

Accounts

Embedding

API

Deep Data Ingestion

Near Real-Time Actions

MCP Servers

Release Notes

Scripting Functions

atob #

btoa #

http_request #

uuid #

cyclr_aes_decrypt #

cyclr_aes_encrypt #

cyclr_encrypt #

cyclr_sign #

cyclr_csv_parse #

cyclr_xml_serialize #

cyclr_xml_deserialize #

PGP Encryption #

cyclr_pgp_encrypt #

cyclr_pgp_decrypt #

Storage Functions #

Libraries #

Moment.js #

CryptoJS #