Audit endpoints

Version: 3.3

The list of available endpoints for querying audit indexes is available under /api/audit.

Note

You can also use the command line interface (CLI) and the tail command in particular to query logs.

Query

The endpoint base address template is:

RequestResponse

GET /api/audit/<index name>/query{/entityId}{?from,to,fullText,skip,take,sort,order}

The querying endpoints support the following parameters:

Name	Type	Sample value	Description
`entityId`	Long	9962	Id of the audited entity (optional)
`from`	DateTime	2018-07-01T08:00Z	Start DateTime
`to`	DateTime	2018-07-02T08:00Z	End DateTime
`fullText`	String	Asset	Full-text search phrase
`skip`	Int	0	Paging: starts from given item index
`take`	Int	10	Paging: shows given number of items
`sort`	String	TimeStamp	Elasticsearch field to sort from
`order`	String	Desc	Sort order: asc or desc

Response example:

RequestResponse

{
  "items": [
      ... documents  ...
  ],
  "total_items": 15,
  "returned_items": 10,
  "next": {
      "href": "<link to next page>",
      "title": ...
  },
  "previous": {
      "href": "<link to previous page>",
      "title": ...
  },
  "self": {
      "href": "<link to current page>",
      "title": ...
  }
}

Some endpoints have an additional set of parameters. The corresponding sections specify the differences.

Note

The asterisk (*) indicates that the URL expands into a list of key-value pairs, not a key with a list of values.

For example:

RequestResponse

Uri.expand("{?userIds*}", { userIds: [1, 2] })

expands into ?userIds=1&userIds=2 not ?userIds=1,2

Scroll

When in need of fetching more items than Elasticsearch (ES) querying allows, you need to use the scroll API. It allows paging only in one direction and works similarly to the entities scroll endpoint.

The endpoint base address template is:

RequestResponse

GET /api/audit/<index name>/scroll{/entityId}{?scrollTime,scrollId,from,to,fullText,skip,take,sort,order}

Each scroll endpoint accepts the same set of parameters as its corresponding query endpoint.

The scroll endpoints support the following parameters:

Name	Type	Sample value	Description
`scrollId`	String	DXF1..U1QQ==	Scroll id assigned by ES. This parameter is automatically appended to the `next` link in the response payload.
`scrollTime`	TimeSpan	Raw	Determines how long the created scroll stays alive in ES. When not provided, the value is taken from the `reporting` section of the centralized configuration (default 5000ms).

Generate

To place a download order for the entire log or its subset, use generation endpoints.

The endpoint base address template is:

RequestResponse

POST /api/audit/<index name>/generate

The generation endpoints support the following parameters:

Name	Type	Sample value	Description
`audit_type`	String	Raw	One of the following values: raw, business, scripting, action, or trigger
`format`	String	csv	One of the following values: csv, json
`from`	DateTime	2018-07-01T08:00Z	Start DateTime
`to`	DateTime	2018-07-02T08:00Z	End DateTime
`filter`	Dict	{ "user_id": ["6"] }	A set of filters applied to the selected audit index

Response headers:

RequestResponse

Location: <url to download order>

Raw query

The raw query fetches the raw audit index that contains entities like property and relation changes.

The endpoint base address template is:

RequestResponse

GET /api/audit/raw/query{/entityId}{?eventTypes*,definitionNames*,userIds*,properties*,relations*,culture,from,to,fullText,skip,take,sort,order}

The raw query endpoints support the following parameters:

Name	Type	Sample value	Description
`eventTypes`	String	EntityUpdated	Type of audited event
`definitionNames`	String	M.Asset	Entity definition name
`userIds`	Long	1211	User id
`properties`	String	Title	Filters by changes done on provided property
`relations`	String	AssetToAssetMedia	Filters by changes done on provided relation
`culture`	String	en-US	Culture for response data

Example request:

RequestResponse

GET /api/audit/raw/query?eventTypes=EntityUpdated

Example response:

RequestResponse

{
  "items": [
          {
              "event_type": "EntityUpdated",
              "message_id": 56272,
              "username": "SampleUser",
              "data": {
                  "name": "User:6",
                  "definition": "User",
                  "version": 24,
                  "cultures": [
                      "invariant"
                  ],
                  "is_new": null,
                  "user_id": null,
                  "usergroup_id": null,
                  "rules": null,
                  "property_changes": [
                      {
                          "property": "LastLoginDateTime",
                          "data_type": "System.DateTimeOffset",
                          "value": {
                              "original": "2021-04-19T09:26:43.3713536Z",
                              "new": "2021-04-19T09:34:32.018373Z"
                          }
                      }
                  ],
                  "relation_changes": []
              },
              "audit_type": "Raw",
              "target_definition": "User",
              "target_id": 6,
              "timestamp": "2021-04-19T09:34:32.053Z",
              "user_id": 6
          },
          ...]
}

Business query

The business query fetches the business audit index.

The endpoint base address template is:

RequestResponse

GET /api/audit/business/query{/entityId}{?logType*,raw,from,to,fullText,skip,take,sort,order}

The business query endpoints support the following parameters:

Name	Type	Sample value	Description
`logType`	String	useraudit	Filters by the provided type
`eventTypes`	String	user.login.success	Event type. Possible values: Created, Updated, Deleted, Enabled, Disabled, or Executed.
`createdBy`	String	SampleUser	User who created the business entity
`modifiesBy`	String	SampleUser	User who last modified the business entity
`username`	String	SampleUser	User making the query
`definition`	String		Definition of the business entity
`raw`	String		Raw Elasticsearch query (deprecated: parameter left for compatibility)

Request example:

RequestResponse

GET /api/audit/business/query?logType*==useraudit

Response example:

RequestResponse

{
"items": [
    {
        "event_type": "user.login.success",
        "created_by": "SampleUser",
        "modified_by": "SampleUser",
        "created_on": "2018-11-29T13:36:11.7964771Z",
        "modified_on": "2021-04-19T09:45:25.1231815Z",
        "username": "SampleUser",
        "log_type": "useraudit",
        "browser_information": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.72 Safari/537.36",
        "geoip": {
            "continent_name": "Europe",
            "region_iso_code": "BE-VBR",
            "city_name": "Halle",
            "country_iso_code": "BE",
            "region_name": "Flemish Brabant Province",
            "location": {
                "lon": 4.2345,
                "lat": 50.7338
            }
          }
        },
        ...]
}

Business generate

The business generate endpoints support the following parameters:

Name	Type	Sample value	Description
`log_type`	String	useraudit	Overrides the filter property to set the provided log type as a filter.

Scripting query

The scripting query fetched the scripting audit index.

The endpoint base address template is:

RequestResponse

GET /api/audit/scripting/query{/entityId}{?scriptType,scriptName,scriptContentId,scriptContentIdentifier,errorMessage,executionSource,id,eventType,severity,targetId,targetIdentifier,userId,from,to,fullText,skip,take,sort,order}

The scripting query endpoints support the following parameters:

Name	Type	Sample value	Description
`scriptType`	String	UserPreRegistration	Type of script. Possible values: UserPreRegistration, UserPostRegistration, UserSignIn, MetadataProcessing, or ActionScript.
`scriptName`	String	fooScript	Script name
`scriptContentId`	Long	1234	Id of the script content entity
`scriptContentIdentifier`	String	zfSGGTUNhkKVdY9U-z49iQ	Identifier of the script content entity
`errorMessage`	String	Failed	Fragment of the error message
`executionSource`	String	Automatic	Scripting execution source. Possible values: Automatic, Trigger, WebApi, Command, ExternalAction, or MassEdit.
`id`	Guid	0ccd58cf-c83f-42ba-907f-44d8950a20fd	Audit message id
`eventType`	String	Created	Event type. Possible values: Created, Updated, Deleted, Enabled, Disabled, or Executed.
`severity`	String	Warning	audit entry severity. Possible values: Debug, Warning, Info, Error, or Fatal.
`targetId`	Long	1234	Id of the audited entity
`targetIdentifier`	String	zfSGGTUNhkKVdY9U-z49iQ	Identifier of the audited entity
`userId`	Long	1234	Id of the user who triggered the audit entry creation

Request example:

RequestResponse

GET /api/audit/scripting/query?scriptType==UserPreRegistration

Response example:

RequestResponse

{
  "items": [
       {
           "script_type": "ActionScript",
           "script_name": "CMP - Create public links for linked assets",
           "script_content_id": 30459,
           "script_content_identifier": "gqQwt42TR0-H053IJPX5KQ",
           "execution_time": 2343,
           "execution_source": "Trigger",
           "context_data": {
               "data": {},
               "execution_event": null,
               "execution_phase": null,
               "execution_source": "Trigger",
               "execution_type": "OutOfProcess",
               "result": {},
               "target": "Asset",
               "target_id": 31523,
               "target_type": null
             }
           },

           ...]
         }
       }

Action query

The action query fetches the action audit index.

The endpoint base address template is:

RequestResponse

GET /api/audit/action/query{/entityId}{?actionType,actionPhase,executionType,executionSource,executionTime,messageId,retryCount,success,id,eventType,severity,targetId,targetIdentifier,userId,from,to,fullText,skip,take,sort,order}

The action query endpoints support the following parameters:

Name	Type	Sample value	Description
`actionType`	String	ApiCall	Type of action. Possible values: ApiCall, ActionScript, AzureEventHub, ReportingChannel, PrintEntityGeneration, StartBpmAutomation, StartSmAutomation, AzureServiceBus, or MAzureServiceBus.
`actionPhase`	string	Pre	Phase the action is executed in. Possible values: Post, Pre, Security, Validation, Audit.
`executionType`	string	InProcess	Type of execution. Possible values: OutOfProcess or InProcess.
`executionSource`	string	Trigger	Source of execution. Possible values: Unknown, Trigger, ExternalAction, Command, WebApi, MassEdit, or BPM.
`executionTime`	Long	234	The elapsed execution time in milliseconds
`messageId`	Long	1234	Message id
`retryCount`	Int	3	Number of retries
`success`	Bool	true	Whether the action was successful
`id`	Guid	0ccd58cf-c83f-42ba-907f-44d8950a20fd	Audit message id
`eventType`	string	Created	Event type. Possible values: Created, Updated, Deleted, Enabled, Disabled, or Executed.
`severity`	string	Warning	Audit entry severity. Possible values: Debug, Warning, Info, Error, or Fatal.
`targetId`	Long	1234	Id of the audited entity
`targetIdentifier`	string	zfSGGTUNhkKVdY9U-z49iQ	Identifier of the audited entity
`userId`	Long	1234	Id of the user who triggered the audit entry creation

Request example:

RequestResponse

GET /api/audit/action/query?actiontype==ApiCall

Response example:

RequestResponse

{
    "items": [
        {
            "action_type": "StartSmAutomation",
            "action_phase": "Post",
            "execution_type": "InProcess",
            "execution_source": "Trigger",
            "execution_time": 8,
            "target_name": "CMP - Content approval action",
            "retry_count": 0,
            "success": true,
            "entity_id": 33232,
            "id": "42e0ca85-87d1-437b-9df8-3decbadd1bf8",
            "audit_type": "Action",
            "event_type": "Executed",
            "severity": "Info",
            "target_id": 9878,
            "target_identifier": "M.Action.CMP.Content.Approval",
            "timestamp": "2021-04-19T10:42:09.8503118Z",
            "user_id": 6
        },
        ...]
      }

Do you have some feedback for us?

If you have suggestions for improving this article,