跳转至

Action log（操作日志 (Action log)）

The action log models all action submissions as object types to be analyzed and displayed in object-aware Foundry tooling. Use an action log object type as an input to decision-making workflows and to monitor changes to your Ontology.

:::callout{theme="neutral"} The action log is designed to capture decisions made by submitting actions and make these decisions available as data in the Ontology. For use cases where logging all edits to an object is desired, edit history can be enabled for an object type. :::

Background

Actions are the primary way to modify the Ontology and trigger related side effects. Often, these Ontology modifications are the result of a specific decision or are accompanied by data audit requirements. The action log simplifies generation and maintenance of object types that represent these decisions and data edits. For easy identification, all action log object types are prefaced with [LOG].

Action log Ontology

Action log object types map one-to-one with action types. Submitting an action generates a single new object of the corresponding action log object type. This newly-created object is automatically linked to all objects edited by the submitted action. By modeling log object types one-to-one with action types, the action log supports capturing context beyond specific object edits, such as which other objects were concurrently edited and the state of the world (as represented by the Ontology) at the time of action submission.

For example, imagine a Close Alerts action type that modifies the "Status" property of many selected Alert objects to "Closed". When configured with an action log, closing 10 Alert objects at once will yield a single action log object with foreign key links to all 10 Alert objects.

:::callout{theme="neutral"} To apply an action log-backed action type, users need the appropriate permissions for the action log object type, just as they do for any other object types that the action type might create or modify through rules and functions. :::

Action log schema

By default, action log object types store:

  • Action RID: Unique identifier for a single action submission
  • Action type RID: Unique identifier for a single action type
  • Action type version: Version number that auto-increments each time an action type is updated
  • Timestamp: UTC timestamp of action submission
  • UserId: Multipass user ID for action submitting user
  • Edited objects: Primary key values of all objects edited by the action. Note that storing properties of edited objects other than the primary key is not supported.
  • [Optional] Summary: A customizable string to describe the action
  • [Optional] Parameter values
  • [Optional] Property values of object reference parameters (this is not supported for object reference parameters if allow multiple values is enabled)

Action log object types can be configured to store object properties that are not edited by the action. This allows you to store data edits as well as relevant information about the context of or motivation for the Ontology edits.

Returning to the example of a Close Alerts action type, imagine the Alert objects also have a "Priority" property containing values "High Priority" and "Low Priority" as well as a "Created at" timestamp and a "Source" machine. The action log supports storing these properties, even if they are not edited by Close Alerts. By aggregating on "Priority", without editing the column we can answer questions such as "where is the source of most "High Priority" alerts?" or "how long does it take to close "High Priority" alerts?".

Action log on function-backed action types

To configure the action log for a function-backed action type, the backing Ontology edit function must have Edits provenance configured. See the functions documentation for more information on Edits provenance.

Action log timeline

You can view action log object types in a timeline using a custom Workshop widget. With this widget, the timeline can be configured to support data audits in order to help answer the questions "what changed, by whom, and when?"

Within Workshop, action log object types can be unioned together for a holistic view of edits within a use case or across an Ontology.

Configure the action log timeline by selecting the edited object type. Then choose which action log object types to display, along with the desired action log object type properties.

中文翻译

操作日志 (Action log)

操作日志将所有操作提交建模为对象类型，以便在支持对象感知的 Foundry 工具中进行分析和展示。使用操作日志对象类型作为决策工作流的输入，并监控本体 (Ontology) 的变更。

:::callout{theme="neutral"} 操作日志旨在通过捕获操作提交所做出的决策，并将这些决策作为数据在本体中提供。如果需要对某个对象类型的所有编辑进行日志记录，可以为该对象类型启用编辑历史功能。 :::

背景

操作是修改本体并触发相关副作用的主要方式。通常，这些本体修改是特定决策的结果，或伴随数据审计需求。操作日志简化了代表这些决策和数据编辑的对象类型的生成与维护。为便于识别，所有操作日志对象类型均以 [LOG] 为前缀。

操作日志本体

操作日志对象类型与操作类型一一对应。提交一个操作会生成一个对应操作日志对象类型的新对象。这个新创建的对象会自动链接到该操作所编辑的所有对象。通过将日志对象类型与操作类型一一对应建模，操作日志能够捕获超出具体对象编辑范围的上下文信息，例如哪些其他对象被同时编辑，以及操作提交时的世界状态（由本体表示）。

例如，假设有一个"关闭警报"操作类型，它将多个选定的"警报"对象的"状态"属性修改为"已关闭"。当配置了操作日志后，一次性关闭 10 个"警报"对象将生成一个"操作日志"对象，该对象包含指向所有 10 个"警报"对象的外键链接。

:::callout{theme="neutral"} 要应用基于操作日志的操作类型，用户需要拥有操作日志对象类型的相应权限，就像他们需要拥有操作类型可能通过规则和函数创建或修改的任何其他对象类型的权限一样。 :::

操作日志模式 (Schema)

默认情况下，操作日志对象类型存储以下内容：

  • 操作 RID (Action RID)： 单个操作提交的唯一标识符
  • 操作类型 RID (Action type RID)： 单个操作类型的唯一标识符
  • 操作类型版本 (Action type version)： 每次更新操作类型时自动递增的版本号
  • 时间戳 (Timestamp)： 操作提交的 UTC 时间戳
  • 用户 ID (UserId)： 提交操作的用户的 Multipass 用户 ID
  • 已编辑对象 (Edited objects)： 操作所编辑的所有对象的主键值。请注意，不支持存储主键以外的已编辑对象属性。
  • [可选] 摘要 (Summary)： 用于描述操作的可自定义字符串
  • [可选] 参数值 (Parameter values)
  • [可选] 对象引用参数的属性值 (Property values of object reference parameters)（如果启用了"允许多个值"，则不支持对象引用参数）

操作日志对象类型可以配置为存储未被操作编辑的对象属性。这允许您存储数据编辑以及关于本体编辑上下文或动机的相关信息。

回到"关闭警报"操作类型的例子，假设"警报"对象还有一个包含"高优先级"和"低优先级"值的"优先级"属性，以及一个"创建时间"时间戳和一个"来源"机器。操作日志支持存储这些属性，即使它们未被"关闭警报"编辑。通过按"优先级"进行聚合，无需编辑该列，我们就可以回答诸如"大多数'高优先级'警报的来源是什么？"或"关闭'高优先级'警报需要多长时间？"等问题。

基于函数的操作类型的操作日志

要为基于函数的操作类型配置操作日志，底层的本体编辑函数必须配置 Edits 来源 (provenance)。有关 Edits 来源的更多信息，请参阅函数文档。

操作日志时间线 (Timeline)

您可以使用自定义 Workshop 组件在时间线中查看操作日志对象类型。通过此组件，可以配置时间线以支持数据审计，从而帮助回答"什么发生了变化、由谁更改、何时更改？"等问题。

在 Workshop 中，操作日志对象类型可以合并在一起，以在一个用例内或跨本体获得编辑的整体视图。

通过选择已编辑的对象类型来配置操作日志时间线。然后选择要显示的操作日志对象类型，以及所需的操作日志对象类型属性。