SoR Templates allow you to define and manage your System of Record integrations with SGNL through YAML files - one per SoR. YAML is a human-readable data serialization format commonly used for configuration files. SoR templates follow a predefined structure and allow you to define configuration/metadata, authentication mechanisms, and synchronization behavior. Moreover, you can also specify the schema for entities you would like SGNL to ingest as well as their attributes, attribute types and any relationships.
SoR Templates must be defined in a YAML file with each SoR defined in one YAML template.
The YAML format uses indentation and key-value pairs to represent data in a hierarchical fashion. Each level of indentation represents a nested structure, and key-value pairs are separated by colons. Lists are represented by using a hyphen followed by a space. More information about YAML can be found in the Official YAML documentation.
The SoR templates contains the components shown with Okta as an example:
The SoR Template structure along with supported fields in yaml format is shown below:
# Template for SoR # Required top-level section displayName: string icon: string description: string address: string defaultSyncFrequency: string defaultSyncMinInterval: integer defaultApiCallFrequency: string defaultApiCallMinInterval: integer type: string adapterConfig: string auth: - oAuth2ClientCredentials: clientId: string tokenUrl: string authStyle: string clientSecret: string scope: string - basic: username: string password: string - bearer: authToken: string # Section to define entities, attributes and relationships to ingest to SGNL entities: EntityName1: displayName: string externalId: string description: string syncFrequency: string syncMinInterval: integer apiCallFrequency: string apiCallMinInterval: integer pageSize: integer pagesOrderedById: boolean attributes: - name: string externalId: string description: string type: string indexed: boolean uniqueId: boolean list: boolean - name: string externalId: string description: string type: string indexed: boolean uniqueId: boolean list: boolean ... ... EntityName2: ... ... relationships: # entity relationships - name: string fromAttribute: string toAttribue: string # path relationships - name: string path: - relationship: string direction: string - relationship: string direction: string
|displayName||Display Name of the SoR used for identification||yes||string||none||Salesforce|
|icon||Base64 encoded SVG file to be used as SoR display icon||no||string||none||Example|
|description||Description for the SoR||no||string||none||Sales Cloud for Department Sales|
|address||API endpoint address on which SGNL will make calls to get data||yes||string||none||initech.my.salesforce.com|
|defaultSyncFrequency||Frequency at which SGNL will initiate data ingestion from the SoR. Works with defaultSyncMinInterval. If you want entities to be synchronized into SGNL every hour, defaultSyncFrequency should be set to HOURLY, and defaultSyncMinInterval should be set to 1||yes||string; one of SECONDLY, MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY, YEARLY||none||HOURLY|
|defaultSyncMinInterval||Works with defaultSyncFrequency. If you want entities to be synchronized into SGNL every hour, defaultSyncFrequency should be set to HOURLY, and defaultSyncMinInterval should be set to 1||yes||integer||1||1|
|defaultApiCallFrequency||Determines how often SGNL makes an API call to the SoR to get individual pages of data. Works with defaultApiCallMinInterval. If you want SGNL to make an API call every second to pull a page of entity records from the SoR, set defaultApiCallFrequency to SECONDLY and defaultApiCallMinInterval to 1||yes||string; one of SECONDLY, MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY, YEARLY||none||SECONDLY|
|defaultApiCallMinInterval||Determines how often SGNL makes an API call to the SoR to get individual pages of data. Works with defaultApiCallMinInterval. If you want SGNL to make an API call every second to pull a page of entity records from the SoR, set defaultApiCallFrequency to SECONDLY and defaultApiCallMinInterval to 1||yes||integer||1||1|
|type||System of Record type. Adapters are configured/implemented to use particular System of Record types. SoR types are based on the SoR API version being used in the adapter, the supported authentication mechanisms, and entities and attributes supported in the adapter.||yes||string||none||Jira-1.0.0|
|adapterConfig||Base64 encoded JSON string. The JSON can include any config that is useful for the adapter. For instance, it may contain specifics about SoR resource endpoints, proxy information, SoR version information, address to a central logging service, or any other information that is pertinent to the SoR and adapter.||yes||string||none||Example|
|auth||Authentication schemes that are applicable for this SoR||yes||list||none|
|oAuth2ClientCredentials||OAuth2 Client Credentials Flow Parameters||object||none|
|oAuth2ClientCredentials: clientId||OAuth2 ClientID||yes||string||none|
|oAuth2ClientCredentials: clientSecret||OAuth2 Client Secret||yes||string||none|
|oAuth2ClientCredentials: authStyle||Specify how the token is sent for authentication||yes||string; one of InParams, InBody, AutoDetect||none|
|oAuth2ClientCredentials: tokenUrl||OAuth2 Token URL||yes||string||none|
|oAuth2ClientCredentials: scope||OAuth2 Scope||no||string||none|
|bearer||Bearer token authentication||object||none|
|bearer: authToken||Auth Token||string|
SGNL integrates with various Systems of Record to ingest data that is necessary to build policies and make access decisions. In SGNL, each data type that is ingested is called an Entity. For instance, Users and Cases in ServiceNow or Jira are each an entity in SGNL. The fields in each entity are called Attributes. SGNL allows you to build policies and make access decisions based on Entity/Attribute values.
For more information on SoR Relationships, please check out the Entities and Relationships Explainer.
In the SoR YAML template, each entity is a separate object under the top-level entities field and is keyed by the entity name. For example, EntityName1 as shown in the SoR Template Structure section. The fields are listed below:
|displayName||Display name of the Entity||yes||string||none||User|
|externalId||Actual entity name in the SoR. The displayName can be different from the externalId. This allows us to have a user friendly/readable displayName that may be used in policies.||yes||string||none||User|
|description||Description of the entity||no||string||none||User entity for Salesforce|
|syncFrequency||Frequency at which SGNL will initiate data ingestion from the SoR for the entity. Works with syncMinInterval. If you want entities to be synchronized into SGNL every hour, syncFrequency should be set to HOURLY, and syncMinInterval should be set to 1. Overrides defaultSyncFrequency, if set.||no||string; one of SECONDLY, MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY, YEARLY||none||HOURLY|
|syncMinInterval||Works with syncFrequency. If you want entities to be synchronized into SGNL every hour, syncFrequency should be set to HOURLY, and syncMinInterval should be set to 1. Overrides defaultSyncMinInterval, if set.||no||integer||1||1|
|apiCallFrequency||Determines how often SGNL makes an API call to the SoR to get individual pages of data for the entity. Works with apiCallMinInterval. If you want SGNL to make an API call every second to pull a page of entity records from the SoR, set apiCallFrequency to SECONDLY and apiCallMinInterval to 1. Overrides defaultApiCallFrequency, if set.||no||string; one of SECONDLY, MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY, YEARLY||none||HOURLY|
|apiCallMinInterval||Determines how often SGNL makes an API call to the SoR to get individual pages of data. Works with apiCallMinInterval. If you want SGNL to make an API call every second to pull a page of entity records from the SoR, set apiCallFrequency to SECONDLY and apiCallMinInterval to 1. Overrides defaultApiCallMinInterva, if set||no||integer||1||1|
|pageSize||The number of records that the SoR should return per page or API call||no||integer||100||1000|
|pagesOrderedById||Boolean to indicate whether the SoR returns the data ordered by the ID that is unique and indexed||yes||boolean||none||false|
Every entity has a set of attributes. Each attribute is listed as a separate YAML object under the entities:attributes object as shown in the SoR Template Structure section.
|name||Name of the attribute||yes||string||none||userId|
|externalId||Actual name of the attribute in the SoR. The displayName can be different from the externalId. This allows us to have a user friendly/readable displayName for the attribute that may be used in policies.||yes||string||none||id|
|description||Description of the attribute||no||string||none||User ID|
|type||Data type of the attribute||yes||string; one of Bool, DateTime, Double, Duration, Int64, String||none||Int64|
|indexed||Whether the attribute must be indexed in the SGNL Graph. If the attribute is going to be used in policies, or is referred to in relationships, indexed MUST be set to true||no||boolean||false||false|
|uniqueId||Whether the attribute is unique. There must be EXACTLY ONE attribute in the entity that is unique. The attribute MUST also have indexed set to true, if unique is set to true.||no||boolean||false||false|
|list||Whether the attribute is a list||no||boolean||false||false|
SGNL integrates with various Systems of Record to ingest data that is necessary to build policies and make access decisions. In most cases, there are relationships between data belonging to the same or different Systems of Record. SGNL allows you to build policies and make access decisions based on these relationships as well.
In the SoR YAML template, you can list the relationships under the top-level relationships section. There are two kinds of relationships that may be defined:
Entity Relationship Fields
|name||Relationship name. Does not have to be unique.||yes||string||none|
|fromAttribute||Source Attribute in an Entity||yes||string||none||GroupMember.memberId|
|toAttribute||Target Attribute in an Entity||yes||string||none||User.userId|
Note: fromAttribute and toAttribute may belong to different entities.
Entity Relationships Reference Syntax:
The SGNL SoR YAML schema is flexible enough to allow you to reference attributes by name. The syntax uses a Dot notation to reference a specific attribute like so:
<Entity External ID>.<Attribute External ID>
For example, in the following YAML template snippet,
entities: UserEntities: displayName: UserEntity externalId: User ... ... attributes: - name: username externalId: username ... - name: email externalId: email_id ... ...
To reference the email attribute in the UserEntity, specify it as User.email_id.
Path Relationship Fields
|name||Path relationship name||yes||string||none|
|path||Contains a list of objects (relationships and directions)||yes||list||none|
|relationship||Name of the entity relationship. The YAML key is used instead of the relationship name||yes||string||none||GroupMember|
|direction||Direction of the relationship traversal||yes||String; one of FORWARD, BACKWARD||none||FORWARD|
In the following example YAML, UserMemberGroup is a path relationship that defines a path from User entity to Group entity. Note that the relationship values refer to the YAML key names and not the entity relationship name fields. For more information on Path relationships, please refer to our Entities and Relationships Help page.
relationships: UserMember: name: Member fromAttribute: GroupMember.memberId toAttribute: User.id MemberOf: name: MemberOf fromAttribute: GroupMember.groupId toAttribute: Group.id UserMemberGroup: name: Group path: - relationship: UserMember direction: Backward - relationship: MemberOf direction: Forward