Source Adapter Interface

1. Adapter structure

ISourceAdapter: The data source (DB, service etc.) is configured based on the necessary attributes and credentials. After that, the source can be configured. ISource: The capabilities of an adapter instance can be retrieved from the business logic. This information comes from the adapter itself, not from the source. IActionCapabiliy: If this interface is implemented, then actions on classes, methods or instances can be performed. ISchemaCapability: With this schema interface the adapter analyzes the information/data source and returns the available schema. For example, the schema could be considered for a database source.

2. Adapter interfaces

2.1 Transfer models (common)

2.1.1 SourceResult

Every method call of the API returns an SourceResult object. There is always a property "Messages" in this object, which represents a list of error messages. In addition the SourceResult object could be contain a Result object from the current context.

public class SourceResult<TValue>
{
        public TValue Value { get; private set; }
        public List<SourceResultMessage> Messages { get; private set; }
}

SourceResult is the base result object that is beeing used for inheritance.

2.1.2 SourceRequest

In a SourceRequest object, a list of credentials for identification, authenticate and authorization of a data source can be entered. If a source or adapter supports transactions, You can also enter a transaction key here.

public class SourceRequest
{
    public List<SourceCredential> Credentials { get; set; }
       public object TransactionKey { get; set; }
}

2.1.3 Translation

The Translation object supports the multi-lingualism of the TIVITY platform. It is a list of Key-Value pairs, which contains:

parameter name	type	description
Key	str	country code
Value	str	text in the respective language

Example: translationObj[„en-EN“] = "text in language"

public class Translation : Dictionary <string, string> { }

2.2 ISourceAdapter

The interface must be implemented in every adapter. It provides basic methods:

• pass back information about the adapter ("define")

• allow configurations ("config")

• initializes the adapter ("connect")

2.2.1 Define

The Define method returns meta-information about the adapter: the name of the adapter, the description and a thumbnail (e.g. logo). All three properties are translation objects. Therefore, the information can be supported in all languages.

Task<SourceResult<AdapterDefinition>> Define(AdapterDefineRequest request);

Define Result:

    public sealed class AdapterDefinition
    {
        public Translation Name { get; set; }
        public Translation Description { get; set; }
        public Translation Thumbnail { get; set; }
    }

2.2.2 Config

The two Config methods can be used to control the configuration process. The process starts with a request object (AdapterConfigLaunchRequest), which can submit inital parameters to the adapter, but not necessarily required. Then you get back a list of parameters. They will be displayed on the plattform UI as formular fields. The required configuration settings are made on this form. With the second method the settings are sended as Key-Value pairs (Dictionary) to the adapter/service (request object "AdapterConfigHandleRequest").

Task<SourceResult<ConfigurationStep>> Config(AdapterConfigLaunchRequest request);
Task<SourceResult<ConfigurationStep>> Config(AdapterConfigHandleRequest request)

You now have the opportunity to check these inputs in the adapter itself and send back error messages or to send further parameters based on the previous entries. When the configuration is complete, a ConfigurationSuccess must be returned.

Success Response:

    public sealed class ConfigurationSuccess : ConfigurationStep
    {
        public string Configuration { get; private set; }

        public ConfigurationSuccess(string configuration)
        {
            Configuration = configuration;
        }
    }

2.2.3 Connect

A "Connect" initializes an adapter for an information source. The request object ("AdapterConnectRequest") contains the information of the previous configurations. As a result the interface ISource is returned, which represents the adapter. In fact, however, an map object ("SourceCapabilityMap") is expected in the server variant, which listed the information about the supported capabilities.

    Task<SourceResult<ISource>> Connect(AdapterConnectRequest request);

The AdapterConnectRequest has a Configuration property which structure and content is adapter dependent. Additionally an service factory can be transferred. This factory gives access to different services by querying them by their interface definition. Of course, this option cannot be used in the REST service.

    public class AdapterConnectRequest
    {
        public string Configuration { get; set; }
        public IServiceFactory ServiceFactory { get; set; }
    }

2.3 ISource

The interface retrieves information about the supported adapter capabilities. In addition, the concrete adapter can be returned as ISource interface (not the server variant!). Should be implemented with every adapter. Without the information of the capabilities an adapter can be present (initialized and configured), but has no functionality.

2.3.1 GetCapabilityMap

The GetCapabilityMap method returns a list of capability types. These types represent the capability interfaces implemented by the adapter. This information is important for the platform to know what capabilities an adapter brings.

Task<SourceResult<SourceCapabilityMap>> GetCapabilityMap(SourceCapabilityRequest request);

All available capability types:

Capability type	Interface
Action	IActionCapability
Authentication	IAuthenticationCapability
Document	IDocumentCapability
Model	IModelCapability
Preview	IPreviewCapability
Query	IQueryCapability
Schema	ISchemaCapability
Search	ISearchCapability
Thumbnail	IThumbnailCapability
Version	IVersionCapability

2.3.2 GetCapability<TCapability>

This Method is not supported in a adapter service (see example REST service). The interface of an adapter instance is returned. This is only possible with a straight adapter instantiation.

TCapability GetCapability<TCapability>()

NOT supported in REST Service!

2.4 IActionCapability

The interface IActionCapability has only one method "Execute" and belongs to the adapter capabilities. That means, this interface does not need to be implemented.

2.4.1 Execute

The method "Execute" is to be understood as a generic method call. On the one hand, in the object ("ActionExecuteRequest") it'll be specified the context for the call. These are the classes ("ClassName") that has the action, the Name of the action itself ("ActionName") and optinal the class instance identifier ("Key"). This allows different "Execute" calls to be performed on a particular class. These calls can be handled differently in the adapter instance. In addition, it is possible to pass a list of parameters (Dictionary). These correspond to the return parameters of a class method.

public class ActionExecuteRequest : SourceRequest
{
        public string ClassName { get; set; }
        public string ActionName { get; set; }
        public object Key { get; set; }
        public Dictionary<string, object> Parameters { get; set; }
}

The result returns an object of type object. In the server variant this could be a simple data type like string or integer. But also a serialized object in json format is possible. It should only be ensured that the calling class/instance inside the TIVITY platform can handle it.

Task<SourceResult<object>> Execute(ActionExecuteRequest request);

2.5 ISchemaCapability

There is only one method defined in the interface ISchemaCapability. This interface does not need to be implemented. It belongs to the adapter capabilities.

2.5.1 Get

(Meta-)Information about the object structure (class, fields and links) is determined with the method Get. No parameters are transferred in the request. The object SchemaGetRequest is empty and it doesn't necessary transmit data. The request model is also derived from SourceRequest as well. So it is possible to pass the credentials/transactions with the request.

Task<SourceResult<Schema>> Get(SchemaGetRequest request);

The result is a schema object. This contains the metadata of the available objects. These are the classes and links, each written as a list in the schema.

public class Schema
{
     public List<Class> Classes { get; set; }
    public List<Link> Links { get; set; }
}

Class: in every class exist the class name ("Name") and the class properties ("fields"). The fields are a list of field objects. A Field object contains the description data of the field:

parameter name	type	description
Name	str	Name of the field
Length	str	Max. field length (null = no limit)
DefaultValue	str	The value that set on a new instance
IsNullable	bool	If true, than the field is nullable (database)
NameIntern	str	label as known field
DataSourceOption	str	Options that apply to the field (separated by semicolon)
IsReadOnly	bool	If true, than the field cannot changed.
DataType	enum	Type of the field (string, integer etc.)

Link: the link objects represent a class and field link. a Link has the following description data;

parameter name	type	description
Name	str	Name of the Link
PrimaryClassName	str	Name/ID of the main class
ForeignClassName	str	Name/ID of the linked class
PrimaryFieldName	str	Name/ID of the main class field
ForeignFieldName	str	Name/ID of the linked class field

The meta-information in the Result schema now allows instances to be created and forwarded to the adapter with the CRUD operations.

2.6 IQueryCapability

The QueryCapability interface ensures that the desired class instances (model) are selected by using a filter. A model list (the class instances) is returned as the result. For this operation we need only one method.

2.6.1 Execute

The execute method searches for class instances in a repository or external source using a query object in request. This Query can be used in many ways. As a SQL statement or maybe a mapped filter object.

Task<SourceResult<ModelList>> Execute(QueryExecuteRequest request);

The QueryExecuteRequest has a query. This Query object consist of different query parts:

    public class Query
    {
        public From From { get; set; }
        public List<Join> Joins { get; set; }
        public List<Column> Columns { get; set; }
        public List<Condition> Conditions { get; set; }
        public Pagination Pagination { get; set; }
    }

parameter name	type	description
From	obj	defines a class to query data from
Columns	list	list of column objects to get from data to query
Conditions	list	list of conditions to filter the data
Joins	list	list of joins with filter and class
Pagination	obj	pagination data to reduce the amount of data to query

From

parameter name	type	description
ClassName	str	Name of the class
Alias	str	could be used for alias in SQL statement

Column

parameter name	type	description
Expression	obj	ExpressionField with Fieldname and class alias
Alias	str	could be used for alias in SQL statement

Condition

parameter name	type	description
LeftParentheses	int	set parentheses on left site
LeftExpression	Expression	the expression on left site
IsNegated	bool	true OR false
Operator	enum	well defined comparison operators
RightExpression	Expression	the expression on right site
RightParentheses	int	set parentheses on right site
LogicalOperator	enum	None, And, Or

As a result, a list of model objects is returned. The Model represents a dictionary with Key = FieldName and Value = FieldValue.

2.7 IModelCapability

The model capability united the basic function of persistent storage. These functions are:

• create or add a new entry

• update or edit existing entries

• delete or remove existing entries

This interface facilitate searching and changing information. For read/retrieve, view or search information please use the IQueryCapability interface. Usually the source is used to connect to databases. The IModelCapability interface consists of three methods.

    Task<SourceResult<Model>> Create(ModelCreateRequest request);
    Task<SourceResult> Update(ModelUpdateRequest request);
    Task<SourceResult> Delete(ModelDeleteRequest request);

2.7.1 Create

If you want to create or add a new entry, you need to transfer a class name and the entry (Model). The Model is in fact a simple dictionary consisting of class fields (Key) and the values. These details are included in the ModelCreateRequest. You get the information about the classes and the model structure when the schema capability method is called (see 5.5). As result the created model is returned.

    public class ModelCreateRequest : SourceRequest
    {
        public string ClassName { get; set; }
        public Model Model { get; set; }
    }

2.7.2 Update

To update an existing entry, send the class name of the class to be manipulated. Additional a key for value of the field to identify the model. And of course the entry with all changed fields.

    public class ModelUpdateRequest : SourceRequest
    {
        public string ClassName { get; set; }
        public object Key { get; set; }
        public Model Model { get; set; }
    }

2.7.3 Delete

At last you want delete the entry. Use the delete method and fill the ModelDeleteRequest with the class name and the key for value of the field to identify the model to delete.

    public class ModelDeleteRequest : SourceRequest
    {
        public string ClassName { get; set; }
        public object Key { get; set; }
    }

2.8 IDocumentCapability

This capability is used for getting a document content. The only method in the interface is a download method. If you need the properties for the document, such as the name of the document or the type, these can be saved in an instance of a class. This instance can then be retrieved using the Query method. After that you call the download method to get the content of the document.

    Task<SourceResult<Document>> Download(DocumentDownloadRequest request);

2.8.1 Download

To get a document, use the Download method. The request model has two properties. The name is used to specify the class assigned to the requested document. The Key value is the document identifier. This identifier can be a unique name, a path or a GUID. As result you get a document object. This (base) class is modified as abstract, so you can create your own document class that is inherited from the abstract class.

! The REST service returns a stream, not the document object.

    public class DocumentDownloadRequest : SourceRequest
    {
        public string ClassName { get; set; }
        public object Key { get; set; }
    }