Getting the team back together with the DFP API
Tuesday, June 19, 2012
As you may have noticed in v201204, how you populate teams with users has changed a bit. Starting in v201204, teams are now populated by associating users with a team, much like line item creative associations. Associations give you the ability to define per-team permissions for users and remove users through PQL on the server, rather than modifying a large list of IDs on the team object.
Creating the team
Creating team objects works the same way as in previous versions; you call TeamService.createTeams specifying the initial set of properties on the team, such as to which inventory and companies the team has access. To add users to this empty team, however, you will need to create user team associations for every user you want to add to the team. When creating the association, you can also specify an access override if you have that feature enabled on your network; e.g., you can add a user limiting them to have read only access to entities on that team.
As a side note, you may find some teams have already been created for you by Google. These teams have negative IDs and their name will describe their purpose. The team with the name “All entities”, for example, gives all joined users access to all entities in the network.
Getting the teams
Now that you’ve created a team and associated users with it, it’s simple to retrieve either all users on that team, or all teams to which a user belongs. To retrieve all users on a team, make a call to UserTeamAssociationService.getUserTeamAssociationsByStatement with the PQL statement:
where you’ve bound :teamId to the team’s ID and iterate through each page to collect the results. To retrieve all teams to which a user belongs, make the same service call, but pass the user’s ID instead of the team’s such as:
where you’ve bound :userId to the user’s ID and iterate through each page again to collect the results.
Removing someone from the team
In v201204, removing a user from a team is equivalent to deleting that user’s team association. To delete associations, make a call to UserTeamAssociationService.performUserTeamAssociationAction with a PQL statement including either the team ID, user ID, or both. To delete just a single team member, pass the statement:
You can also delete all members of a team by passing a PQL statement with just the team:
Lastly, you may just want to remove a subset of users from a team. To do this, pass a PQL statement like:
where you’ve bound :teamId to the team’s ID, and 123, 456, and 789 represent IDs of users that you want to remove.
Our next hangout is July 18th and we’d love to see you there. As always, let us know if you have any questions on our forum.
Creating the team
Creating team objects works the same way as in previous versions; you call TeamService.createTeams specifying the initial set of properties on the team, such as to which inventory and companies the team has access. To add users to this empty team, however, you will need to create user team associations for every user you want to add to the team. When creating the association, you can also specify an access override if you have that feature enabled on your network; e.g., you can add a user limiting them to have read only access to entities on that team.
As a side note, you may find some teams have already been created for you by Google. These teams have negative IDs and their name will describe their purpose. The team with the name “All entities”, for example, gives all joined users access to all entities in the network.
Getting the teams
Now that you’ve created a team and associated users with it, it’s simple to retrieve either all users on that team, or all teams to which a user belongs. To retrieve all users on a team, make a call to UserTeamAssociationService.getUserTeamAssociationsByStatement with the PQL statement:
WHERE teamId = :teamId LIMIT 200
WHERE userId = :userId LIMIT 200
Removing someone from the team
In v201204, removing a user from a team is equivalent to deleting that user’s team association. To delete associations, make a call to UserTeamAssociationService.performUserTeamAssociationAction with a PQL statement including either the team ID, user ID, or both. To delete just a single team member, pass the statement:
WHERE teamId = :teamId and userId = :userId
WHERE teamId = :teamId
WHERE teamId = :teamId and userId in (123,456,789)
Our next hangout is July 18th and we’d love to see you there. As always, let us know if you have any questions on our forum.