Below are listed all models that are used by the Syncari’s Synapse SDK.
Core models
Synapse info
Synapse Info class is used in the synapse_info method. It allows for specifying the authentication and configurable UI fields of the custom synapse.
class SynapseInfo(BaseModel): name: str # API name of the Synapse (required). category: str # Synapse Category. metadata: UIMetadata # Optional UI Synapse elements. supportedAuthTypes: List[AuthMetadata] # Supported authentication types (required). configuredFields: Optional[List[AuthField]] # Additional configurable fields. oauthInfo: Optional[dict[str, str]] # oAuth configuration object. apiMaxCrudSize: Optional[int] # Maximum number of records that are passed to create, update and delete methods at each method invocation. When not set, the system will default to 20 records.
UIMetadata
UIMetadata class is used inside SynapseInfo class for configuring visual elements of the Synapse.
class UIMetadata(BaseModel): backgroundColor: Optional[str] # Sets the background color helpUrl: Optional[str] # Link to the Help article of the custom synapse
AuthMetadata
AuthMetadata class is used to set authentication types in the SynapseInfo class. Each synapse should have at least one insta AuthMetadata configured.
class AuthMetadata(BaseModel): authType: AuthType # Authentication type (required). fields: Optional[List[AuthField]] # List of UI fields that are needed for a given authentication. label: Optional[str] # UI Label for the authentication type
AuthType
AuthType ENUMS represents available authentication types that can be set in the AuthMetadata class.
class AuthType(Enum): BASIC_TOKEN = 'UserPasswordToken' # Basic authentication. USER_PWD = 'UserPassword' # Username Password authentication. API_KEY = 'ApiKey' # API key or single access token authentication. OAUTH = 'Oauth' # oAuth 2 authentication type with iFrame flow. SIMPLE_OAUTH = 'SimpleOAuth' # oAuth 2 authentication with client credentials or any authentication types where the credentials can expire and need to be requested again.
AuthField
AuthFeild class represents user configurable UI fields that can be set on SynapseInfo class. AuthFeild can be either added in the list of fields in AuthMetadata class for authentication related fields or in SynapseInfo under configuredFields list for any additional fields (dynamic endpoints for example). Fields not present in AuthConfig class will show under metaConfig dict if added under ConfiguredFields or additionalHeaders dict if added in AuthMetadata.
class AuthField(BaseModel): name: str # API name of the input field type. If set to any of the AuthConfig types the value will be populated in the authConfig object. Any other will show up in the metaConfig dictionary (required). dataType: DataType = DataType.STRING # Input field data type. (required). label: Optional[str] # UI label for the field. required: bool = True # Require setting for the input field, if not set it’ll default to required. defaultValue: Optional[str] # Optional default value for the input field. description: Optional[str] # Optional UI description for the input field.
Connection
Connection object is a persisting object that is handled by the Syncari platform. It is present with each Synapse invocation and includes authentication information inside authConfig object, entity related information in idFieldName, watermarkFieldName, createdAtFieldName, updatedAtFieldName and any additional fields configured in the UI inside metaConfig dictionary.
Connection object stores the information about the Synapse connection and persists through the framework. It is passed as an argument in the Test method and the method is also expected to return it. Its main use case is to access the authConfig object, which includes the authentication values that were imputed in the UI.
class Connection(BaseModel): name: str authConfig: AuthConfig idFieldName: Optional[str] watermarkFieldName: Optional[str] createdAtFieldName: Optional[str] updatedAtFieldName: Optional[str] oAuthRedirectUrl: Optional[str] metaConfig: Optional[dict[str, object]]
AuthConfig
AuthConfig class represents an object that persists inside the Connection object. Inside the framework will pass along the user input authentication fields and also allow in certain methods (test, get_token, refresh_token) to modify the values while running the Synapse’s code.
If you want to set a specific value of the object from the user input in the setup wizard the name of the field. For example if we want a user to set up the password it would be set as: AuthField(name='password', label='Password', dataType=DataType.PASSWORD).
If we use an AuthField name that isn’t present in the AuthConfig object those values will be stored in a dictionary metaConfig inside the Connection object. So for example if we set a value in the configuration wizard as: AuthField(name='specialValue', label='Endpoint URL', dataType=DataType.STRING)] this would be accessible in our framework as self.connection.metaConfig['specialValue'] instead inside the self.connection.authConfig object. Additionally please note that metaconfig values can be only set as in the configuredFields list and not under supportedAuthTypes list.
class AuthConfig(BaseModel): endpoint: Optional[str] userName: Optional[str] password: Optional[str] clientId: Optional[str] clientSecret: Optional[str] redirectUri: Optional[str] token: Optional[str] accessToken: Optional[str] refreshToken: Optional[str] expiresIn: Optional[str] lastRefreshed: Optional[datetime] additionalHeaders: Optional[dict[str, str]]
Record
Record object represents a single Syncari record. The object is returned by the Read method inside the ReadResponse object in the data field, or in a list of Record objects by the Get_By_Id method.
class Record(BaseModel):
name: Optional[str] # Entity name of the record (required).
id: Optional[str] # ID of the record in the external system (required).
syncariEntityId: Optional[str] # ID of the record in Syncari (required).
deleted: bool = False # Flag if the record is deleted.
values: dict[str, object] # Field values of the record (required).
lastModified: Optional[int] # Last modified date of the record (required).
createdAt: Optional[int] # Created date of the record.
Result
Result object represents a single CRUD operation result. It is expected to be returned as a list of Result objects in Create, Update and Delete methods.
class Result(BaseModel): success: bool = True # Field to indicate if the performed CRUD operation was successful. errors: Optional[List[str]] # Field to pass any error messages to. id: Optional[str] # ID of the record in the external system (required). syncariId: Optional[str] # ID of the record in Syncari (required).
Schema models
DataType
Data type represents ENUMS all the available field data types that entity attributes can be set as. The ENUMS also apply for AuthField.dataType options for AuthMetadata.fields and SynapseInfo.configuredFields.
class DataType(Enum): BOOLEAN = 'boolean' DECIMAL = 'decimal' DOUBLE = 'double' REFERENCE = 'reference' PICKLIST = 'picklist' STRING = 'string' DATETIME = 'datetime' TIMESTAMP = 'timestamp' INTEGER = 'integer' DATE = 'date' OBJECT = 'object' CHILD = 'child' PASSWORD = 'password' COMPLEX = 'complex'
Status
Optional status ENUM for both entities and attributes. If not set the default value will be ACTIVE.
class Status(Enum): ACTIVE = 'ACTIVE' INACTIVE = 'INACTIVE' DELETED = 'DELETED' PENDING = 'PENDING'
Picklist
Class for configuring a list of Picklist possible values. This is used in cases where it’s required to have picklist value with separate labels.
class Picklist(BaseModel): id: str label: Optional[str]
Attribute
Attribute class represents an Attribute object on each Entity in a schema (you can think of it as Columns on a table or key pairs on an object). Each Entity should have at least one Attribute set as isIdField and one set as isWatermarkField.
class Attribute(BaseModel): id: Optional[str] # Id of an Attribute. apiName: str # API name of an Attribute. This should mirror the incoming API names from the system you are integrating with (required). displayName: str # Display name of the Attribute (required). dataType: DataType = DataType.STRING # Data type of the attribute (required). custom: bool = False # UI flag in Schema studio to distinguish between default and custom fields. defaultValue: Optional[str] # Optional default value for a field. nillable: bool = True # Nillable flag can make a field required. By default the flag is set to TRUE which will mark the field as Required FALSE in the UI. If set to FALSE the required flag will be set to TRUE in the UI. Required fields need to be mandatorily mapped in the field pipelines. initializable: bool = True # If set to false together with updatable the field will be read-only. updateable: bool = True # If set to false together with initializable the field will be read-on createOnly: bool = False # Indicate in Schema Studio that it's create only field. calculated: bool = False # Indicate in Schema Studio that it's calculated field. unique: bool = False # Set the field field value as unique. length: Optional[int] # Character length of the field. precision: Optional[int] # Place to store percision information. scale: Optional[int] # Place to store scale information. status: Status = Status.ACTIVE # Status field of an Attribute. By default it’s set as ACTIVE. referenceTo: Optional[str] # Entity which the Attribute references to. For additional information please reed: link to the reference fields article. referenceTargetField: Optional[str] # Field of the entity where referenceTo points to. This can be considered as a foreign key. For additional information please reed: link to the reference fields article. referenceToPluralName: Optional[str] # Field to name the plural name of the entity where referenceTo points to. isSystem: bool = False # Flag to set a field as a system field (mostly used for created at and last modified date fields). isIdField: bool = False # This flag is reserved for Attributes that are unique identifiers for entities. Each entity should have one (required). compositeKey: Optional[str] # Name the composite key. isWatermarkField: bool = False # Flag to set an Attribute as a Watermark Field. Each entity should have one. In most cases they can be used together with isCreatedAtField or isUpdatedAtField fields. isCreatedAtField: bool = False # Flag to set an Attribute as a created date field. isUpdatedAtField: bool = False # Flag to set an Attribute as Last Modified date field. isMultiValueField: bool = False # Flag to set an Attribute as a multivalued field. This works with any DataTypes. externalId: Optional[str] # Optional external ID of the field. entityId: Optional[str] # Optional entity ID of the entity to which the field belongs to. picklistValues: Optional[List[str]] # List of string fields that will be made possible in the Picklist selection. picklist: Optional[List[Picklist]] # List of picklist object, where you can control the label and the value of each option.
Schema
Schema class represents a model for each Entity of the endsystem you are integrating with.
class Schema(BaseModel): id: Optional[str] # Id of an Entity. apiName: str # API name of Entity. This should mirror the incoming API names from the system you are integrating with (required). displayName: str # Display name of an Entity (required). pluralName: Optional[str] # Plural display name of an Entity. description: Optional[str] # Description name of an Entity (required). custom: bool = False # UI flag in Schema studio to distinguish between default and custom Entities. readOnly: bool = False # Flag to set a schema as read only. If this is set to true, destination nodes will not be available to the end user. version: Optional[int] # Optional version number of the schema. child: bool = False # Optional flag to set an entity as a child entity. For additional information please see: Link to child article # . attributes: List[Attribute] # List of attributes (fields) for an Entity.
Request Models
RequestType
Possible request types that a Synapse can receive. Based on the request type different methods in the Synapse class get executed.
class RequestType(Enum): SYNAPSE_INFO = 'SYNAPSE_INFO' TEST = 'TEST' REFRESH_TOKEN = 'REFRESH_TOKEN' GET_ACCESS_TOKEN = 'GET_ACCESS_TOKEN' DESCRIBE = 'DESCRIBE' READ = 'READ' GET_BY_ID = 'GET_BY_ID' CREATE = 'CREATE' UPDATE = 'UPDATE' DELETE = 'DELETE' EXTRACT_WEBHOOK_IDENTIFIER = 'EXTRACT_WEBHOOK_IDENTIFIER' PROCESS_WEBHOOK = 'PROCESS_WEBHOOK'
OffsetType
Possible offset types that can be used in the ReadResponse object that is returned by the read method.
class OffsetType(str, Enum): NONE = 'NONE', PAGE_NUMBER = 'PAGE_NUMBER', RECORD_COUNT = 'RECORD_COUNT', TIMESTAMP = 'TIMESTAMP', CUSTOM = 'CUSTOM'
Watermark
Watermark object is used to facilitate the Syncari pipeline sync in the Read method. It is passed to the method from the System as an argument inside the SyncRequest object and it is also expected to return it with the Read method inside the ReadResponse object.
class Watermark(BaseModel):
start: int # Epoch time in milliseconds that marks the start of the interval from where the system checks for updated records.
end: int # Epoch time in milliseconds that marks the end of the interval from where the system checks for updated records.
offset: Optional[int] # API page offset.
limit: Optional[int] # Number of API pages.
cursor: Optional[str] # API cursor.
isResync: bool = False # Marks if the triggered sync was incremental or a full sync of all records.
isTest: bool = False # Used when testing a pipeline for records changed in a given time frame.
initial: bool = False # Marks if the triggered sync was for the first time, since the synapse was connected.
ReadResponse
ReadResponse object is the object that the read method returns. It includes a list of Record objects that were returned from the method as a list in data field, watermark object and the type of offset that the API is using.
class ReadResponse(BaseModel):
data: Optional[List[Record]] # includes a list of Syncari records. This is present for create, update, delete and get_by_id methods.
watermark: Optional[Watermark] # object that is used for the read method for syncing purposes. It includes the following fields
offsetType: OffsetType # type of offset that the API is using (possible values: NONE, PAGE_NUMBER, RECORD_COUNT, TIMESTAMP, CUSTOM).
DescribeRequest
Describe request class that is provided as an argument for the Describe method. It can either include a list of entities or an empty one.
class DescribeRequest(BaseModel): entities: List[str]
SyncRequest
SyncRequest object is provided as an argument in all data related methods (Read, get_By_id, Create, Update, Delete):
class SyncRequest(BaseModel):
entity: Schema # includes the schema that is returned from the describe method. Object is always present.
data: Optional[List[Record]] # includes a list of Syncari records. This is present for create, update, delete and get_by_id methods.
watermark: Optional[Watermark] # object that is used for the read method for syncing purposes.
WebhookRequest
WebHookRequest object is passed as an argument to both webhook methods (extract_webhook_identifier and process_webhook). It includes all the data of an incoming webhook event.
class WebhookRequest(BaseModel):
body: str # Payload of the incoming webhook.
headers: Optional[dict] # Headers of the incoming webhook.
params: Optional[dict] # Endpoint params of the incoming webhook.
ErrorResponse
class ErrorResponse(BaseModel): status_code: int detail: Optional[str] message: str