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 Cloud instances only. It is enabled by default. To toggle the feature, navigate to the Admin → Server Settings → Support tab. At the bottom of the page there will be a toggle switch.

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

JSON

{
        "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
`SYSTEM`	Used for internal/automated actions of Process Design

Available Event Data

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

USER_MANAGEMENT

User Action

Event Type

Category

eventData payload

Create Local User In Platform

create-user

USER_MANAGEMENT

JSON

"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

JSON

"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

JSON

"eventData": {
    "user": {
        "loginName": "firstname.lastname@company.com",
        "firstName": "Firstname",
        "lastName": "Lastname",
        "userDirectoryType": "LOCAL",
        "id": "637",
        "email": "firstname.lastname@company.com",
        "enabled": "true"
    }
}

OBJECTS

User Action

Event Type

Category

eventData payload

Navigate to Object Tab in Platform Model Area

load-object-tab

OBJECTS

JSON

"eventData": {
    "objectId": "568331",
    "repository": "repo",
    "version": "-1",
    "tab": "itemprops"
}

Bulk operation requested

create-bulk-operation

OBJECTS

JSON

"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]
            	}
        	]
    	}
	]
}

DIAGRAMMING

User Action	Event Type	Category	eventData payload
View Web Diagram	`view-diagram-data`	`DIAGRAMMING`	JSON `"eventData": { "repository": "testRepo", "objectId": "9197", "version": "0" }`

NARRATIVE

User Action	Event Type	Category	eventData payload
View Full Diagram Narrative	`view-full-narrative`	`NARRATIVE`	JSON `"eventData": { "repository": "repo", "objectId": "9375", "objectVer": "0", "narrativeId": "21", "version": "0" }`
View Diagram SOP Narrative	`view-sop-narrative`	`NARRATIVE`	JSON `"eventData": { "repository": "repo", "diagramId": "9375", "diagramVersion": "6", "narrativeId": "21", "narrativeVersion": "0" }`
View Shape Narrative	`view-shape-narrative`	`NARRATIVE`	JSON `"eventData": { "repository": "repo", "diagramId": "7451", "diagramVersion": "1", "narrativeId": "1327", "narrativeVersion": "0", "shapeId": "121" }`
View Path Narrative	`view-path-narrative`	`NARRATIVE`	JSON `"eventData": { "repository": "repo", "diagramId": "8906", "diagramVersion": "2", "narrativeId": "21", "narrativeVersion": "0", "pathId": "1", "shapeIds": { "shape1": "4", "shape2": "6", "shape3": "7", "shape4": "8", "shape5": "9" } }`

SECURITY

User Action	Event Type	Category	eventData payload
Successful Login	`loginsuccess`	`SECURITY`	Not applicable

SETTINGS

User Action	Event Type	Category	eventData payload
Changing a Feature Flag through the API	`set-feature-flag`	`SETTINGS`	JSON `"eventData": { "featureFlagGuid": "3gg45532-df8e-48ce-a41c-0427e7d75155", "setActive": "true" }`
Reading the Feature Flag Status	`get-feature-flag`	`SETTINGS`	JSON `"eventData": { "featureFlagGuid": "3gg45532-df8e-48ce-a41c-0427e7d75155" }`
Feature Flag set for repository	`set-repository-feature-flag`	`SETTINGS`	JSON `"eventData": { "featureFlagGuid": "3gg45532-df8e-48ce-a41c-0427e7d75155", "allRepositories": false, "repositories": [ "repositoryId": 1, "repositoryName": "repo" ] }` The `repositories` array will only be present if `allRepositories` is `false`. *This only audits the changes in repositories for the feature flag. The feature flag being turned on/off will still be audited under `set-feature-flag`.
A new server setting is created	`server-setting-create`	`SETTINGS`	JSON `"eventData": { "newValue": "true", "setting": "igrafx.defaults.newuserlocale" }` Values for sensitive settings will be redacted to: `*******`.
A server setting is updated	`server-setting-update`	`SETTINGS`	JSON `"eventData": { "newValue": "true", "oldValue": "false", "setting": "igrafx.defaults.newuserlocale" }` Values for sensitive settings will be redacted to: `*******`.
A server setting is deleted	`server-setting-delete`	`SETTINGS`	JSON `"eventData": { "oldValue": "false", "setting": "igrafx.defaults.newuserlocale" }` Values for sensitive settings will be redacted to: `*******`.

ROLE_MANAGEMENT

User Action	Event Type	Category	eventData payload
Server role created	`server-role-create`	`ROLE_MANAGEMENT`	JSON `"eventData": { "roleId": "{roleId}", "roleName": "{roleName}" }`
Server role updated	`server-role-update`	`ROLE_MANAGEMENT`	JSON `"eventData": { "roleId": "{roleId}", "rights": [ "ManageEndorse", "ManageRequiredWatchers" ] "roleName": "{roleName}" }` *The rights will be the entire list of granted permissions at the time of the update.
Server role deleted	`server-role-delete`	`ROLE_MANAGEMENT`	JSON `"eventData": { "roleId": "{roleId}", "rights": [ "ManageEndorse", "ManageRequiredWatchers" ] "roleName": "{roleName}" }` *The rights will be the entire list of granted permissions at the time of deletion.
Server role assigned to User/Group	`server-role-assigned`	`ROLE_MANAGEMENT`	JSON `"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`	JSON `"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 created	`repository-role-create`	`ROLE_MANAGEMENT`	JSON `"eventData": { "roleId": "{roleId}", "roleName": "{roleName}" }`
Repository role updated	`repository-role-update`	`ROLE_MANAGEMENT`	JSON `"eventData": { "roleId": "{roleId}", "rights": [ "ManageEndorse", "ManageRequiredWatchers" ] "roleName": "{roleName}" }` *The rights will be the entire list of granted permissions at the time of the update.
Repository role deleted	`repository-role-delete`	`ROLE_MANAGEMENT`	JSON `"eventData": { "roleId": "{roleId}", "rights": [ "ManageEndorse", "ManageRequiredWatchers" ] "roleName": "{roleName}" }` *The rights will be the entire list of granted permissions at the time of deletion.
Repository role assigned to User/Group	`repository-role-assigned`	`ROLE_MANAGEMENT`	JSON `"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`	JSON `"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.
Item role created	`item-role-create`	`ROLE_MANAGEMENT`	JSON `"eventData": { "roleId": "{roleId}", "roleName": "{roleName}" }`
Item role updated	`item-role-update`	`ROLE_MANAGEMENT`	JSON `"eventData": { "roleId": "{roleId}", "rights": [ "ManageEndorse", "ManageRequiredWatchers" ] "roleName": "{roleName}" }` *The rights will be the entire list of granted permissions at the time of the update.
Item role deleted	`item-role-delete`	`ROLE_MANAGEMENT`	JSON `"eventData": { "roleId": "{roleId}", "rights": [ "ManageEndorse", "ManageRequiredWatchers" ] "roleName": "{roleName}" }` *The rights will be the entire list of granted permissions at the time of deletion.
Item role assigned to a user or group	`item-role-assigned`	`ROLE_MANAGEMENT`	JSON `"eventData": { "role": { "itemId": "{itemId}", "roleId": "{roleId}", "roleName": "{roleName}", "repositoryId": "{repoId}" }, "userId": "{userId}" }` *`userId` can also be `groupId` if the repository role was assigned to a group instead of a user, like in the example.
Item role unassigned from a user or group	`item-role-unassigned`	`ROLE_MANAGEMENT`	JSON `"eventData": { "role": { "itemId": "{itemId}", "roleId": "{roleId}", "roleName": "{roleName}", "repositoryId": "{repoId}" }, "userId": "{userId}" }` *`userId` can also be `groupId` if the repository role was assigned to a group instead of a user, like in the example.

GROUP_MANAGEMENT

Coming soon

Some group management actions are created by automated systems. Some of these actions have special principals that indicate how these actions were performed (e.g., iGrafx Identity Solution, LDAP, etc…). These principals are based off the underlying technologies and may not display what you might expect (e.g., using SAML via iGrafx Identity Solution may have the principal SYSTEM: OAuth2 because the underlying technology is OAuth2).

User Action	Event Type	Category	eventData payload
A user is added to a group	`group-assigned-user`	`GROUP_MANAGEMENT`	JSON `"eventData": { "user": { "loginName": "{loginName}", "userId": {userid} }, "group": { "groupName": "{groupName}", "groupId": {groupId} } }` *This will not audit new users being created and added to the everybody group. As well as the initial assignment for the system administrator.
A user is removed from a group	`group-unassigned-user`	`GROUP_MANAGEMENT`	JSON `"eventData": { "user": { "loginName": "{loginName}", "userId": {userid} }, "group": { "groupName": "{groupName}", "groupId": {groupId} } }`
A group is added to a group	`group-assigned-group`	`GROUP_MANAGEMENT`	JSON `"eventData": { "childGroup": { "groupName": "{groupName}", "groupId": {groupId} }, "parentGroup": { "groupName": "{groupName}", "groupId": {groupId} } }`
A group is removed from a group	`group-unassigned-user`	`GROUP_MANAGEMENT`	JSON `"eventData": { "childGroup": { "groupName": "{groupName}", "groupId": {groupId} }, "parentGroup": { "groupName": "{groupName}", "groupId": {groupId} } }`