Cache Functions¶

Introduction¶

Cloud caching allows you to store data temporarily in the cloud. The cached value is visible to all operations running in the same scope until the cache expires, regardless of how an operation was started or which agent an operation runs on.

By caching data in Harmony, rather than relying on local or agent-specific data stores, data can be shared between separate operations and across projects.

Before using either the ReadCache or WriteCache functions (described below), be aware of these important notes:

• If defining a cache for an environment, care must be taken to use unique cache names in the projects to avoid unintentional overwriting of values. Obviously, if the intent is to share data between projects, then sharing the same cache name is required.
• These functions work only during runtime. If attempting to test a script or operation that includes these functions, errors will be generated.
• WriteCache and ReadCache values are not accessible through the Management Console.
• The default limit on using WriteCache is to a maximum of 100 calls per minute per organization.

Examples using ReadCache and WriteCache are covered both within the individual functions and in the Examples below.

Use Cases¶

The following are several example use cases where you may wish to use cloud caching:

• Assume two operation chains, Chain A and Chain B, in a single project. These chains are executed separately. With a single agent, temporary storage can be shared between the chains. But in a multiple-agent environment, temporary storage cannot be used since it is local to the agent that executes an operation rather than the project as a whole. If Agent 1 executes Chain A and Agent 2 executes Chain B, then the data generated by Chain A is not available to Chain B. Using cloud caching instead of temporary storage overcomes this problem.
• Data can be shared between asynchronous operations within a project.
• Errors that are generated across different operations could be stored to a common cache. By accumulating operation results in this manner, more comprehensive alerts can be built.
• Login tokens can be shared across operations.
• WriteCache and ReadCache functions can be used to share data between projects. Before cloud caching was available, all related operations were required to be within the same project, which could lead to very large projects. By using cloud caching, large projects can now be broken into smaller projects, which allows more granular permissions access as well as compartmentalization of development and testing.

ReadCache¶

Declaration¶

type ReadCache(string name[, long expirationSeconds, string scope])

Syntax¶

ReadCache(<name>, <expirationSeconds>, <scope>)

Required Parameters¶

• name: Up to 256 characters.

Optional Parameters¶

• expirationSeconds: Number of seconds before the cached value expires. Default is 30 minutes (1800 seconds). The maximum is 30 days (2592000 seconds). When used for ReadCache, the cached value will expire in this number of seconds after a successful read. If either no expiration or a non-positive expiration is specified, then the expiration of the cached value will be the expiration from the last write.
• scope: Determines if the scope of the cache is for the current project. The scope of the cache can be either "project" or "environment". (The shorter forms "proj" and "env" are also accepted.) The default scope is "project" if either no scope or an empty string is specified. The cached value is visible to all operations running in the same scope until it expires, regardless of how that operation was started or which agent the operation runs on.

Description¶

Reads from a common cache stored on Harmony.

Examples¶

// Read a cached value in the default scope (project)
myToken = ReadCache("authToken");

// Read a cached value in the "env" scope
myToken = ReadCache("authToken", "", "env");

// Read a cached value in the environment scope with a default timeout
lastTimeStamp = ReadCache("lastTimeStamp", -1, "env");

WriteCache¶

Declaration¶

void WriteCache(string name, type value[, long expirationSeconds, string scope])

Syntax¶

WriteCache(<name>, <value>, <expirationSeconds>, <scope>)

Required Parameters¶

• name: Up to 256 characters.
• value: Cannot exceed 1MB.

Optional Parameters¶

• expirationSeconds: Number of seconds before the cached value expires. Default is 30 minutes (1800 seconds). The maximum is 30 days (2592000 seconds). If either no expiration or a non-positive expiration is specified, then the expiration of the cached value will be renewed using the expiration from the last write. The maximum allowed expiration time is set by your organization and/or Harmony.
• scope: Determines if the scope of the cache is for the current project. The scope of the cache can be either "project" or "environment". (The shorter forms "proj" and "env" are also accepted.) The default scope is "project" if either no scope or an empty string is specified. The cached value is visible to all operations running in the same scope until it expires, regardless of how that operation was started or which agent the operation runs on.

Description¶

Writes to a common cache stored on Harmony.

Examples¶

// Write a value to the cache in the default scope ("project")
WriteCache("authToken", myToken);

// Write a value (a timestamp using the Now() function)
// to the cache in the environment ("env") scope with a default timeout
WriteCache("lastTimeStamp", Now(), -1, "env");

// Writing a value without specifying an expiration or scope
// $authToken would be generated from a login operation
WriteCache("authToken", $authToken);

// Write a value to the cache in the "env" scope
// No expiration specified
WriteCache("City", "Houston", "", "env");

Examples¶

Example 1: Project Scope¶

// Write a value to the cache in the default scope (project)
WriteCache("authToken", myToken);

// Read the cached value in the default scope (project)
myToken = ReadCache("authToken");

Example 2: Environment Scope¶

// Write a value (a timestamp using the Now() function)
// to the cache in the environment ("env") scope with a default timeout
WriteCache("lastTimeStamp", Now(), -1, "env");

// Read the cached value in the environment scope with a default timeout
lastTimeStamp = ReadCache("lastTimeStamp", -1, "env");

Example 3: No Expiration Seconds or Scope¶

// Writing a value without specifying an expiration or scope
// $authToken would be generated from a login operation
WriteCache("authToken", $authToken);

// Reading the cached value:
myToken = ReadCache("authToken");

Example 4: Use Scope Only¶

This example includes specifying the environment in the scope parameter, and setting the timeout to an empty string. The expiration_seconds can be an empty string, a negative number (such as "-1"), or a number of seconds up to 30 days (2592000 seconds).

// Writing specifying the environment only
WriteCache("City", "Houston", "", "env");

Example 5: Use Expiration Seconds Only¶

This example specifies an expiration of 300 seconds. The expiration_seconds can be an empty string, a negative number (such as "-1"), or a number of seconds up to 30 days (2592000 seconds).

// Writing specifying the expiration in seconds
WriteCache("City", "Houston", "300");

Reading of the cached value. The cached value will be returned only if the call follows within 300 seconds of the writing; otherwise, a null value will be returned:

// Reading the cached value
city = ReadCache("City");