Custom Query Callback for Reassigning and Adding Approver
Approvals admins can determine predefined subset of users, groups, queues or roles to be added as ad hoc or additional users to the list of approvals for in-flight approval requests. Approvals also supports a custom callback code to filter query users, roles and queues for reassigning and adding an approver on the My Approvals page.
Admins can also reassign to queues and roles as well as users. When you select re-assignment to a queue or a role, a list of queues or roles is dynamically populated via a drop-down. By default:
- Reassigning Approver: Selects all users, queues, or roles
- Add Approver: Selects all users, queues, or roles
To change the default behavior from selecting all users, queues, and roles to selecting only a subset of them, you can create a custom Apex callback class that contains custom code to query users, queues, and roles when reassigning users or adding ad hoc approvers from the My Approvals page. Your code must implement the IQueryCallback and IQueryCallback2 interfaces and define the following six methods to override the default behavior, which is to select all available users, queues, and roles. Because there are individual methods to select users, queues, or roles for reassigning or adding new approvers, you can display a different set of records for reassign approvers than adding them. Your code can also call a common method to return the same set of records for both.
/**
* Apttus Approvals Management
* IQueryCallback
*
* @2018-2019 Apttus Inc. All rights reserved.
*/
global interface IQueryCallback {
/**
* Callback invoked to perform a filtered query when reassigning user approvers
* @param request the approval request context object
* @param searchText the prefilter search text
* @return list of sobjects returned from query
*/
List<sObject> doReassignUserQuery(Approval_Request__c request, String searchText);
/**
* Callback invoked to perform a filtered query when adding user approvers
* @param request the approval request context object
* @param searchText the prefilter search text
* @return list of sobjects returned from query
*/
List<sObject> doAddUserQuery(Approval_Request__c request, String searchText);
/**
* Callback invoked to perform a filtered query when adding queue approvers
* @param request the approval request context object
* @param searchText the prefilter search text
* @return list of sobjects returned from query
*/
List<sObject> doAddQueueQuery(Approval_Request__c request, String searchText);
/**
* Callback invoked to perform a filtered query when adding role approvers
* @param request the approval request context object
* @param searchText the prefilter search text
* @return list of sobjects returned from query
*/
List<sObject> doAddRoleQuery(Approval_Request__c request, String searchText);
}
/**
* Apttus Approvals Management
* IQueryCallback2
*
* @2018-2019 Apttus Inc. All rights reserved.
*/
global interface IQueryCallback2 extends IQueryCallback {
/**
* Callback invoked to perform a filtered query when reassigning queue approvers
* @param request the approval request context object
* @param searchText the prefilter search text
* @return list of sobjects returned from query
*/
List<sObject> doReassignQueueQuery(Approval_Request__c request, String searchText);
/**
* Callback invoked to perform a filtered query when reassigning role approvers
* @param request the approval request context object
* @param searchText the prefilter search text
* @return list of sobjects returned from query
*/
List<sObject> doReassignRoleQuery(Approval_Request__c request, String searchText);
}To override the default behavior
From the Approval System Properties in the Reassign Filter Page custom setting, name a Visualforce page that lets users select from a filtered list of users, queues, and roles.
To specify the custom reassign user search
- Go to and click Manage for Approval System Properties.
- In the Reassign Filter page, specify the name of the Visualforce page.
- Click Save.
To override the Default Query Callback class
- Enter your callback class name in Query Callback class.In this example,
GSMyApprovalsQueryCallbackis entered as the query callback class name:
Use Case
A sample implementation of a custom callback with custom filters to reassign and add approver users and to add approver users, queues, and roles is presented here. Your custom class can be simpler or more complex. Each method takes two parameters: the approval request context object the user has selected to reassign or add approvers to, and the search text entered in the search box for additional record filtering. Each method in your callback class must return a list of User, QueueSObject, or UserRole objects in each of the three methods.
Note:
You must define your class as global for the callback mechanism to work.
/**
* Apttus Approvals Management
* GSMyApprovalsQueryCallback
*
* @2018-2019 Apttus Inc. All rights reserved.
*/
global with sharing class GSMyApprovalsQueryCallback
implements Apttus_Approval.CustomClass.IQueryCallback,
Apttus_Approval.CustomClass.IQueryCallback2 {
// limit rows
public static final Integer LIMIT_ROWS = 1000;
/**
* Callback invoked to perform a filtered query when reassigning user approvers
* @param request the approval request context object
* @param searchText the prefilter search text
* @return list of sobjects returned from query
*/
public List<sObject> doReassignUserQuery(Apttus_Approval__Approval_Request__c request, String searchText) {
try {
String sq = '\'';
String qryStr = 'SELECT Id, Name, Username, LastName, FirstName, Email, UserRoleId, UserRole.Name, IsActive, Profile.Name ';
qryStr += ', (select Id, ';
qryStr += 'Apttus_Approval__Approval_Level__c, ';
qryStr += 'Apttus_Approval__Description__c';
qryStr += ' from ' + 'Apttus_Approval__Approval_Matrices__r)';
qryStr += ' FROM User ';
qryStr += ' WHERE IsActive = true ';
if (!nullOrEmpty(searchText)) {
// build the search term
String searchTerm = (searchText != null ? searchText : '').trim();
// append wildcards to the search term
searchTerm = (!searchTerm.startsWith('%') ? '%' + searchTerm : searchTerm);
searchTerm = (!searchTerm.endsWith('%') ? searchTerm + '%' : searchTerm);
qryStr += 'AND ';
qryStr += 'Name LIKE ' + sq + String.escapeSingleQuotes(searchTerm) + sq;
}
// EXAMPLE: filter out users with names not containing 'Borden' and system admin profiles
qryStr += ' AND (NOT Name LIKE ' + sq + 'Borden%' + sq + ')';
//qryStr += ' AND Profile.Name = ' + sq + 'System Administrator' + sq;
qryStr += ' ORDER BY Name';
// limit rows
qryStr += ' LIMIT ' + LIMIT_ROWS;
// execute the query
return Database.query(qryStr);
} catch (Exception ex) {
system.debug(LoggingLevel.ERROR, ex.getMessage());
return new List<sObject>();
}
}
/**
* Callback invoked to perform a filtered query when reassigning queue approvers
* @param request the approval request context object
* @param searchText the prefilter search text
* @return list of sobjects returned from query
*/
public List<sObject> doReassignQueueQuery(Apttus_Approval__Approval_Request__c request, String searchText) {
try {
String sq = '\'';
String qryStr = 'SELECT Id, QueueId, Queue.Id, Queue.Name, Queue.DeveloperName, Queue.Type, Queue.Email';
qryStr += ' FROM QueueSobject ';
qryStr += ' WHERE ';
if (!nullOrEmpty(searchText)) {
// build the search term
String searchTerm = (searchText != null ? searchText : '').trim();
// append wildcards to the search term
searchTerm = (!searchTerm.startsWith('%') ? '%' + searchTerm : searchTerm);
searchTerm = (!searchTerm.endsWith('%') ? searchTerm + '%' : searchTerm);
qryStr += 'Queue.Name LIKE ' + sq + String.escapeSingleQuotes(searchTerm) + sq;
qryStr += ' AND SObjectType = ' + sq + 'Apttus_Approval__Approval_Request__c' + sq;
qryStr += ' AND';
}
// EXAMPLE: filter out queues with names containing 'Approvals BQA'
qryStr += ' Queue.Name LIKE ' + sq + 'Approvals BQA%' + sq;
qryStr += ' AND SObjectType = ' + sq + 'Apttus_Approval__Approval_Request__c' + sq;
qryStr += ' ORDER BY Queue.Name';
// limit rows
qryStr += ' LIMIT ' + LIMIT_ROWS;
// execute the query
return Database.query(qryStr);
} catch (Exception ex) {
system.debug(LoggingLevel.ERROR, ex.getMessage());
return new List<sObject>();
}
}
/**
* Callback invoked to perform a filtered query when reassigning role approvers
* @param request the approval request context object
* @param searchText the prefilter search text
* @return list of sobjects returned from query
*/
public List<sObject> doReassignRoleQuery(Apttus_Approval__Approval_Request__c request, String searchText) {
try {
String sq = '\'';
String qryStr = 'SELECT Id, Name, DeveloperName, RollupDescription';
qryStr += ' FROM UserRole ';
qryStr += ' WHERE ';
if (!nullOrEmpty(searchText)) {
// build the search term
String searchTerm = (searchText != null ? searchText : '').trim();
// append wildcards to the search term
searchTerm = (!searchTerm.startsWith('%') ? '%' + searchTerm : searchTerm);
searchTerm = (!searchTerm.endsWith('%') ? searchTerm + '%' : searchTerm);
qryStr += 'UserRole.Name LIKE ' + sq + String.escapeSingleQuotes(searchTerm) + sq;
qryStr += ' AND';
}
// EXAMPLE: filter out roles with names containing Sales
qryStr += ' UserRole.Name LIKE ' + sq + 'Sales%' + sq;
qryStr += ' ORDER BY UserRole.Name';
// limit rows
qryStr += ' LIMIT ' + LIMIT_ROWS;
// execute the query
return Database.query(qryStr);
} catch (Exception ex) {
system.debug(LoggingLevel.ERROR, ex.getMessage());
return new List<sObject>();
}
}
/**
* Callback invoked to perform a filtered query when adding user approvers
* @param request the approval request context object
* @param searchText the prefilter search text
* @return list of sobjects returned from query
*/
public List<sObject> doAddUserQuery(Apttus_Approval__Approval_Request__c request, String searchText) {
try {
String sq = '\'';
String qryStr = 'SELECT Id, Name, Username, LastName, FirstName, Email, UserRoleId, UserRole.Name, IsActive, Profile.Name ';
qryStr += ', (select Id, ';
qryStr += 'Apttus_Approval__Approval_Level__c, ';
qryStr += 'Apttus_Approval__Description__c';
qryStr += ' from ' + 'Apttus_Approval__Approval_Matrices__r)';
qryStr += ' FROM User ';
qryStr += ' WHERE IsActive = true ';
if (!nullOrEmpty(searchText)) {
// build the search term
String searchTerm = (searchText != null ? searchText : '').trim();
// append wildcards to the search term
searchTerm = (!searchTerm.startsWith('%') ? '%' + searchTerm : searchTerm);
searchTerm = (!searchTerm.endsWith('%') ? searchTerm + '%' : searchTerm);
qryStr += 'AND ';
qryStr += 'Name LIKE ' + sq + String.escapeSingleQuotes(searchTerm) + sq;
}
// EXAMPLE: filter out users with names not containing 'Borden' and system admin profiles
qryStr += ' AND (NOT Name LIKE ' + sq + 'Borden%' + sq + ')';
//qryStr += ' AND Profile.Name = ' + sq + 'System Administrator' + sq;
qryStr += ' ORDER BY Name';
// limit rows
qryStr += ' LIMIT ' + LIMIT_ROWS;
// execute the query
return Database.query(qryStr);
} catch (Exception ex) {
system.debug(LoggingLevel.ERROR, ex.getMessage());
return new List<sObject>();
}
}
/**
* Callback invoked to perform a filtered query when adding queue approvers
* @param request the approval request context object
* @param searchText the prefilter search text
* @return list of sobjects returned from query
*/
public List<sObject> doAddQueueQuery(Apttus_Approval__Approval_Request__c request, String searchText) {
try {
String sq = '\'';
String qryStr = 'SELECT Id, QueueId, Queue.Id, Queue.Name, Queue.DeveloperName, Queue.Type, Queue.Email';
qryStr += ' FROM QueueSobject ';
qryStr += ' WHERE ';
if (!nullOrEmpty(searchText)) {
// build the search term
String searchTerm = (searchText != null ? searchText : '').trim();
// append wildcards to the search term
searchTerm = (!searchTerm.startsWith('%') ? '%' + searchTerm : searchTerm);
searchTerm = (!searchTerm.endsWith('%') ? searchTerm + '%' : searchTerm);
qryStr += 'Queue.Name LIKE ' + sq + String.escapeSingleQuotes(searchTerm) + sq;
qryStr += ' AND SObjectType = ' + sq + 'Apttus_Approval__Approval_Request__c' + sq;
qryStr += ' AND';
}
// EXAMPLE: filter out queues with names containing 'BO'
qryStr += ' Queue.Name LIKE ' + sq + 'BO%' + sq;
qryStr += ' AND SObjectType = ' + sq + 'Apttus_Approval__Approval_Request__c' + sq;
qryStr += ' ORDER BY Queue.Name';
// limit rows
qryStr += ' LIMIT ' + LIMIT_ROWS;
// execute the query
return Database.query(qryStr);
} catch (Exception ex) {
system.debug(LoggingLevel.ERROR, ex.getMessage());
return new List<sObject>();
}
}
/**
* Callback invoked to perform a filtered query when adding role approvers
* @param request the approval request context object
* @param searchText the prefilter search text
* @return list of sobjects returned from query
*/
public List<sObject> doAddRoleQuery(Apttus_Approval__Approval_Request__c request, String searchText) {
try {
String sq = '\'';
String qryStr = 'SELECT Id, Name, DeveloperName, RollupDescription';
qryStr += ' FROM UserRole ';
qryStr += ' WHERE ';
if (!nullOrEmpty(searchText)) {
// build the search term
String searchTerm = (searchText != null ? searchText : '').trim();
// append wildcards to the search term
searchTerm = (!searchTerm.startsWith('%') ? '%' + searchTerm : searchTerm);
searchTerm = (!searchTerm.endsWith('%') ? searchTerm + '%' : searchTerm);
qryStr += 'UserRole.Name LIKE ' + sq + String.escapeSingleQuotes(searchTerm) + sq;
qryStr += ' AND';
}
// EXAMPLE: filter out roles with names containing Role
qryStr += ' UserRole.Name LIKE ' + sq + 'Role%' + sq;
qryStr += ' ORDER BY UserRole.Name';
// limit rows
qryStr += ' LIMIT ' + LIMIT_ROWS;
// execute the query
return Database.query(qryStr);
} catch (Exception ex) {
system.debug(LoggingLevel.ERROR, ex.getMessage());
return new List<sObject>();
}
}
/**
* Checks if the given string value is null or empty.
* @param strValue the string to check
* @return <code>true</code> if the string value is null or empty, <code>false</code> otherwise
*/
public static Boolean nullOrEmpty(String strValue) {
// check if null or zero length string
return (strValue == null || strValue.trim().length() == 0);
}