Systems of Record Templates

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.

Template Structure

SoR Templates must be defined in a YAML file with each SoR defined in one YAML template.

Briefly about YAML Syntax

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
    parent: 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

SoR Top-Level Fields

SoR Auth Fields

oAuth2 Client Credentials Flow

Basic Authentication

Bearer Token Authentication

SoR Entities

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:

Parent and Child Entities

SoR Entity Attributes Fields

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.

JSONPath for External IDs

Some Systems of Record’s APIs return complex JSON data with multiple nestings. In such cases, you might want to refer to specific fields within the deeply nested JSON objects and ingest those fields as attributes to base your SGNL policies on.

For example, Jira Issues Search API sends a response as shown here. If one of the attributes for the Issue entity is author, and you want to set the value of author to the accountId, set name to author, and externalId to a JSONPath to extract the value of the accountId.

For this particular JSON structure, the accountId field appears within an array structure under the issues key. Since SGNL processes each JSON object in the array separately, to retrieve this value, the JSONPath expression would not have to navigate through the issues array, and refer to the relevant object directly. Given that each issue might have different sections containing an accountId field (like comments and worklogs), you need to specify the correct path. For the example case, the JSONPath expression would be something like $.fields.comment[*].author.accountId

It’s important to adjust the JSONPath expression based on the exact structure of your JSON and the location of the author field within it.

SoR Relationships

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:

1. Entity Relationships
2. Path Relationships

Entity Relationships

Entity Relationship Fields

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 Relationships

Path Relationship Fields

Parent Relationships

Parent Relationship Fields

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 documentation.

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

More on Templates in SGNL

For more information on how Templates are used to manage your Systems of Record in SGNL, watch the video below.