gravityflow_step_assignees

Description

The gravityflow_step_assignees filter allows for the assignees of a step to be filtered.

Parameters

ParameterTypeDetails
$assigneesArrayThe array of Assignees
$stepStepThe current step

Examples

Add a role-based assignee based on a field value

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
add_filter( 'gravityflow_step_assignees', 'sh_step_assignees_role_field_value', 10, 2 );
function sh_step_assignees_role_field_value( $assignees, $step ) {
   if ( gravity_flow()->is_workflow_detail_page() && $step->get_id() == 63 ) {
        $entry = $step->get_entry();
        //Add logic to confirm the entry value actually matches to a role within your site
        $new_role = str_replace( '-', '_', $entry['10'] );
        $args = array(
            'id'  => $new_role,
            'type' => 'role',
            'key' => 'role|' . $new_role,
            'editable_fields' => array( '1000' ),
        );
        $new_assignee = new Gravity_Flow_Assignee( $args, $step );
        $assignees[] = $new_assignee;
    }
    return $assignees;
}

In addition to checking the step ID, we can also check the step type (‘approval’, for instance).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
add_filter( 'gravityflow_step_assignees', 'sh_step_assignees_role_field_value', 10, 2 );
function sh_step_assignees_role_field_value( $assignees, $step ) {
   if ( $step->step_type ) {
        $entry = $step->get_entry();
        //Add logic to confirm the entry value actually matches to a role within your site
        $new_role = str_replace( '-', '_', $entry['10'] );
        $args = array(
            'id'  => $new_role,
            'type' => 'role',
            'key' => 'role|' . $new_role,
            'editable_fields' => array( '1000' ),
        );
        $new_assignee = new Gravity_Flow_Assignee( $args, $step );
        $assignees[] = $new_assignee;
    }
    return $assignees;
}

Remove the current user from the list of assignees

This example checks if the current user was the one who created the entry. The delisting of the current user is checked from all 3 possibilities – user_id, role, or email assignment.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
add_filter('gravityflow_step_assignees', 'sh_step_assignees_role_field_value', 10, 2);
function sh_step_assignees_role_field_value($assignees, $step) {
    if ( gravity_flow()->is_workflow_detail_page() && $step->get_id() == 350 ) {
        $entry = $step->get_entry();
        $created_by_user_id = $entry['created_by'];
        $current_user = wp_get_current_user();
 
        if ( $created_by_user_id != $current_user->ID) {
            return $assignees;
        }
 
        $new_assignees = array();
 
        foreach ( $assignees as $assignee ) {
            switch ($assignee->get_type()) {
                case 'user_id':
                    $assignee_id = $assignee->get_id();
 
                    if ( $assignee_id != $current_user->ID ) {
                        $new_assignees[] = $assignee;
                    }
                    break;
 
                case 'role':
                    $assignee_role = $assignee->get_id();
 
                    if ( ! in_array($assignee_role, $current_user->roles ) ) {
                        $new_assignees[] = $assignee;
                    }
                    break;
 
                case 'email':
                    $assignee_email = $assignee->get_id();
 
                    if ( $assignee_email != $current_user->user_email ) {
                        $new_assignees[] = $assignee;
                    }
                    break;
            }
        }
        $assignees = $new_assignees;
    }
        return $assignees;
}

Convert role-based assignee into users

This example ensures that the step is always assigned to every user of a given role – overriding whatever assignee(s) are defined in the step settings.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
add_filter( 'gravityflow_step_assignees', 'jo_step_assignees_by_user_role', 10, 2 );
function jo_step_assignees_by_user_role( $assignees, $step ) {
 
    //Modify this to match the step ID of your approval step that needs customization.
    $step_id_approval = 570;
    //Modify this to match the role which you want to have assignes derived from.
    $step_role        = 'administrator';
 
    if ( $step->get_id() == $step_id_approval ) {
 
        //Add logic to confirm the entry value actually matches to a role within your site
        $assignees = array();
        $users     = get_users( array( 'fields' => array( 'ID' ), 'role' => $step_role ) );
 
        foreach ( $users as $user ) {
            $args         = array(
                'name'            => 'generic',
                'id'              => $user->ID,
                'type'            => 'user_id',
                'key'             => 'user_id|' . $user->ID,
                'editable_fields' => array(),
            );
            $new_assignee = new Gravity_Flow_Assignee( $args, $step );
            $assignees[]  = $new_assignee;
        }
    }
    return $assignees;
}

Add an assignee for a Workflow Step, if none is assigned (or removed).

This example ensures that a step is always assigned to a user. See the FAQ about ‘What happens to workflow when a step has no assignees / an assignee user account no longer exists?’ for why this approach may be beneficial in specific use cases.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
add_filter( 'gravityflow_step_assignees', 'sh_step_assignees_role_field_value', 10, 2 );
function sh_step_assignees_role_field_value( $assignees, $step ) {
    if ( $step->get_id() == 63 ) {
        if ( empty( $assignees ) ) {
            $args = array(
                'id'  => 'administrator',
                'type' => 'role',
                'key' => 'role|administrator',
            );
            $new_assignee = new Gravity_Flow_Assignee( $args, $step );
            $assignees[] = $new_assignee;
        }
    }
    return $assignees;
}

Let a user input step be considered complete after X assignees have responded

The default assignee policy offers any (1 assignee) or all (every assignee) options. With this filter you could let the step be considered complete when a specific # have completed their task (as the 5 in this version shows) or based on a % of total assignees, etc. Ensure that this filter is in place before any entries on the selected user input step have completed their task (or resstart them) to avoid any edge cases where the “complete” tally differs from the overall step status.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
add_filter( 'gravityflow_step_assignees', 'jo_user_input_assignee_count_complete', 10, 2 );
function jo_user_input_assignee_count_complete( $assignees, $step ) {
    if ( $step->get_id() != 63 ) {
        return $assignees;
    }
 
    $complete_assignees = array();
    foreach( $assignees as $assignee ) {
        if ( $assignee->get_status() == 'complete' ) {
            $complete_assignees[] = $assignee;
        }
    }
 
    if ( count( $complete_assignees ) >= 5 ) {
        $assignees = $complete_assignees;
    }
 
    return $assignees;
}

Placement

This code can be used in the functions.php file of the active theme, a custom functions plugin, a custom add-on, or with a code snippets plugin.

See also the PHP section in this article: Where Do I Put This Code?