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:
- List
- An Boolean indicator that the field is a list as opposed to a single value
- Required
- An Boolean indicator that the field is required when creating new entities
- ReadOnly
- An Boolean indicator that the field is read-only and cannot be set when creating or updating the entity
- Custom
- An Boolean indicator that the field is a custom as opposed to being part of a 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; }