Migration API Feedback

Developing with Prismic
1

Hi Prismic Support Team,

Our team is actively using the Migration API and we'd like to share some feedback that could help improve the documentation and developer experience for other users.

Current Challenge: We've encountered several gaps between the Migration API's actual functionality and its documentation, which has significantly impacted our development workflow.

Specific Issues We've Identified:

  1. Content Relationships Documentation Gap

    • The proposed solution for updating content relationships (referenced in "Hyperlink span must contain a 'data' field with link data" - #10) lacks programmatic implementation details

    • No clear guidance on whether this can be done programmatically or requires manual intervention

    • When content relationships work properly (with createDocument, it shows as a “Deleted Page” or with the documents ID in the field.

  2. Migration Release Limitations

    • Unable to query documents from the Migration Release ref

    • No bulk operations available for adding documents to releases

    • Manual workaround requires individually setting each document to a release, which is not scalable

  3. Batch Operation Failures

    • When using createDocumentFromPrismic, a single document failure causes the entire batch to fail

    • This breaks content relationships and forces us to create custom functions for maintaining relationships per data item

    • Example workaround we've had to implement:

    javascript

    body_content: () => {
    const preppedRichText = prepRichText(migration, doc.data.body_content)
    return preppedRichText
},

Impact: These documentation gaps have required significant trial-and-error development time and custom workarounds that could be avoided with clearer documentation. We’ve also found that there is a gap between what is proposed in the community vs what is feasible/possible requiring us to do our own testing.

Suggestions for Improvement:

  1. Add comprehensive code examples for common migration scenarios.

  2. Document programmatic approaches for handling content relationships

  3. Clarify limitations and provide recommended workarounds

  4. Include error handling best practices for batch operations and error codes that one may expeirence.

  5. Provide examples of querying and managing Migration Releases

Would it be possible to prioritize updating the Migration API documentation and code examples? We're happy to provide additional details about our use cases or test any improved documentation.

Thank you for considering this feedback. We appreciate Prismic as a platform and want to help make it even better for the developer community.

2

Hi,

Thanks a lot for taking the time to share this detailed feedback, it’s super valuable.

Some of the issues you’ve mentioned are already on our radar. Others would benefit from more context so we can better understand your use cases and see what’s most impactful to address. Specifically:

  1. Comprehensive code examples: What kind of migration scenarios would be most useful for you to see documented? (e.g. typical workflows you run often).

  2. Content relationships: Could you share the exact problem you’re facing here (code snippets, screenshots, etc.)? That would help us see where the documentation falls short.

  3. Clarifying limitations: Were you referring specifically to the points you listed in your post, or do you have other limitations in mind? If so, which ones in particular?

  4. Batch operations: We’re aware of the “one fail, all fail” issue. It’s on our radar, though there’s nothing planned yet.

  5. Querying/managing releases: Could you give us a bit more detail about your real-world use cases or examples where this has been blocking?

We’ll study all of this and see what improvements are possible on our side, both in terms of documentation and the API itself. Your input here is a big help in shaping what we prioritize.

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.

4

Hi,

Thank you for your feedback! We really appreciate you taking the time to share your thoughts. We’ll take your input into account as we discuss our next steps internally and work on our priorities. While I can’t give a specific timeline at the moment, please know that your feedback is valuable to us as we move forward.

1 Like