Skip to content

Objects and Schemas For Your Connector

This guide will help you understand the various objects that a connector will provide and how to properly attribute them in your connector.

Available Attributes

The main JSON attributes we provide fall into two categories: metadata and validation. The metadata attributes are more for clarity in terms of how the properties are represented and what they are for. The validation attributes are used for validating that the data that is provided for the objects meets the requirements of what should be provided.

This is not exhaustive, but it provides the most common use cases. For more see json-everything's Schema Generation

Metadata Attributes

  • Title: The title attribute gives us a value that can be used in place of the property name. Used to improve readability if the property name is abbreviated or lacking context to the property or class.
  • Description: The description attribute gets used to give the user more information on what the property is, hopefully making it more clear how to populate it.
  • JsonPropertyName: Allows you to override the property name that will be chosen when the object gets serialized to JSON. (Only for properties)

An Example of the usage of the attributes on an object and a property:

[Title("Equipment V1 Action Processor Configuration")]
[Description("Configuration of the data object actions for the module.")]
public class EquipmentV1ActionProcessorConfig
{
    [Title("Add Equipment Action handler Configuration")]
    [Description("Configuration object for the add equipment action.")]
    [JsonPropertyName("addEquipmentConfig")]
    public AddEquipmentHandlerConfig AddEquipmentConfig { get; set; }
}

Validation Attributes

  • Required: Can be set on a property that needs to be provided. T
  • Nullable(true/false): Can be set to tell whether or not the property can be nullable. By default the JsonSchema defaults the properties to not be nullable. Even if you mark your property with a ? to indicate it is nullable at compile time, you'll need to set this attribute to true for your property for the Schema to recognize it as nullable. 
[Required]
public Guid Id { get; set; }

[Nullable(true)]
public Guid? CategoryId { get; set; }

Strings

  • MaxLength(int): Allows a maximum length to be set for the property
  • MinLength(int): Allows a minimum length to be set for the property
  • Pattern(string): Allows a regex to be applied to a property to make sure that the value matches the pattern.
[MaxLength(5), MinLength(3)]
public string? CostCenter { get; set; }

[Pattern(@"^(\+\d{1,2}\s)?\(?\d{3}\)?[\s.-]\d{3}[\s.-]\d{4}$")]
public string? PhoneNumber { get; set; }

Numbers

  • Maximum: Sets the maximum value a property can be set to.
  • Minimum: Sets the minimum value a property can be set to.
[Maximum(500), Minimum(1)]
public int? Length { get; set; }

Objects to attribute

Connector Registration Configuration

This object is provided by the template for you, and it contains some data objects to help get you started.

The title and description are used in the Xchange UI for clarity on what the properties are for. The Validation attributes will be used to validate the supplied configuration against the schema prior to it being used. An invalid configuration will stop the connector from fully starting with error messages indicating what was invalid in the configuration.

Service Configuration

The service configurations are created when an new module is created for your connector, and there will be one for each type of service: Cache writer configuration and Action Processor configuration

Similar to the Connector Registration Configuration in that the title and description are used for clarity, and validation is used to make sure that the service is properly configured prior to execution. Some additional notes on both kinds of configuration are below:

Cache Writer

This configuration by default will contain a Configuration property for each data object of type CacheWriterObjectConfig. If you want to allow more configuration for your data objects, you can extend this configuration type and add additional properties.

The CacheWriterObjectConfig property is necessary because it provides a property UploadObject that gives the user with a way to enable/disable that particular data object's cache writer from uploading data to the cache. A connector may contain a large number of data objects, and it's quite possible an integration is only going to need a subset of those objects. This allows the data types to be turned off to limit the amount of data uploaded into the Xchange platform.

public class EquipmentV1CacheWriterConfig
{
    // Data Reader configuration
    [Title("Equipment")]
    public CacheWriterObjectConfig EquipmentConfig { get; set; } = new();
}

Action Processor

This configuration by default will contain a Configuration property for each action of each data object of type DefaultActionHandlerConfig. If you want to allow more configuration for your data objects, you can extend this configuration type and add additional properties.

The DefaultActionHandlerConfig property is necessary because it provides a property ProcessQueuedEvent that gives the user with a way to enable/disable that particular action from being performed by the system. A connector may contain a large number of actions for the data objects, and it's quite possible an integration is only going to need a subset of those actions. This allows the actions to be turned off to limit the amount of data processed in the Xchange platform.

public class EquipmentV1ActionProcessorConfig
{
    // Action Handler configuration
    [Title("Add Equipment Action handler Configuration")]
    public DefaultActionHandlerConfig AddEquipmentConfig { get; set; } = new();
}

Data Objects

For The data objects that are uploaded into the cache, the schema is used for validation that it is properly formed before it's entered into the cache. In addition it should mean that all data in the cache matches the schema.

This schema validation happens on the Xchange platform.

Action Objects

For your action objects, the ones that implement the IAction<> interface, the reference types that are used for the input, output, and failure cases. All of these will be validated when passed to the Xchange platform. It will allow you and your integrators to know when any of the objects are not properly formed.

In addition to the validation, the metadata attributes will help those building integrations or testing flows better understand what the properties are for.