Prepare your Pack for column renaming features

Making Packs
1

The Packs team is in the process of implementing some SDK features that in the near-future will allow Pack makers to rename sync table columns (top-level schema properties) without impacting existing docs. To be able to take advantage of this feature you’ll need to do some preparation now. Specifically:

  1. Rebuild your Pack on SDK version 1.5.1 or greater and release it.
  2. In rare cases, manually set column IDs.

Complete these steps by September 15th, 2023 to ensure that your Pack is best setup to take advantage of these features when they are released. See below for more information on how to complete these steps.

If your Pack doesn’t contain any sync tables, or you don’t expect you’ll ever want to rename a column, then no action is required. If you fail to take action before the deadline then using the column renaming feature at some future date may negatively impact docs using your sync table.

Rebuilding your Pack

If you use the Pack Studio all you need to do is open your Pack, add a space somewhere, and then click the Build button. Once the build is complete, use the Release button to release that new version of your Pack.

If you use the Pack CLI to develop locally you’ll need to update to the latest version of the SDK. For example:

npm install --save @codahq/packs-sdk@latest \
&& npx coda upload pack.ts \
&& npx coda release pack.ts --notes "Updated SDK version."

Manually set column IDs

The upcoming SDK renaming feature requires that the schema property being renamed has a stable identifier set. Going forward this ID will default to the property’s key, which also serves as the basis of the display name, etc.

In some cases however it may make sense to use a different value as the stable ID. For example when a dynamic sync table includes custom properties returned by the API, each of which have a unique ID in addition to a user visible name. Setting an ID manually will also allow users to rename custom fields in the source application without breaking sync tables.

In these cases you should adjust your getSchema function to set the column ID manually, using the fixedId field.

for (let customField of customFields) {
  properties[customField.name] = {
    type: coda.ValueType.String,
    // Use the custom field's ID as the column ID.
    fixedId: customField.id,
  }
}

After making these changes make sure to release a new version of your Pack.

Let us know if you have any questions or feedback. We don’t have a firm date as to when the aforementioned column renaming features will be live, but expect it to be at least a few months out.

7 Likes