logo
logo

Audit endpoints

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:

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

The querying endpoints support the following parameters:

NameTypeSample valueDescription
entityIdLong9962Id of the audited entity (optional)
fromDateTime2018-07-01T08:00ZStart DateTime
toDateTime2018-07-02T08:00ZEnd DateTime
fullTextStringAssetFull-text search phrase
skipInt0Paging: starts from given item index
takeInt10Paging: shows given number of items
sortStringTimeStampElasticsearch field to sort from
orderStringDescSort order: asc or desc

Response example:

{
  "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:

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:

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:

NameTypeSample valueDescription
scrollIdStringDXF1..U1QQ==Scroll id assigned by ES. This parameter is automatically appended to the next link in the response payload.
scrollTimeTimeSpanRawDetermines 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:

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

The generation endpoints support the following parameters:

NameTypeSample valueDescription
audit_typeStringRawOne of the following values: raw, business, scripting, action, or trigger
formatStringcsvOne of the following values: csv, json
fromDateTime2018-07-01T08:00ZStart DateTime
toDateTime2018-07-02T08:00ZEnd DateTime
filterDict{ "user_id": ["6"] }A set of filters applied to the selected audit index

Response headers:

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:

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:

NameTypeSample valueDescription
eventTypesStringEntityUpdatedType of audited event
definitionNamesStringM.AssetEntity definition name
userIdsLong1211User id
propertiesStringTitleFilters by changes done on provided property
relationsStringAssetToAssetMediaFilters by changes done on provided relation
cultureStringen-USCulture for response data

Example request:

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

Example response:

{
  "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:

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

The business query endpoints support the following parameters:

NameTypeSample valueDescription
logTypeStringuserauditFilters by the provided type
eventTypesStringuser.login.successEvent type. Possible values: Created, Updated, Deleted, Enabled, Disabled, or Executed.
createdByStringSampleUserUser who created the business entity
modifiesByStringSampleUserUser who last modified the business entity
usernameStringSampleUserUser making the query
definitionStringDefinition of the business entity
rawStringRaw Elasticsearch query (deprecated: parameter left for compatibility)

Request example:

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

Response example:

{
"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:

NameTypeSample valueDescription
log_typeStringuserauditOverrides 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:

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:

NameTypeSample valueDescription
scriptTypeStringUserPreRegistrationType of script. Possible values: UserPreRegistration, UserPostRegistration, UserSignIn, MetadataProcessing, or ActionScript.
scriptNameStringfooScriptScript name
scriptContentIdLong1234Id of the script content entity
scriptContentIdentifierStringzfSGGTUNhkKVdY9U-z49iQIdentifier of the script content entity
errorMessageStringFailedFragment of the error message
executionSourceStringAutomaticScripting execution source. Possible values: Automatic, Trigger, WebApi, Command, ExternalAction, or MassEdit.
idGuid0ccd58cf-c83f-42ba-907f-44d8950a20fdAudit message id
eventTypeStringCreatedEvent type. Possible values: Created, Updated, Deleted, Enabled, Disabled, or Executed.
severityStringWarningaudit entry severity. Possible values: Debug, Warning, Info, Error, or Fatal.
targetIdLong1234Id of the audited entity
targetIdentifierStringzfSGGTUNhkKVdY9U-z49iQIdentifier of the audited entity
userIdLong1234Id of the user who triggered the audit entry creation

Request example:

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

Response example:

{
  "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:

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:

NameTypeSample valueDescription
actionTypeStringApiCallType of action. Possible values: ApiCall, ActionScript, AzureEventHub, ReportingChannel, PrintEntityGeneration, StartBpmAutomation, StartSmAutomation, AzureServiceBus, or MAzureServiceBus.
actionPhasestringPrePhase the action is executed in. Possible values: Post, Pre, Security, Validation, Audit.
executionTypestringInProcessType of execution. Possible values: OutOfProcess or InProcess.
executionSourcestringTriggerSource of execution. Possible values: Unknown, Trigger, ExternalAction, Command, WebApi, MassEdit, or BPM.
executionTimeLong234The elapsed execution time in milliseconds
messageIdLong1234Message id
retryCountInt3Number of retries
successBooltrueWhether the action was successful
idGuid0ccd58cf-c83f-42ba-907f-44d8950a20fdAudit message id
eventTypestringCreatedEvent type. Possible values: Created, Updated, Deleted, Enabled, Disabled, or Executed.
severitystringWarningAudit entry severity. Possible values: Debug, Warning, Info, Error, or Fatal.
targetIdLong1234Id of the audited entity
targetIdentifierstringzfSGGTUNhkKVdY9U-z49iQIdentifier of the audited entity
userIdLong1234Id of the user who triggered the audit entry creation

Request example:

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

Response example:

{
    "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
        },
        ...]
      }

Can we improve this article ? Provide feedback