Entity change journal (changes)

Overview

Provides data from the domain center entity change journal based on the specified search conditions.

On each creation, modification, or deletion of a number of entities, information about the operation is recorded in the change journal. This happens only for descriptor entities marked in the specification as serviced by the domain center.

Retrieving all journal changes is impossible. At least one search condition must be specified.

The integration channel token (token_local) in the obj field is returned encrypted (ha_v=5;…​ if an installation key is set; Encryption and keys) or masked with a fingerprint *****#<8 hex>; likewise in the DMS platform/log/HistoryChanges and events. Journal records made before version 1.13 may contain plaintext tokens: after upgrading, reissue channel tokens if journals are accessible to outsiders. In some cases a combination of conditions is required. The system hints the required fields in the response body if the condition set is unsuitable.

For example, you can search all changes over a time interval, or all changes for a specific object.

Saving to the journal is enabled by the store_history_options setting (key journal/changes, enabled by default). The same setting (key platform/log/HistoryChanges) enables parallel history recording into the dynamic data model collection of the same name.

Requests

HTTP verb Endpoint Description

GET

/rest/v1/journal/changes

Getting data from the journal

Getting data from the journal

Request

Table 1. Request parameters
Name Type Description

params

object

Search conditions in the change journal. Search condition object fields.

filter

object

Filter by field values of discovered journal records.

mask

str

List of fields to output. Available fields for output: cmdtype, dtutc, modifierid, modifiername, source, objtype, objid, fields, obj.

To mask object fields (values of the obj field), specify them in flat format, for example: obj.id,obj.name,obj.opts.

offset

int

Offset in the list of resources to output. This is an additional offset relative to the offset in the search conditions.

limit

int

Maximum number of resources in the list. This is an additional limit relative to the limit in the search conditions

order

array<object|str>

Sorting order of resources in the list.

flat

bool

Transformation of composite fields to flat form. Applies to the object content — the value of the obj field.

Table 2. Search condition object fields
Name Type Description

dtstart

str

Start date and time of the interval.

In RFC3339 format in UTC, for example 2019-11-01T08:37:56Z. Other value formats are also accepted and are automatically converted to the required one.

dtstop

str

Start date and time of the interval.

In RFC3339 format in UTC, for example 2019-11-01T08:37:56Z. Other value formats are also accepted and are automatically converted to the required one.

cmdtype

str

Filter by operation type:

  • "create" – object created;

  • "update" – object modified;

  • "delete" – object deleted.

objtype

str

Filter by entity type. For example "user" or "ivrscript".

Used together with one of the objid and objkey conditions.

objid

str

Filter by object identifier.

For entities that have an identifier.

Used together with the objtype condition. Cannot be used together with objkey.

objkey

str

Filter by object key field.

For entities that do not have an identifier.

Used together with the objtype condition. Cannot be used together with objkey.

offset

int

Offset when outputting data from the DB.

limit

int

Limit on the amount of data output from the DB.

Example request
GET /rest/v1/journal/changes?params={"objtype":"user","objid":"3063e0ff-2ce8-2f4e-f5e0-00241dd9a031"} HTTP/1.1

Response

Table 3. Search condition object fields
Name Description

cmdtype

Object operation type. Value variants:

  • "create" – object created;

  • "update" – object modified;

  • "delete" – object deleted.

dtutc

Date and time of the operation. RFC3339 format in UTC.

modifierid

Identifier of the user account on whose behalf the operation was performed.

modifiername

Name of the user account on whose behalf the operation was performed. Recorded at the time of the operation.

source

Change source: ui – user by session (interface, REST and WebSocket collection API); token:<channel type> – integration channel token, for example token:public, token:mcp; script – script; system – platform service. Some operations (for example, changing one’s own password, uploading an avatar) are recorded with the system source or without a source. In the center journal, a change from another site preserves the source of the original site. The field is absent if the source is not determined (including records before version 1.13).

objtype

Entity type. For example "user" or "ivrscript".

objid

Entity identifier or key field.

fields

String with the names of object fields whose values changed. Fields are listed comma-separated. Composite field values by first-level keys are specified in flat mode, for example opts.roles.

The field is present only in "update" operation objects.

obj

Full object content, similar to the object output via API.

For operations

  • "create" and "update" – the object value after the operation is given.

  • "delete" – the object value before the operation is given.

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "cmdtype": "update",
    "dtutc": "2019-11-01T06:35:03.343Z",
    "modifierid": "71374fef-42f1-4e49-2069-faab905d4be2",
    "modifiername": "Administrator",
    "objtype": "user",
    "objid": "3063e0ff-2ce8-2f4e-f5e0-00241dd9a031",
    "fields": "name,opts.roles",
    "obj": {
      "id": "3063e0ff-2ce8-2f4e-f5e0-00241dd9a031",
      "login": "ivanov",
      "name": "Ivanov Alexey",
      "pwd": "*****",
      "timezone": "default",
      "opts": {
        "roles": ["admin"]
      },
      "ext": {
        "a": "1",
        "b": "asdfasdf",
        "c": 555.2,
        "d": 10,
        "e": {
          "x": 1,
          "y": "2",
          "z": false
        },
        "ct": "2019-08-01T07:02:01.52Z",
        "lwt": "2019-11-01T06:35:03.31Z"
      }
    }
  },
  {
    "cmdtype": "update",
    "dtutc": "2019-08-01T07:02:15.951Z",
    "modifierid": "71374fef-42f1-4e49-2069-faab905d4be2",
    "modifiername": "Administrator",
    "objtype": "user",
    "objid": "3063e0ff-2ce8-2f4e-f5e0-00241dd9a031",
    "fields": "opts.roles",
    "obj": {
      "id": "3063e0ff-2ce8-2f4e-f5e0-00241dd9a031",
      "login": "ivanov",
      "name": "Ivanov A",
      "pwd": "*****",
      "timezone": "default",
      "opts": {
        "roles": ["user"]
      },
      "ext": {
        "a": "1",
        "b": "asdfasdf",
        "c": 555.2,
        "d": 10,
        "e": {
          "x": 1,
          "y": "2",
          "z": false
        },
        "ct": "2019-08-01T07:02:01.52Z",
        "lwt": "2019-08-01T07:02:15.95Z"
      }
    }
  },
  {
    "cmdtype": "create",
    "dtutc": "2019-08-01T07:02:01.530Z",
    "modifierid": "71374fef-42f1-4e49-2069-faab905d4be2",
    "modifiername": "Administrator",
    "objtype": "user",
    "objid": "3063e0ff-2ce8-2f4e-f5e0-00241dd9a031",
    "obj": {
      "id": "3063e0ff-2ce8-2f4e-f5e0-00241dd9a031",
      "login": "ivanov",
      "name": "Ivanov A",
      "pwd": "*****",
      "timezone": "default",
      "opts": {},
      "ext": {
        "a": "1",
        "b": "asdfasdf",
        "c": 555.2,
        "d": 10,
        "e": {
          "x": 1,
          "y": "2",
          "z": false
        },
        "ct": "2019-08-01T07:02:01.52Z",
        "lwt": "2019-08-01T07:02:01.52Z"
      }
    }
  }
]

See also