Documentation Center

externalItem query

Use the externalItem GraphQL query get a single entity.

Query syntax

The following code illustrates required format for the GraphQL request, followed by a description of the input values:

{
   externalItem([eclUri: "ECL-URI"]
                [identity: {
                    namespace: "NAMESPACE",
                    id: "IDENTIFIER",
                    type: "TYPE"
                    [,localeId: "LOCALE_ID"]
                }]) 
   {
      ... on TYPE {
      RESPONSE_FIELD_1
      RESPONSE_FIELD_2
      RESPONSE_FIELD_n
      }
   }
}

Fields and inputs

identity
The identity object is formed from the following field values to uniquely identify the entity to be retrieved:
namespace
Where NAMESPACE is the namespace where the external data is made available.
If defined at a higher level of the query, the namespace does not need to be separately specified here.
id
Where IDENTIFIER is the unique identifier provided by the external system.
type
Where TYPE refers to the external entity type.
localId
Where LOCAL_ID can be either a Publication ID or a locale string, such as 'en' or 'sv-se', which identifies a locale-specific variant of the entity.
eclUri
ECL-URI for the entity being requested.
When using the connector for integration with Content Manager and External Content Library (ECL), the ECL-URI can be used as an alternative to the identity parameter. It is normally something that comes from Tridion Sites in form of an ECL component link.
... on TYPE
Defines the query response, where:
  • TYPE is the entity type and matches the TYPE value in the identity section.
  • RESPONSE_FIELD_1 to RESPONSE_FIELD_n are the specific data fields that you want to be returned in the response.
The GraphQL type definition of the entity type determines which fields are available in a response.

Example request and response

The first sample code block illustrates a request to retrieve a product (the entity type) based on its identity. The second code block illustrates the corresponding response with with the requested product details:

RequestResponse
{
  externalItem(
    
    identity: {
      namespace: "ProductNamespace",
      id: "300046587",
      type:"Product",
      localeId: "de_DE"
    }
   
  ) {
    ... on Product {
      name
      summary
      description
      price {
        value
        currency
      }
    }
  }
}
{
  "data": {
    "externalItem": {
      "name": "Sonnenbrille Fox The Condition black grey",
      "summary": "The Condition von Fox verbindet Ästätik und Komfort",
      "description": "Features:\n <br /> leichter und 
widerstandsfähiger O-Matter Rahmen mit integriertem Gelenk 
und Metall Fox Head stoßfeste Plutonite Linsen\n <br />
100% UV-Schutz \n <br />High Definition Optics Technology.\n 
<br /> HDO Technology. \n <br /> \n <br /> Flush Mounted 
Plutonite Linsen",
      "price": {
        "value": "97.37",
        "currency": "EUR"
      }
    }
  }
}