Manipulating Teams Programmatically

Overview

How to manipulate team relationships.

Fetching Teams

To fetch teams related to a bean, you will need to retrieve an instance of a TeamSet object and use the getTeams() method to retrieve the teams using the team_set_id. An example is shown below:

    //Create a TeamSet bean - no BeanFactory
require_once 'modules/Teams/TeamSet.php';
$teamSetBean = new TeamSet();

//Retrieve the bean
$bean = BeanFactory::getBean($module, $record_id);

//Retrieve the teams from the team_set_id
$teams = $teamSetBean->getTeams($bean->team_set_id);

Adding Teams

To add a team to a bean, you will need to load the team's relationship and use the add() method. This method accepts an array of team ids to add. An example is shown below:

    //Retrieve the bean
$bean = BeanFactory::getBean($module, $record_id);

//Load the team relationship 
$bean->load_relationship('teams');

//Add the teams
$bean->teams->add(
    array(
        $team_id_1, 
        $team_id_2
    )
);

Considerations

• If adding teams in a logic hook, the recommended approach is to use an after_save hook rather than a before_save hook as the $_REQUEST may reset any changes you make.

Removing Teams

To remove a team from a bean, you will need to load the team's relationship and use the remove() method. This method accepts an array of team ids to remove. An example is shown below:

    //Retrieve the bean
$bean = BeanFactory::getBean($module, $record_id);

//Load the team relationship 
$bean->load_relationship('teams');

//Remove the teams
$bean->teams->remove(
    array(
        $team_id_1, 
        $team_id_2
    )
);

Considerations

• If removing teams in a logic hook, the recommended approach is to use an after_save hook rather than a before_save hook as the $_REQUEST may reset any changes you make.

Replacing Team Sets

To replace all of the teams related to a bean, you will need to load the team's relationship and use the replace() method. This method accepts an array of team ids. An example is shown below:

    //Retrieve the bean
$bean = BeanFactory::getBean($module, $record_id);

//Load the team relationship 
$bean->load_relationship('teams');

//Set the primary team
$bean->team_id = $team_id_1

//Replace the teams
$bean->teams->replace(
    array(
        $team_id_1, 
        $team_id_2
    )
);

//Save to update primary team
$bean->save()

Considerations

• If replacing teams in a logic hook, the recommended approach is to use an after_save hook rather than a before_save hook as the $_REQUEST or workflow may reset any changes you make.
• This method does not replace (or set) the primary team for the record. When replacing teams, you need to also make sure that the primary team, determined by the team_id field, is set appropriately and included in the replacement ids. If this is being done in a logic hook you should set the primary team in a before_save hook and replace the team set in the after_save hook.
• When using an after_save hook, be sure to call $bean->teams->setSaved(false) to explicitly reset the save state. This ensures that the updates (create, update or delete) to the team sets are applied.

Example:

    //before save function

public function before_save_hook($bean, $event, $arguments)
{
    $bean->team_id = $team_id_1;
}

//after save function
public function after_save_hook($bean, $event, $arguments)
{
	$bean->teams->setSaved(false); // Manually reset TeamSet state for save

    $bean->teams->replace(
        array(
            $team_id_1,
            $team_id_2
        )
    );
}

Creating and Retrieving Team Set IDs

To create or retrieve the team_set_id for a group of teams, you will need to retrieve an instance of a TeamSet object and use the addTeams() method. If a team set does not exist, this method will create it and return an id. An example is below:

    //Create a TeamSet bean - no BeanFactory
require_once 'modules/Teams/TeamSet.php';
$teamSetBean = new TeamSet();

//Retrieve/create the team_set_id
$team_set_id = $teamSetBean->addTeams(
    array(
        $team_id_1,
        $team_id_2
    )
);

Adding Additional Access

To enable additional access for a record, you can either set the team id or team set to the beans acl_team_set_id field. An example of this is shown below:

    require_once 'modules/Teams/TeamSet.php';
// Create a new teamset or fetch the id of an existing teamset
$teamSetBean = new TeamSet();
$teamSetId = $teamSetBean->addTeams([
    'East', // Demo Team ID
    'West', // Demo Team ID
]);

$bean = BeanFactory::getBean('Accounts', '15bcf01c-1e1e-11e8-9e13-f45c89a8598f');

// Set additional access
$bean->acl_team_set_id = $teamSetId; // if set to NULL, this will remove any existing value
$bean->save();