Documentation Center

External entities

Connectors perform queries and operations on external data, or entities. An entity is a representation of a remote data structure, such as a multimedia object, external WCM content, a CRM contact, or an E-Commerce product.

Entity identity

Each entity has a unique identity, which is composed of the following elements:

Namespace ID
The namespace where the external data is made available. A connector can expose several namespaces with different setups, such as different end points or entity types. Typical namespaces are 'sapcommerce', 'salesforce' and 'poolparty'.
Entity Type
The general type of data represented by the entity, such as product, category, contact or concept.
Unique ID
The unique identifier provided by the external system. The external system defines the ID format.
Locale ID
An identifier for a locale-specific variant of the entity, such as a product ID for a specific market. The locale ID can either be a Tridion Sites publication ID or a locale string, such as 'en' or 'sv-se'. The connector is responsible for the actual locale value and mappings between locales and publication IDs.
Structure Type
A read-only value to identify the type of element that the entity represents in the structure, and one of the following: root item, container item or a leaf item. This value is available only as a returned value; therefore, it cannot be modified through a GraphQL mutation.

The following example code shows the constructor within an entity class that the entity's identity:

[Schema(Description: "My Entity")]
public class MyEntity : EntityBase
{
    public MyEntity(IEntityIdentity identity)
    {
        Identity = new EntityIdentity
        {
            NamespaceId = identity.NamespaceId,
            Id = identity.Id,
            LocaleId = identity.LocaleId,
            Type = identity.Type
        };
    }
...
 
}

Fields and properties

An entity exposes fields, which can be based on standard contracts for content, such as those that exist for multimedia content, or they can be custom fields defined by the Connector itself. An entity's fields are made available in the following ways:

  • External Content Library (ECL) – as metadata fields for the ECL item
  • Public Content API (Public Content API) – as fields made available to GraphQL types

Each field is defined as a set of properties. The following list describes all the possible properties that might be part of a field definition:

Name
The name of the field
Description
A general description of the field and its usage, which when used for PCA integration, is used to generate a field description for GraphQL.
Type
An indicator of the type of content the field can contain, which the following possible values:
  • Boolean – for fields whose values are either true or false
  • Integer – for numeric content with values that must be whole numbers
  • Float – for numeric content with a floating decimal point
  • String – for textual content
  • Date – for date and time fields indicating the local time (no time zone offset)
  • DateTimeOffset – for date and time fields with a time zone offset
  • BinaryReference – reference to a binary asset which can be downloaded through the connector
  • NestedSchema – a field that consists of other, nested (or embedded) fields
  • EntityReference – a field that contains a reference to another entity
List
An Boolean indicator that the field is a list as opposed to a single value
  • True – is a list
  • False – is single value
Required
An Boolean indicator that the field is required when creating new entities
  • True – is required
  • False – is optional
ReadOnly
An Boolean indicator that the field is read-only and cannot be set when creating or updating the entity
  • True – is read-only
  • False – is writable (default)
Custom
An Boolean indicator that the field is a custom as opposed to being part of a standard contract
  • True – custom field
  • False – standard contract
ContractQualifier
The name of the standard contract, which applies if the field is not custom, such as 'Multimedia', 'Product' and so on.
FieldConstraints
A set of constraints that controls what values will be allowed in the field, specified as a value range, a list of values or with regex expressions

The following example code illustrates the schema attributes within an entity class that are used to define the entity's fields and properties:


    [SchemaField(Required: true, Description: "Name of the entity")]
    [Regex("[A-Za-z ]+")]
    public string Name { get; set; }
 
    [SchemaField(Description: "Age of the entity")]
    [MinValue(0)]
    public int Age { get; set; }
 
    [SchemaField(Readonly: true, Description: "Factor property")]
    [MinValue(0.0f)]
    [MaxValue(100.0f)]
    public float Factor { get; set; }
 
    [SchemaField(Description: "Market price")]
    [FloatConstraints(TotalDigits: 5, FractionDigits: 2)]
    public double Price { get; set; }
 
    [SchemaField(Description: "Birthdate of the entity")]
    public DateTime BirthDate { get; set; }
 
    [SchemaField(Readonly: true, Description: "Entity image")]
    public IBinaryReference Image { get; set; }
 
    [SchemaField(Readonly: true, Description: "List of strings")]
    [AllowedValues(new []{"Arne", "Bengt"})]
    public IList<string> Strings { get; set; }