GraphQL type name collision helper

If a graph fails to be created or updated, it is likely a type name collision has occurred. Manual intervention is required to resolve type name collisions before a new valid graph can be created and published.

The GraphQL type name collision helper allows a user to view whether the last attempt to generate a graph was successful or not. If it was not successful, it allows the user to view a list of fatal errors causing the failure. In cases where the failure was caused by a type name collision, the helper provides details of the conflicting content type schemas.

The helper can be used when a graph has never been built or when a graph has not been built after an update.

Using the GraphQL type name collision helper

The functionality of the GraphQL type name collision helper is accessed using an HTTP API. Using the API requires authentication, as shown below:

Request URL

https://api.amplience.net/v2/content/hubs/{hub ID}/graphql-publishing-jobs`

For more information about finding the hub ID, head to the Finding the hub ID section.

Authentication

The parameters and values needed for you to use the API are listed in the table below.

Parameter	Value
Username	Your username used to login to Amplience Dynamic Content.
Password	Your password used to login to Amplience Dynamic Content
Access Token URL	https://auth.amplience.net/oauth/token
Auth Type	OAuth2
Grant Type	Resource Owner Password Credentials
Client ID	B8F76643-CF4B-4A86-B03F-2F026B88693B Note that the Client ID will always be this ID. Do not use the Client ID associated with your chosen hub.
Credentials	In Request Body Note that if you are using Insomnia to make a request, you may find the credentials section in the advanced options.

note

There is no Client Secret required for the usage of this API. Do not include one in your parameters.

Finding the hub ID

hub ID is the ID of the hub you're using for your queries. The hub ID can be found in the properties tab within the settings of your hub.

An example request is shown below:

https://api.amplience.net/v2/content/hubs/1234k6931r2125698b172c78/graphql-publishing-jobs

Additional query parameter

Include compilationSummary = true in your query parameters to get a breakdown of all fatal errors. Without this additional parameter, you will only get a response that informs you whether the last attempted publish failed or passed.

Response format

Response	Description
generatedName	This describes the type name that the colliding types are trying to resolve to.
conflictingTypes	Lists the two colliding content type schemas.
createdDate	When the last attempted graph generation took place.
code	The last attempt to generate the graph as a success or failure.
errors	Lists fatal errors if status equals failure.
detail	The detail for each error.
message	A description of each error.

note

conflictingTypes lists two content type schemas. If more than two content type schemas conflict with each other, multiple error blocks will be repeated to ensure each schema that has a conflict on that type name is reported at least once.

Status codes

Status code	Description
200	The request has succeeded.
400	Bad Request.
500	Internal error
524	Request timeout

Examples

As this is a diagnostic HTTP API, it can be used with any API tool, such as Postman. For the following examples, we will be using Insomnia.

Identifying failed graphs with the helper

In the GraphQL playground, you may receive a response like the below if a graph has never been built for your schema. The GraphQL type name collision helper can help us understand why.

Alternatively, if you make changes to a graph after it was built successfully, and the new changes are not being shown in the GraphQL playground, this can also be investigated using the GraphQL type name collision helper.

First, we retrieve an authorisation token using the required parameters, as shown below In Insomnia.

The response below is what we receive when we make our request without including compilationSummary = true in our additional query parameters. We're informed the graph for the specified hub has failed to publish without specific details about which schemas caused a collision.

{
  "_embedded": {
    "graphql-publishing-jobs": [
      {
        "id": "6512b090d7a5c99cc9a8bd86",
        "createdDate": "2023-09-26T10:21:03.967Z",
        "status": {
          "code": "FAILED_TO_PUBLISH"
        },
        "compilationJobId": "6512b090d7a5c99cc9a8bd85"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.amplience.net/v2/content/hubs/6452d5854e3436787a061b53/graphql-publishing-jobs"
    }
  }
}

Identifying type name collisions with the helper

Now we add the extra parameter of compilationSummary = true to discover which schemas are causing a type name collision.

Example response

{
  "_embedded": {
    "graphql-publishing-jobs": [
      {
        "id": "6512b090d7a5c99cc9a8bd86",
        "createdDate": "2023-09-26T10:21:03.967Z",
        "status": {
          "code": "FAILED_TO_PUBLISH"
        },
        "compilationJobId": "6512b090d7a5c99cc9a8bd85",
        "compilationSummary": {
          "status": "FAILURE",
          "errors": [
            {
              "level": "FATAL",
              "detail": {
                "message": "A type with a duplicate name exists.",
                "generatedName": "TutorialBanner",
                "conflictingTypes": [
                  "https://schema-examples.com/tutorial-banner#",
                  "https://schema-examples.com/tutorial-Banner#"
                ]
              },
              "type": "GRAPHQL_DUPLICATE_TYPE"
            }
          ]
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.amplience.net/v2/content/hubs/6452d5854e3436787a061b53/graphql-publishing-jobs?compilationSummary=true"
    }
  }
}

As shown in the response above, we can now see that our issue involves a banner schema and slot schema that have been given similar names.

The response message tells us the cause of the fatal error.

• generatedName is shown when a type name collision is the reason, and this describes the type name that the colliding types are trying to resolve to.

• conflictingTypes lists the two colliding content type schemas.

Solving a type name collision

There are three ways to solve a type name collision:

• Archive the schemas causing the collision
• Add type name directives to your colliding types
• Use the skip directive

Archiving schemas

One way to solve a type name collision is to use the Archive feature for colliding schemas. By Archiving a schema you remove it from the graph and remove any collisions it caused.

note

For more information about how Archiving works, please head to the Archiving a schema section.

Adding a type name directive

Another way to solve a type name collision is to add the graphql:typename directive to your schemas. By adding this directive, you can manually define your own GraphQL type names for each of the colliding content types.

If a user includes the graphql:typename directive within their schema, the value defined will be used to generate the GraphQL type name instead of the originally used type name, allowing for the type name collision to be solved.

For example, if we use the graphql:typename directive to change the name of some colliding tutorial banner content types, we will notice that if we create some content using our newly named tutorial banner and then query for banners in the GraphQL playground, we get a response showing that the graph has been built.

Using the GraphQL type name collision helper, we also get a response informing us that the graph was successfully built.

{
  "_embedded": {
    "graphql-publishing-jobs": [
      {
        "id": "65169d5c9e67b90c0475a8e3",
        "createdDate": "2023-09-29T09:48:12.108Z",
        "status": {
          "code": "SUCCESS"
        },
        "compilationJobId": "65169d5c9e67b90c0475a8e2",
        "compilationSummary": {
          "status": "SUCCESS",
          "errors": null
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.amplience.net/v2/content/hubs/6452d5854e3436787a061b53/graphql-publishing-jobs?compilationSummary=true"
    }
  }
}

note

For more information about how the graphql:typename directive works, along with syntax rules for naming and examples, please head to the GraphQL type name overrides section.

Using the skip directive

The graphql:skip directive can also be used to solve a collision. Adding this directive in your colliding content type schemas allows you to exclude them from the hub’s graph before it is built.

As the following schema snippet shows, the graphql:skip directive accepts only boolean values:

"type": "object",
   "properties": {
       "content": {
       "graphql:skip": true,
           "title": "content",
           "allOf": [
               {
                   "$ref":
"http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
               },
               {
                   "properties": {...}
               }
           ]

note

For more information about how the graphql:skip directive works, along with configuration options and accepted value formats, please head to the GraphQL type name overrides section.

Listing all hubs with the helper

The GraphQL type name collision helper also allows you to list all the hubs you have access to. To make use of this feature, make a HTTP request to the below URL and enter your authentication details:

https://api.amplience.net/v2/content/hubs/

Key information like the ID, name, label, description, status and more of all the hubs you have access to will be included in your response. Along with the associated applications, and localization details.

Here is a short snippet of the JSON response:

"_embedded": {
        "hubs": [
            {
                "id": "5aa146e5c9e77c00014eb084",
                "name": "ampproduct",
                "label": "Amplience Product",
                "description": null,
                "status": "ACTIVE",
                "cdv2": "ENABLED",
                "algoliaSearch": "ENABLED",
                "settings": {
                    "virtualStagingEnvironment": {
                        "hostname": "1vkz2i2i1hlau19hndnr03duvb.staging.bigcontent.io"
                    },
                    "previewVirtualStagingEnvironment": {
                        "hostname": "1vkz2i2i1hlau19hndnr03duvb.staging.bigcontent.io"
                    },
                    "applications": [
                        {
                            "name": "Website",
                            "templatedUri": "https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/dynamiccontenttutorials/bannerslotpreview.html?api={{vse.domain}}&timestamp={{context.timestamp}}"
                        },
                        {
                            "name": "Website local preview",
                            "templatedUri": "http://localhost:3000/preview/timestamp?vse={{vse.domain}}&timestamp={{context.timestamp}}"
                        },
                        {
                            "name": "Segment everyone local preview",
                            "templatedUri": "http://localhost:3000/preview/timestamp?vse={{vse.domain}}&timestamp={{context.timestamp}}&segment=everyone"
                        },
                        {
                            "name": "Blog List Preview dc-static-blog-nextjs",
                            "templatedUri": "https://ampproduct-static-blog-nextjs.netlify.com/?vse={{vse.domain}}"
                        },
                        {
                            "name": "acc-Preview",
                            "templatedUri": "https://{{vse.domain}}/v1/content/demo/content-item/336c2675-9aa6-4c9a-8998-25d702b5e3ae?template=slotPreview"
                        },
                        {
                            "name": "Website2",
                            "templatedUri": "https://doc-examples.s3.eu-west-2.amazonaws.com/cdv2version3.html?api={{vse.domain}}"
                        },
                        {
                            "name": "CDv2 preview (home-page/feature-banner)",
                            "templatedUri": "https://amp-product.s3-eu-west-1.amazonaws.com/tutorials/dynamiccontenttutorials/contentpreviewcdv2.html?api={{vse.domain}}"
                        }
                    ],
                    "devices": [
                        {
                            "name": "Desktop",
                            "width": 1024,
                            "height": 768,
                            "orientate": false
                        },
                        {
                            "name": "Tablet",
                            "width": 640,
                            "height": 768,
                            "orientate": true
                        },
                        {
                            "name": "Mobile",
                            "width": 320,
                            "height": 512,
                            "orientate": true
                        },
                        {
                            "name": "HD desktop",
                            "width": 1440,
                            "height": 960,
                            "orientate": false
                        }
                    ],
                    "publishing": {
                        "platforms": {
                            "amplience_dam": {
                                "API_KEY": "04c47824-6344-45bd-9345-0f9855245da7",
                                "endpoint": "ampproduct"
                            }
                        }
                    },
                    "localization": {
                        "locales": [
                            "en-GB",
                            "en-US",
                            "de-DE",
                            "fr-CH",
                            "fr-BE",
                            "fr-FR",
                            "es-ES",
                            "es-CL",
                            "es-CO",
                            "es-MX",
                            "es-EC",
                            "it-IT",
                            "sv-CH"
                        ]
                    },
                    "assetManagement": {
                        "enabled": true,
                        "clientConfig": "USER"
                    }
                },
                "createdBy": "c83fb65c-1593-44de-b998-e6b38aa6f69f",
                "createdDate": "2018-03-08T14:21:25.192Z",
                "lastModifiedBy": "1da3bdb2-4e42-4e1c-9811-ff4cd7ce4e8d",
                "lastModifiedDate": "2023-05-30T17:51:51.780Z",
                "_links": {
                    "self": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084"
                    },
                    "hub": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084"
                    },
                    "snapshots": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/snapshots{?page,size,sort,types}",
                        "templated": true
                    },
                    "create-snapshot": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/snapshots"
                    },
                    "batch-create-snapshots": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/snapshots/batch"
                    },
                    "snapshot-hierarchy": {
                        "href": "https://api.amplience.net/v2/content/hierarchies/snapshot"
                    },
                    "publish-hierarchy": {
                        "href": "https://api.amplience.net/v2/content/hierarchies/publish"
                    },
                    "search-editions": {
                        "href": "https://api.amplience.net/v2/content/editions/search/findByDate?hubId=5aa146e5c9e77c00014eb084{&projection,bounded,page,rangeEnd,rangeStart,size,sort}",
                        "templated": true
                    },
                    "events": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/events{?page,size,sort}",
                        "templated": true
                    },
                    "create-event": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/events"
                    },
                    "archive": {
                        "href": "https://api.amplience.net/v2/content/events/{id}/archive",
                        "templated": true
                    },
                    "extensions": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/extensions{?page,size,sort}",
                        "templated": true
                    },
                    "extensions-lite": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/extensions?show-full=false{&page,size,sort}",
                        "templated": true
                    },
                    "extension-by-name": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/extensions/{name}",
                        "templated": true
                    },
                    "create-extension": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/extensions"
                    },
                    "update": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084"
                    },
                    "update-settings": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/settings"
                    },
                    "share": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/share"
                    },
                    "grant": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/grant"
                    },
                    "revoke": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/revoke"
                    },
                    "content-repositories": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/content-repositories{?page,size,sort}",
                        "templated": true
                    },
                    "create-content-repository": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/content-repositories"
                    },
                    "register-content-type": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/content-types"
                    },
                    "create-content-type-schema": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/content-type-schemas"
                    },
                    "content-types": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/content-types{?page,size,sort,status}",
                        "templated": true
                    },
                    "list-content-type-schemas": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/content-type-schemas{?page,size,sort,status}",
                        "templated": true
                    },
                    "resolve-content-type-schema": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/content-type-schemas/resolve"
                    },
                    "search-content-items": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/content-items/find{?page,projection,query,size,sort}",
                        "templated": true
                    },
                    "facet-content-items": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/content-items/facet{?page,projection,query,size,sort}",
                        "templated": true
                    },
                    "filter-content-items": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/content-items/filter"
                    },
                    "get-hierarchy-parents": {
                        "href": "https://api.amplience.net/v2/content/hierarchy-node/{id}/parents",
                        "templated": true
                    },
                    "get-hierarchy-children": {
                        "href": "https://api.amplience.net/v2/content/hierarchy-node/{id}/children",
                        "templated": true
                    },
                    "search-localization-jobs": {
                        "href": "https://api.amplience.net/v2/content/localization-jobs/search"
                    },
                    "webhooks": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/webhooks{?page,size,sort}",
                        "templated": true
                    },
                    "create-webhook": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/webhooks"
                    },
                    "integrations": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/integrations{?page,size,sort}",
                        "templated": true
                    },
                    "create-workflow-state": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/workflow-states"
                    },
                    "workflow-states": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/workflow-states{?page,size,sort}",
                        "templated": true
                    },
                    "delivery-keys": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/delivery-keys?key={key}",
                        "templated": true
                    },
                    "locale-labels": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/locale-labels"
                    },
                    "bulk-archive": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/bulk-archive"
                    },
                    "bulk-unarchive": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/bulk-unarchive"
                    },
                    "bulk-update-workflow-state": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/bulk-update-workflow"
                    },
                    "bulk-apply-locale": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/bulk-apply-locale"
                    },
                    "bulk-assign-users": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/bulk-assign-users"
                    },
                    "bulk-copy-item": {
                        "href": "https://api.amplience.net/v2/content/hubs/5aa146e5c9e77c00014eb084/bulk-copy-item"
                    },
                    "create-algolia-search-index": {
                        "href": "https://api.amplience.net/v2/content/algolia-search/5aa146e5c9e77c00014eb084/indexes"
                    },
                    "algolia-search-indexes": {
                        "href": "https://api.amplience.net/v2/content/algolia-search/5aa146e5c9e77c00014eb084/indexes{?parentId,projection,page,size,sort,status}",
                        "templated": true
                    }
                }
            },

Related pages

GraphQL overview