Enhanced Auditing Capabilities

Purpose

This document describes the event payload data that can be contained in your audit data. You can query the audit information via the REST API of the iGrafx Process Design application.

Enabling the Enhanced Auditing Capabilities

CLOUD ONLY

This feature is for iGrafx hosted instances only (cloud deployments). To enable the feature, navigate to the Admin → Server Settings → Support tab. At the bottom of the tab there will be a toggle switch to toggle on/off the enhanced audit feature.

API Endpoint

The general API endpoint to retrieve your audit information is

CODE

https://YOUR_SUBDOMAIN.igrafxcloud.com/api/auditevents

Calling it without any additional parameters will return the last 24 hours of audit information, with the data format outlined below under General Payload Structure.

To query older data, you will have to append the query parameter secondThreshold to your URL. It determines the amount of historic audit data to retrieve, and by default is set to 86400 seconds (24 hours). For example, to retrieve the last 30 days of audit information, you can use the following URL:

CODE

https://YOUR_SUBDOMAIN.igrafxcloud.com/api/auditevents?secondThreshold=2592000

General Payload Structure

A general audit event will have the following data structure, and then custom data relevant to the specific type and category of the event. We describe the general structure here and provide additional examples of specific audit events for analysis in the table under Available Specific Data.

Basic Audit Event Payload

JS

{
        "uuid": "558ff7b4-7fd2-459c-9b2d-4a3d5d0fc306",
        "eventType": "loginsuccess",
        "eventCategory": "SECURITY",
        "eventData": {},
        "timestamp": "2023-08-08T04:26:58.919+00:00",
        "principal": "firstname.lastname@company.com",
        "authenticationType": "OAUTH2",
        "hostname": "abcdef123456",
        "platformVersion": "18.3.1.925-develop",
        "platformUuid": "fdc8450e-7774-4c8c-88ee-a0f6162aa616",
        "tenantId": "abcd1234"
}

The fields are as follows

Field name	Content/Purpose
`uuid`	Contains a unique identifier for the event
`eventType`	Specific event type (see Event Type column in the below table)
`eventCategory`	Category for the event (see Category column in the below table)
`eventData`	A custom payload that is different per event (see the below table)
`timestamp`	The timestamp of the event, either as ISO-8601 string or numeric timestamp
`principal`	The authenticated user or entity that triggered the event
`authenticationType`	The type of authentication the principal was using during this event (see Authentication Type column in the below table) The `authenticationType` property will give you security relevant information.
`hostname`	The name of the host of the Process Design instance The `hostname` property is mainly implemented for internal purposes and customers with multiple deployments/servers. It will not be relevant for most customers.
`platformVersion`	The version the Process Design app was running at the time of the event
`platformUuid`	Contains the unique identifier of the Process Design instance
`tenantId`	The unique tenant identifier for the Process Design instance (if present) The `tenantId` property is mainly implemented for internal purposes and customers with multiple deployments/servers. It will not be relevant for most customers.

Authentication Type

authenticationType	Description
`BASIC`	This authentication type signifies a “basic” sign on with a username and password
`OAUTH2`	When the principal uses OAuth2 to authenticate with Process Design
`SAML`	When the principal uses SAML to authenticate with Process Design
`APP_TOKEN`	IGrafx Access Management Service
`API_KEY`	When the principal uses an API Key to authenticate with Process Design

Available Specific Data

In addition to the generic fields listed above, each action may have additional information

User Action	Event Type	Category	eventData payload
Create Local User In Platform	`create-user`	`USER_MANAGEMENT`	CODE `"eventData": { "user": { "id": "637", "loginName": "firstname.lastname@company.com", "firstName": "Firstname", "lastName": "Lastname", "email": "firstname.lastname@company.com" } }`
Update User Details In Platform	`update-user`	`USER_MANAGEMENT`	CODE `"eventData": { "userBefore": { "firstName": "Old firstname", "lastName": "Old lastname", "loginName": "oldfirstname.oldlastname@company.com", "userDirectoryType": "LOCAL", "id": "637", "email": "oldfirstname.oldlastname@company.com", "enabled": "true" }, "userAfter": { "firstName": "New firstname", "lastName": "New lastname", "loginName": "newfirstname.newlastname@company.com", "userDirectoryType": "LOCAL", "id": "637", "email": "newfirstname.newlastname@company.com", "enabled": "false" } }`
Delete User In Platform	`delete-user`	`USER_MANAGEMENT`	CODE `"eventData": { "user": { "loginName": "firstname.lastname@company.com", "firstName": "Firstname", "lastName": "Lastname", "userDirectoryType": "LOCAL", "id": "637", "email": "firstname.lastname@company.com", "enabled": "true" } }`
Navigate to Object Tab in Platform Model Area	`load-object-tab`	`OBJECTS`	CODE `"eventData": { "objectId": "568331", "repository": "repo", "version": "-1", "tab": "itemprops" }`
Bulk operation requested	`create-bulk-operation`	`OBJECTS`	CODE `"eventData": { "bulkOperations": [ { "bulkOperationType": "Relationship_Remove", "objectIds": [223,1245], "changeParameters": [ { "relationshipType": "RACIC", "slot": 2, "targetObjectIds": [1236] } ] }, { "bulkOperationType": "Relationship_Add", "objectIds": [223,1245], "changeParameters": [ { "relationshipType": "RACIC", "targetObjectIds": [193,196] } ] } ] }`
View Web Diagram	`view-diagram-data`	`DIAGRAMMING`	CODE `"eventData": { "repository": "testRepo", "objectId": "9197", "version": "0" }`
View Full Diagram Narrative	`view-full-narrative`	`NARRATIVE`	CODE `"eventData": { "repository": "repo", "objectId": "9375", "objectVer": "0", "narrativeId": "21", "version": "0" }`
View Diagram SOP Narrative	`view-sop-narrative`	`NARRATIVE`	CODE `"eventData": { "repository": "repo", "diagramId": "9375", "diagramVersion": "6", "narrativeId": "21", "narrativeVersion": "0" }`
View Shape Narrative	`view-shape-narrative`	`NARRATIVE`	CODE `"eventData": { "repository": "repo", "diagramId": "7451", "diagramVersion": "1", "narrativeId": "1327", "narrativeVersion": "0", "shapeId": "121" }`
View Path Narrative	`view-path-narrative`	`NARRATIVE`	CODE `"eventData": { "repository": "repo", "diagramId": "8906", "diagramVersion": "2", "narrativeId": "21", "narrativeVersion": "0", "pathId": "1", "shapeIds": { "shape1": "4", "shape2": "6", "shape3": "7", "shape4": "8", "shape5": "9" } }`
Successful Login	`loginsuccess`	`SECURITY`	Not applicable
Changing a Feature Flag through the API	`set-feature-flag`	`SETTINGS`	CODE `"eventData": { "featureFlagGuid": "3gg45532-df8e-48ce-a41c-0427e7d75155", "setActive": "true" }`
Reading the Feature Flag Status	`get-feature-flag`	`SETTINGS`	CODE `"eventData": { "featureFlagGuid": "3gg45532-df8e-48ce-a41c-0427e7d75155" }`
Server role assigned to User/Group	`server-role-assigned`	`ROLE_MANAGEMENT`	CODE `"eventData": { "role": { "roleName": "server role", "roleId": "4" }, "userId": "3" }` *`userId` can also be `groupId` if the server role was assigned to a group instead of a user, like in the example.
Server role removed from a User/Group	`server-role-unassigned`	`ROLE_MANAGEMENT`	CODE `"eventData": { "role": { "roleName": "server role", "roleId": "9" }, "userId": "3" }` *`userId` can also be `groupId` if the server role was assigned to a group instead of a user, like in the example.
Repository role assigned to User/Group	`repository-role-assigned`	`ROLE_MANAGEMENT`	CODE `"eventData": { "repository": { "repositoryId": "1", "repositoryName": "Company" } "role": { "roleName": "repository role", "roleId": "4" }, "userId": "7" }` `userId` can also be `groupId` if the repository role was assigned to a group instead of a user, like in the example. *The `repository` block will NOT be present if the repository role applies to ALL repositories.
Repository role removed from a User/Group	`repository-role-unassigned`	`ROLE_MANAGEMENT`	CODE `"eventData": { "repository": { "repositoryId": "1", "repositoryName": "Company" } "role": { "roleName": "repository role", "roleId": "4" }, "userId": "7" }` `userId` can also be `groupId` if the repository role was assigned to a group instead of a user, like in the example. *The `repository` block will NOT be present if the repository role applies to ALL repositories.