Hiding actions that a user cannot perform

A schema designer can hide actions from users who do not have permission to perform the action.

Actions in a schema might display in HCL Compass even if a user does not have permission to perform all the actions. A schema designer can hide actions that are controlled by an action access control hook. Actions that are hidden from the user do not display in the Modify, Change State, or Utilities menus in the HCL Compass client. Whether an action is hidden is determined by the value specified in Access Control.
  • If Access Control is set to All Users, the action is not hidden because all users are allowed to access the action.
  • If Access Control is set to User Groups, the action is visible to users who are members of the specified groups.
  • If Access Control is set to SCRIPTS, the action may or may not be hidden from the user depending on the value of the HIDE_ACTIONS schema property. The default behavior is to display the action.

Hiding actions for SCRIPTS access control: HIDE_ACTIONS schema property

First, the schema must be enabled to hide actions. Run the packageutil command to set the HIDE_ACTIONS schema property to 1. The HIDE_ACTIONS schema property is set on the latest version of the schema. The format of the command is as follows:

packageutil setproperty -dbset <dbset> <user> <password> <schema> HIDE_ACTIONS 1

To disable the ability to hide actions, set the HIDE_ACTIONS schema property to 0.
Note: Record form display performance may be affected by setting the HIDE_ACTIONS session variable value to 1. Access control hooks for all the actions on the record will be run to determine if the action should be displayed to the user. If the schema has a large number of actions, or if the access control hook script processes slowly, then the user may perceive a record form as loading slowly.

ratl_GetLegalAction session variable

When the HIDE_ACTIONS schema property is set to 1 to hide actions and Access Control is set to SCRIPTS, the access control hook can be called to determine if the action name should be hidden from the user in the menus of the HCL Compass client, or to check if the user is allowed to perform the action. The schema designer can customize the hook to check the value of the hcl_GetLegalActionsession variable, which indicates why the hook is being called.
  • If the value of hcl_GetLegalAction matches the display name of the current record, the hook is being called to determine if the action should be hidden. The hook returns a value of 0 if the action name should be hidden. The hook returns a value of 1 if the action name should be displayed.
  • If the value of hcl_GetLegalAction does not match the display name of the current record, the hook is being called to determine if the user is allowed to run this action. The action has been selected and will be run if the access control hook returns a value of 1. Even if the action name was hidden from this user in the Compass client menus, the action may be invoked by a nested hook or external script. The HCL Compass client will display a generic error message that this action is not allowed if the action access control hook returns 0. Alternately, the hook can display a more descriptive error message by passing information to a Perl die() function or a VBScript Err.Raise() method. The message could contain information about a precondition that is not met or why the user does not have permission to run the action.

Example

The following Perl example shows you how to customize the hook to decide if the action is hidden or not. You can also write this type of access control hook with VBScript.
    # Start User Code
    # Set $result to 1 if the user has permission to perform
    # this action, otherwise set it to 0.

    $result = 0;

    if ($session->IsUserSuperUser()) {
        # A super user can always do this action.
        $result = 1;
    }
    else {
        my $GLA = $session->GetNameValue("ratl_GetLegalAction");
        my $myName = $entity->GetDisplayName();
        if ($GLA eq $myName) {
            # This hook was called for hide action.
            # To hide the action, return 0 by uncommenting the following line
            # $result = 0
            # and then delete or comment out the $result = 1 below
            #
            # Or, to always show the action so the user will see 
            # a detailed message if they try to run it. 
            $result = 1;
        }
        else {
            my $user  = $session->GetUserLoginName();
            my $owner = $entity->GetFieldStringValue("Owner");
            if ($user ne $owner) {
                die "Only the owner can perform this action."; 
            }
            $result = 1;
        }
    }
    # End User Code