Manipulating Teams Programatically

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 teams 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 teams 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 teams 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.

Function Examples:

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

//after save function
function after_save_hook($bean, $event, $arguments)
{
    $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
    )
);