Changelog

New dashboard private beta and API v3 release

Cosmic

January 31, 2023

We are excited to announce the release of the new dashboard in private beta along with the API v3. This release has been a long time in the making and we are looking forward to helping you upgrade to the new dashboard and API for production use.

Below is a list of changes that you should be aware of. Sign up for the new dashboard to get all of the latest features noted below.

Summary

🎉 The new dashboard, API, and NPM module are ready for private beta customer upgrade.
⚠️ Potential breaking change: Object models are now strongly typed and strictly connected to the Object type model.
⚠️ Potential breaking change: Parent Metafields cannot contain other Parent Metafields. Repeaters cannot contain Parent Metafields.
⚠️ Potential breaking change: depth now required for all API requests past the first level.
✨ Feature improvement: API metadata write improvements.
✨ Feature improvement: Media validation by type and size.
✨ New Feature: Object type folders.

What’s new?

New Cosmic dashboard now ready for customer upgrades
New Cosmic API version (v3)
New Cosmic NPM module (@next v5.0.0)

We’ve rebuilt the dashboard and the API from the ground up. Importing from dashboard v1 to v2 should be smooth as long as your modeling is compatible. Please note the breaking changes which may require updates to your content modeling to upgrade to the new versions.

Compatibility checking
In the old dashboard, go to Bucket Settings > Import / Export and find the area titled “Dashboard v2 compatibility” to note any compatibility issues that may occur with the migration. These can be fixed in the old dashboard, or in the new dashboard.

🔒 Object Type modeling locked - Potentially breaking

In the old dashboard, Objects could individually have a different content model than the Object type model. This has proven to be an undesired behavior, especially since we rolled out Singleton Object types which better satisfies the use case for unique Object models.

In the new dashboard, Objects are now strongly typed and strictly connected to the Object type model. This includes when making any changes to keys, adding Metafields, deleting Metafields or updating the order of Metafields.

✅ Metafield modeling restrictions - Potentially breaking

** Parents are now only allowed at the first level **

We have made updates to allowable Metafield modeling which may break some modeling:

Parent Metafields are now only allowed at the first level. Parent Metafields cannot contain any other Parent Metafields.
Repeater Metafields cannot contain Parent Metafields.

📁 Object type folders - New feature

Object type folders are now available to help you better organize your Object types. This should be a welcome feature for those of you who are using Cosmic to store and manage a lot of different Object types.

📍API updates - Improvements

Depth update
In the API v3, if you are using the the high-level metadata set in props, you will now need to include the depth parameter to retrieve nested Object data. For example, if you have Blog Posts that have an Object Metafield in the model connected to Authors, to retrieve the Author Object along with Blog Posts, you will need to set the depth parameter to 1.
depth:0 returns the Object id (string)
```
{  
  "title": "My Blog Post",
  "slug": "my-blog-post",
  "metadata": {
    "author": "asdfasdf12341234"
  }
}
```
depth:1 returns the nested Object data (object)
```
{
  "title": "My Blog Post",
  "slug": "my-blog-post",
  "metadata": {
    "author": {
      "id": "asdfasdf12341234",
      "title": "John Doe",
      "slug": "john-doe"
      ...
    }
  }
}
```
The default depth value is 0. This is only applicable if you have metadata included in props without any further name-spaced declarations. Circular references are prohibited.
API Metafield updates
Objects no longer return metafields from the API, only metadata. You can still get metafields from the Object type from the API.
Metafield values are now strongly typed, so any Metafields that do not have values set will return as null. For example, if you don’t set a value on a Number Metafield, it will now return null instead of empty string.

🪄 Dashboard - Adding / editing Objects - Improvement

Adding and editing Object Metadata via the API got a lot better.

Before 😫
Before, adding Metadata was cumbersome requiring you to explicitly state all Metafield properties and values when making your edit Object API request.

Now 🥳
Now you only need to include the metadata values. Much simpler and concise.

🖼️ Dashboard - Media Metafield validation - Improvement

We have added new Media Metafield validations to enable you to restrict Media Metafields to images, audio, video, and document file types. Along with granular file type restrictions, you can also include a maximum file size to help guide your content creators to optimize your content creation and Bucket file storage.

Media previews are also much improved, giving you the ability to preview video, audio, and PDF files.

🆘 Migration Troubleshooting

There may be issues when you attempt to import from the old dashboard into the new dashboard. Some common issues may be:

Object and Object type Metafields model issues
- To make sure that your Bucket is compatible with the new dashboard, in the old dashboard go to Bucket Settings > Import / Export and find the area on this page that says “Dashboard v2 compatibility” and test your Bucket compatibility. If any issues are reported, they can be fixed in the old dashboard, or in the new dashboard after import.
- Object Metafield models are now strongly typed and strictly tied to their Object type. This should come as a welcome change, but could be an issue if, in the old dashboard, you had single Objects that were composed of a different Metafield model than the Object type. To fix this, make sure that your Object type model is accurate for all Objects, and if you do have Objects that need a unique Metafield model, create a Singleton Object type to store this single Object instead.
If importing a Bucket into the new dashboard that previously contained modeling that is not supported, it will be ignored. IE: if you have a Parent inside of a Parent Metafield or any other unsupported Metafield model.

🏗️ Product architecture and pricing updates

The product architecture has been updated to two main usage levels:

Projects
- Projects contain Buckets. You can have multiple Buckets in a Project plan.
- Add ons are available at the Project level and shared on all Buckets in the Project.
- Team members are added and managed in the Project. Granular roles and permissions are available.
- Usage reports are available in the Project. Filter by Bucket usage.
- Billing is handled at the Project level. See Project > Billing > Plan for new pricing details.
Workspaces
- Workspaces contain Projects. You can have multiple Projects and Buckets in a Workspace plan.
- Add ons are available at the Workspace level and shared on all Projects and Buckets in the Workspace.
- Team members are added and managed in the Workspace. Granular roles and permissions are available.
- Usage reports are available in the Workspace. Filter by Project and Bucket usage.
- Billing is handled at the Workspace level. See Workspace > Billing > Plan for new pricing details.

➡️ Features TBD

There are a few features that we are still working on, but are planning on including them in a future release:

Merge Requests
- Offers git-like workflows for your content. Including visual change review and team member approvals.
Single Sign On
- Offering teams a way to login using a 3rd party IdP
Workspace subdomain
- Offering teams their own workspace subdomain.
Mobile dashboard access
- The new dashboard is currently desktop only.
CLI connected to API v3

This is a big release for us and we hope you enjoy all of the updates. Sign up for the new dashboard to reserve your spot in line. Follow us on Twitter and join our Slack community to stay up with the latest updates.

Back to changelog