Cascade CMS API Library

Version 2 includes REST contract corrections, including type-level breaking changes for target-related surfaces, ACL entry send/read shapes, audited nullability, required alternative fields, and role ability discrimination. See CHANGELOG.md before upgrading from 1.1.0.

Version 1.1.0 includes type accuracy fixes verified against the WSDL and REST API. Most changes add missing properties or fix incorrect types. Two changes may affect existing code:

• OperationResult.success changed from string to boolean — if you compare result.success === "true", update to result.success === true
• OperationResult.message changed from required to optional — the REST API omits this field on success

See CHANGELOG.md for the full list of changes.

Cascade Documentation

Please note this library is a work in progress. If you come across a bug please open an issue.

A JavaScript library for the Cascade CMS API. You can find more information about their API here: https://www.hannonhill.com/cascadecms/latest/developing-in-cascade/rest-api/index.html#Operations

Available for Cascade CMS v8.1.1 and later.

You can find an openAPI representation of the Cascade library here:

https://kuklaph.github.io/cascade-cms-api/swagger-ui/

Cascade provides in tandem with the REST API docs listed above, a WSDL operations page. In order to access this you will need to use your organization as a subdomain followed by this url:

cascadecms.com/ws/services/AssetOperationService?wsdl

Example: isSandActuallySandy.cascadecms.com/ws/services/AssetOperationService?wsdl

Install

This can be used either via NodeJS or Google Apps Script.

Either download/Copy the files and extract the zip or use npm npm i cascade-cms-api or npm ci cascade-cms-api depending on what you prefer.

General Usage

NodeJS

In your project file import the Cascade API.

import { CascadeAPI, Types } from "cascade-cms-api";

Google Apps Script

In order to use this library within a Google Apps Script (GAS) project you will need to copy the main.js and paste the contents as a new .gs file in your project.

To use the library you will need to instantiate the CascadeAPI function and pass it a config object with your apiKey and a Cascade CMS API URL with your custom domain:

{ apiKey: "", url: "" }

const cascadeAPI = CascadeAPI({
  apiKey: "",
  url: "https://isSandActuallySandy.cascadecms.com/api/v1/",
});

The apiKey is generated in your Cascade dashboard. The url is yourOrg.cascadecms.com/api/v1/ (this is the current version as of 1/9/2023).

If you are using this in Google Apps Script the async/await pattern is not used/required. GAS does not follow this pattern.

// Apps Script
// const cascadeAPI = CascadeAPI_({apiKey: "", url: ""})

// Nodejs
const cascadeAPI = CascadeAPI({
  apiKey: "",
  url: "https://isSandActuallySandy.cascadecms.com/api/v1/",
});

const readFile = async () => {
  const results = await cascadeAPI.read({
    identifier: {
      type: "page",
      id: "d3631e59ac1easd2434bd70be3fbfe8148abc",
    },
  });
  //...
};

Types are optional. You can add type definitions which may be helpful depending on the situation:

// Opt1 - inline
const read = await cascadeAPI.read({
  identifier: {
    type: "page", // inline gives you intellisense
    id: "d3631e59ac1easd2434bd70be3fbfe8148abc",
    //...
  },
});

// Opt2 - add external type
/**
 * @type {Types.EntityTypeString}
 */
const type = "page";
const read = await cascadeAPI.read({
  identifier: {
    type, // uses type from above and you get intellisense within the variable above
    id: "d3631e59ac1easd2434bd70be3fbfe8148abc",
    //...
  },
});

A built in retry is offered for the Nodejs version. The default allotted timeout time is 30 seconds. You can adjust whether or not to use a retry (the default is true) per request method as an optional parameter. If you want to update the timeout time, you can pass in an optional timeout parameter when instantiating CascadeAPI.

Read Audits

Asset audit requests use the same top-level identifier as other asset operations. Audit dates use Cascade's textual date format rather than ISO 8601.

const audits = await cascadeAPI.readAudits({
  identifier: {
    type: "page",
    id: "asset-123",
  },
  auditParameters: {
    auditType: "edit",
    startDate: "May 12, 2023 12:00:00 AM",
    endDate: "Aug 12, 2023 11:59:00 PM",
  },
});

To filter by a user, group, or role instead of an asset, provide username, groupname, or rolename inside auditParameters.

Other Resources

Cascade CMS Tools
Check out my other library cascade-cms-tools