Skip to main content

Shared types

Core types​

Tenant Id​

The tenant is represented by its tenantId, which is a globally unique identifier for the tenant in the system.

A tenant represents an organization or a group of users that share access to the same system and data boundary.
The tenant is used to separate data and access rights between other tenants and applications.

See IAM management for additional details.

Characteristics:

  • data boundary

Example:

const tenantId = '63c65dee83abd41be9f61108';

Audit information​

The audit information is a set of attributes used for track changes.

Characteristics:

  • Maintained by system
  • Can be queried

Attributes:

  • createdAt - timestamp telling when the entity was created
  • createdBy - Actor Id identifying who created the entity. Will be taken from the access token used when created the entity
  • lastModifiedAt - timestamp telling when the entity was lastly updated. Will initially be set to same timestamp as createdAt
  • lastModifiedBy - Actor Id identifying who updated the entity. Will be taken from the access token used when updated the entity Will initially be set to same Id as createdBy.

Example:

// Audit example
const audit = {
  createdAt: '2023-03-31T17:21:28.97Z',
  createdBy: '63d29842f0abf2120390cc58',
  lastModifiedAt: '2023-05-04T16:59:27.343Z',
  lastModifiedBy: '63d29842f0abf2120390cc58',
}

Change Id​

The changeIdis globally unique number represented in the API in a string.
The changeId is increased for on any data change in the system.

Characteristics:

  • Maintained by system
  • Globally unique
  • A number represented in a string
  • Use for data synchronization
  • Can be queried
  • Can be tailed

Example:

// Audit example
const entity = {
  foo: 'bar',
  changeId: '7229372992252280858',
}

Data synchronization​

Due to that the changeId increase on any change in the system. The last change in the system has the highest number. This behaviour makes the changeId ideal for maintaining replication of data.

Example of data synchronization flow:

  1. Do initial load and fill your local database
    1. Also store the changeId
    2. Keep track on the highest number of the changeId
  2. Listen for changes in the system and filter by entities with larger changeId than your highest (see Tailing concept for more information)
  3. When system returns updated / created entities with higher changeId
    1. Store them into your database.
    2. Update your highest changeId
    3. Go to step 2

Common types​

Type​

The type is a string used telling the kind of entity.

NOTE: The type cannot be updated or deleted. The type is set when the entity is created.

Characteristics:

  • Create-Read operations
  • Can be queried
  • Defined by client
  • Required

Example:

// Actor examples
const type = 'USER';
const type = 'VEHICLE';
const type = 'VACCUM_CLEANER';

// Node examples
const type = 'COUNTRY';
const type = 'DEPARTMENT';
const type = 'REPORT';

Name​

The name is a string used for naming an entity.

Characteristics:

  • Simple way for grouping entities
  • CRUD operations
  • Can be queried
  • Defined by client
  • Optional

Example:

// Actor example
const name = 'John Doe';

// Node example
const name = 'Sweden';

Description​

The description is a string used for describing an entity.

Characteristics:

  • CRUD operations
  • Can NOT be queried
  • Defined by client
  • Optional

Example:

const description = 'Sweden is a country in northen Europe'

Timestamp​

Timestamps in the system are identified by a string that follow the RFC3339 format.

Attributes:

  • Date - 2023-01-17
  • Time including milliseconds - 08:35:58.916
  • Offset - Z, +02:00, -01:00

Example:

// Utc timezone
const utc = '2023-01-17T08:35:58.916Z'

// Local timezone
const local = '2023-05-04T18:59:00+02:00'

Custom types​

Both the Actor and Node entities can be extended with custom data.
This allows you to add additional information to these entities that are specific to your application.

Custom id​

A custom id is a tenant unique identifier that is created and maintained by the client.

Characteristics:

  • Pair type/value is unique within the Tenant
  • CRUD operations per custom Id type
  • Can be used to identify an entity during an entity update / delete operation
  • Can be queried and sorted
  • Owned by client
  • Zero to many is supported
  • Optional

Attributes: A custom id consists of two parts

  1. type - a string the identifies the custom Id among others
  2. value - the actual Id value represented as a string

Example:

// VIN (Vehicle Identification number)
const vin = {
  type: 'VIN',
  value: '3B7HF13Z3B7HF13Z11M26988311M269883'
}

// SSN (social security number)
const ssn = {
  type: 'SSN',
  value: '123-45-6789'
}

Custom status​

Custom statuses is manage by the client and is a customizable way to manage an entity's status and life-cycle.

Characteristics:

  • Client defined status types
  • Client defined timestamp for status change
  • Audit information who did the change and when
  • A note that could describe why the status was changed
  • The history of all previous statuses including all attributes

Attributes: A custom status consists of:

  • type - a string the identifies the custom status among others
  • value - the actual status value
  • customStartedAt - client defined timestamp. Optional
  • note - a reason why status were changed. Optional
  • startedBy - Actor Id identifying who did the status change. Taken from access token
  • startedAt - system defined timestamp when change wae made
  • previousValues - an array of previous status values that the entity has had

Example:

// Address
const customVechicleStatus = {
  type: 'VEHICLE_STATUS',
  value: 'SOLD',
  createdAt: '2023-05-04T17:52:25.09Z',
  createdBy: '65f2bd99e410a04b36ef3685',
  statusFrom: '2023-05-04T19:52:00+02:00',
  note: 'Sold for €12 000',
  previousValues: [
    {
      value: 'DELIVERED',
      statusFrom: '2023-05-03T18:00:00+02:00',
      statusTo: '2023-05-04T19:52:00+02:00',
      createdAt: '2023-05-04T17:51:53.335Z',
      createdBy: '65f2bd99e410a04b36ef3685',
      replacedAt: '2023-05-04T17:52:25.09Z',
      replacedBy: '65f2bd99e410a04b36ef3685'
    }
  ]
};

Custom string​

A custom string is a queryable key-value combination that is created and maintained by the client.

Characteristics:

  • Pair type/value
  • CRUD operations per custom string type
  • Can be queried and sorted
  • Owned by client
  • Zero to many is supported
  • Optional

Attributes: A custom string consists of two parts

  1. type - a string the identifies the custom string among others
  2. value - the actual value represented as a string

The main difference between a custom string and a custom attribute is that the custom string is a key-value pair that can be queried and sorted.

Example:

const surname = {
  type: 'SURNAME',
  value: 'Smith'
}

const title = {
  type: 'TITLE',
  value: 'Dr.'
}

Custom attribute​

Custom attributes enable un-typed data to be attached to an entity. The structure of a custom attribute is defined by the client and can be any kind of JSON object.

Characteristics:

  • CRUD operations per custom attribute type
  • Flexible an stores un-typed data
  • Can NOT be queried
  • Owned by client
  • Zero to many is supported
  • Optional

Attributes: A custom attribute consists of two parts

  1. type - a string the identifies the custom attribute among others
  2. value - the actual JSON object containing the data

Example:

// Address
const address = {
  type: 'ADDRESS',
  value: {
    addresses: [
      {
        street: 'Anvenue 1',
        city: 'Gothenburg',
        country: 'Sweden',
        primary: false
      },
      {
        street: 'Downtown 10',
        city: 'Stockholm',
        country: 'Sweden'
      }
    ]
  }
};
Copyright © 2019 Akkess