The IDataAdminService interface provides a set of methods that enable the execution of CRUD operations pertaining to Dynamic Data Masking (DDM). These methods are utilized for managing:
  • User-defined roles
  • Users
  • Role grants or user-to-role mapping
  • Authorization tags
  • Setting or unsetting the mask and authorization tag for any field in a table

Methods for managing user-defined roles

A security administrator is responsible for creating user-defined roles that govern the privileges associated with data access for individual users. The following table lists the IDataAdminService methods that you can utilize to perform the DDM-related CRUD operations on roles:
Table 1. IDataAdminService interface methods for user-defined roles
Method syntax Description 
Logical CreateRole (poRole AS IRole)
 Creates a new user-defined role referenced by poRole and returns TRUE if successful. 
Logical UpdateRole (poRole AS IRole)

Updates the user-defined role referenced by poRole and returns TRUE if successful.

 
Logical DeleteRole (roleName AS CHARACTER)

Deletes the user-defined role referenced by roleName and returns TRUE if successful.

This method generates an error if you attempt to delete a system- defined role or a user-defined role that does not exist.

Methods for managing users

The following table lists the IDataAdminService methods that you can utilize to perform the DDM-related CRUD operations on users:
Table 2. IDataAdminService interface methods for users
Method syntax Description 
Logical CreateUser (usr AS IUser)
 Creates a new user referenced by usr and returns TRUE if successful. 
Logical UpdateUser (usr AS IUser)
 Updates table permissions for the user referenced by usr and returns TRUE if successful. 
Logical DeleteUser (usrId AS CHARACTER)

Deletes the user referenced by usrId and returns TRUE if successful.

This method generates the NOTFOUNDERROR error if you attempt to delete a user that does not exist.

Methods for managing role grants

DDM configuration employs role-based access control (RBAC) to regulate the privileges granted to users for the purpose of data unmasking. This technique makes it easier to create and grant new roles to database users (user-to-role mapping), allowing for the determination of user privileges for accessing certain resources.

The following table lists the IDataAdminService methods that you can utilize to perform the DDM-related CRUD operations on role grants:
Table 3. IDataAdminService interface methods for role grants
Method syntax Description 
Logical CreateGrantedRole (poGrant AS IGrantedRole)
 Creates a new role grant referenced by poGrant and returns TRUE if successful. 
Logical CreateGrantedRoles (poGrants AS IGrantedRoleSet)

Creates a collection of new role grants referenced by poGrants and returns TRUE if successful.

 
GetGrantedRoles (pcFilter AS CHARACTER)
 Retrieves a collection of role grants from the database using the query referenced by pcFilter, which is used to filter the result set. 
Logical UpdateGrantedRole (poGrant AS IGrantedRole)
 Updates the role grant referenced by poGrant and returns TRUE if successful. 
Logical UpdateGrantedRoles (poGrants AS IGrantedRoleSet)

Updates the collection of role grants referenced by poGrants and returns TRUE if successful.

 
Logical DeleteGrantedRole (pcGrantId AS CHARACTER)

Deletes the role grant referenced by pcGrantId and returns TRUE if successful.

The method generates NOTFOUNDERROR error if you attempt to delete a role grant that does not exist.

Methods for managing authorization tags

The authorization tag is an attribute designed to establish the connection between user-defined DDM roles and the fields of a table to which a mask is to be applied. If an authorization tag is associated with fields of a table on one side and a user-defined role on the other, and if that role is mapped to you, then it can be determined that you have unmask privileges for the fields of the table in consideration.

The DDM administrator is responsible for creating and assigning new authorization tags to the user-defined roles. They can map any role to multiple authorization tags and any authorization tag to multiple user-defined roles. After mapping the roles and authorization tags together, the DDM administrator can map these authorization tags to the table fields.

The following table lists the IDataAdminService methods that you can utilize to perform the DDM-related CRUD operations on authorization tags:
Table 4. IDataAdminService interface methods for authorization tags
Method syntax Description 
Logical CreateAuthTag (tag AS IAuthTag)
 Creates a new authorization tag referenced by tag and returns TRUE if successful. 
Logical CreateAuthTags (tags AS IAuthTagset)
 Creates a collection of new authorization tags referenced by tags and returns TRUE if successful. 
GetAuthTags()
 Retrieves from the database a collection of all authorization tags and their associated user-defined roles. 
Logical UpdateAuthTag (tag AS IAuthTag)
 Updates the authorization tag referenced by tag and returns TRUE if successful. 
Logical UpdateAuthTags (tags AS IAuthTag)

Updates the collection of authorization tags referenced by tags and returns TRUE if successful.

 
Logical DeleteAuthTag (
pcRoleName AS CHARACTER, 
pcAuthTag AS CHARACTER)

Deletes the authorization tag and the associated role name referenced by pcAuthTag and pcRoleName, respectively, and returns TRUE if successful.

This method generates the NOTFOUNDERROR error if you attempt to delete an authorization tag that does not exist for the specified user-defined role.

Set or unset mask and authorization tag for any field in a table

A mask is the format string representation, which is set up against the fields of a table. The authorization tags determine whether the user has permission to view the unmasked data if a mask is defined for a given field.

For more information on the authorization tags and the available mask configuration types, see “Authorization tags” and “Dynamic data mask configurations” in Learn About Security and Auditing.

The following table lists the IDataAdminService methods that you can utilize to set or unset (reset) the mask and authorization tag for any field in a table:
Table 5. IDataAdminService interface methods for setting and unsetting mask and authorization tag
Method syntax Description 
Logical setDDMConfig(
tablename AS CHARACTER, 
fieldname AS CHARACTER, 
maskval AS CHARACTER,
authtag AS CHARACTER)

Configures DDM settings such as mask value and authorization tag referenced by maskval and authtag, respectively, for fieldname field of the tablename table and returns TRUE if successful.

 
Logical unsetDDMMask(
tablename AS character,
fieldname AS character)

Resets the mask value for fieldname field of the tablename table and returns TRUE if successful.

 
Logical unsetDDMAuthTag(
tablename AS character,
fieldname AS character)
 Resets the authorization tag for fieldname field of tablename table and returns TRUE if successful.
Note: When you reset the authorization tag value, reset the corresponding mask value also.

Get mask and authorization tag for any field in a table

The following table lists the IDataAdminService methods that you can utilize to retrieve the mask and authorization tag for any field in a table:
Table 6. IDataAdminService interface methods to mask and authorization tag
Method syntax Description 
GetFieldDDMConfig(
input tablename AS character,
input fieldname AS character,
output maskval AS character,
output authtag AS character)
 Retrieves the mask value and authorization tag for the given fieldname field of the tablename table. If the field is not configured for DDM, the maskval and authtag are set to an unknown value (?).