Troubleshooting: Integration fields

[Phil (Phil Snow)]

Encountering issues while using integration fields with Prismic? This guide addresses common problems, their causes, and how to resolve them effectively.

Issue: Integration Fields Not Enabled

• Solution: Check your repository settings for Integration Fields. If unavailable, contact Prismic support for activation.

Issue: Connected to the wrong catalogue

• Solution: This may be a case of a copy and paste mistake. Make sure the id of the catalogue in the Custom Type you're using, matches that of the updated catalogue.

Issue: Integration Fields with Slice Machine

• Symptom: Can't find the option to add an integration field to a page type in Slice Machine
• Cause: The field isn't yet available in the Slice Machine Interface, but that doesn't mean you can't use it already.
• Solution: Find the index.json of the Page Type or the model.json of your Slice and add the integration Field:

"api_id": { // Rename the api_id of the field
   "type": "IntegrationFields",
   "config": { // modify the catalog values
      "catalog": "my-repository--your_store", //if your repository is called lorem and your Integration catalog is called my store, the value will be: "catalog": "lorem--my_store"
       "label": "Here goes the field name",
      "placeholder": "This is the field placeholder..."
   }
}

Save your JSON file, Push your changes to Prismic, and you're done. Now you can visualize and use your integration field in the documents!

Issue: Incorrect Catalog Naming Conventions

• Symptom: Your catalog names do not match expected values in Prismic, leading to integration failures.
• Cause: Catalog names must be all lowercase and use underscores (_) instead of spaces.
• Solution: Rename your catalog in the format "catalogue": "projectname--catalog_name". For example, if your catalog is "My Awesome Store" and your Prismic project is "CoolProject", use "catalogue": "coolproject--my_awesome_store".

Issue: Incorrect Endpoint Configuration

• Symptom: Integration failures with Shopify.
• Cause: Endpoint format does not match the required specification, possibly containing extra URL details.
• Solution: When configuring the integration with the Shopify catalog, Make sure that your API Endpoint is in the following format: my-store-name.myshopify.com. It should be without HTTPS. Otherwise, An error occurs during synchronization.

Issue: Sync Error

• Symptom: Not getting the latest items in when using the editor.
• Cause: Mutliple reasons, see error codes.
• Solution: Go to your Integration Fields settings in the Prismic dashboard and see if it's synchronised or if there are any errors, the status codes will help you see what's wrong. If there are no errors you'll see the last time it was updated. Check the error on your side.

Issue: API Error Codes

Find these in your repo https://your-repo-name.prismic.io/settings/integrationfields/. Hover over the error so see more details.

• Symptom: Receiving error responses like 200, 400, 403, or 404 when attempting to integrate.
• Cause:

  • 200 (Success): Indicates successful operations.

  • 400 (Bad Request): General API misuse.

  • 403 (Forbidden): Authentication issues.

    • If this is for Shopify catalogues, then usually, the issue might be due to the fact that you need to give 'all access' to 'Integration fields' when creating your Shopify app. Make sure that all the Admin API permissions are set to Read Access or Read and Write access.
      
      

  • 404 (Not Found): Incorrect endpoint configurations.

• Solution: Ensure that your API integration adheres to Prismic's format and authentication guidelines. Verify that all endpoint configurations are correct.

Issue: Data Structure Mismatch

• Symptom: Errors during synchronization with Prismic's Integration Fields.
• Cause: Incorrect data format or missing required fields such as description and last_update.
• Solution: Verify that all data provided to Prismic matches the required structure and that no fields are null. Check the complete list of required fields.

Issue: Issues with Creating, Updating, or Deleting Catalog Items (Required fields)

• Symptom: Unable to perform write operations on your catalog.
• Cause: Incorrect request formatting or missing authorization tokens when sending POST requests.
• Solution: When performing operations via the Prismic Integration Fields write API, ensure your POST requests include all necessary information (results size, item ID, title, description, image URL, last update timestamp) and authorization tokens.

Further Assistance

If you've followed these troubleshooting steps and still encounter issues, it may be beneficial to review the integration fields documentation or create a new post for more detailed assistance.