Migration API Feedback

Developing with Prismic
3

  1. Comprehensive code examples:

    I think the biggest thing that would be helpful is that if a solution is given as an example, it would be nice to see it in use. An example can be found here:

    Migrating to Prismic — Prismic Docs

    • While the example is that we can use await writeClient.getByUID(), it seems this conflicts with other information that tells us that we cannot query the Prismic Repo for documents that are in the migration release. This puts the user in a bit of a catch 22 because either we are unaware how to use it or Prismic is giving conflicting information. Given that this is a newer release and there’s more being fleshed out, I’m sure it is more a matter of user ignorance.

    Another example would be what it would look like for legacy Prismic users createDocumentFromPrismic (found here). This is a great utility however our team has found this fails in many instances because either content relationships become an issue and/or Prismic doesn’t filter data it considers adequate for upload/migration. This can be found with how things like richText is handled, or legacy slices, etc.

  2. Content relationships:
    The long and short of this problem is we’ve had to discover how to properly signal to the Migration API how/when to fetch content relationships. This is a snippet to show in order to get our slice to properly look for content relationships in the function getRelatedItems we needed to set doc.data.related_items to a function call using ( ) => {} which took a bit of trial and error to discover since using the method in the documentation did not immediately help with getting the correct content relationship to work for that slice.
    An example is this code snippet here:

related_items: () => {
  let getItems: Array<{ related_item: FilledContentRelationshipField }> = []
  
  getItems = getRelatedItems(getItems, migration, doc)

  return getItems
},

  1. Clarifying limitations:
    This was mostly covered in the above but there are some things that aren’t as clear as they could be.

    • An example is the limitations on publishing migration documents. We’ve found a pretty big failure rate in trying to publish/archive numerous documents (in the hundreds) but it’s never consistent. Sometimes 400 will work. Sometimes 200 will fail.
    • Another example is the writeClient’s capabilities. I’ve given more detail below but there is no clarity on updating documents using migration.updateDocument() if one cannot query the migration release

  2. Batch operations: Thank you for this update.

  3. Querying/managing releases:
    We've received conflicting guidance about querying documents in migration releases: some say we can map IDs and update, others say we cannot access the migration release directly. The documentation suggests using updateDocument but this fails with 'no documents found' errors.

    I could be completely misinterpreting it so my apologies but it isn’t straightforward and leaves a lot of room for a user to have to interpret on there own.

These are just a few examples and there is a high likelihood that we are misinterpreting much of what’s being suggested/may be a case by case situation. However it seems easy to lose oneself especially if there are multiple documents that need to be migrated.

Thank you for lending us your ears and we hope that this is somewhat helpful in Prismic’s continued growth.