Read More

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 teamId = :teamId LIMIT 200

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 userId = :userId LIMIT 200

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:

    WHERE teamId = :teamId and userId = :userId

You can also delete all members of a team by passing a PQL statement with just the team:

    WHERE teamId = :teamId

Lastly, you may just want to remove a subset of users from a team. To do this, pass a PQL statement like:

    WHERE teamId = :teamId and userId in (123,456,789)

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.

 - Adam Rogal, DFP API Team

Read More

New to v201204 of DFP API are custom fields, which can be applied to orders, line items, and creatives. This new feature gives you the ability to include additional information on DFP entities without having to implement data persistence in your own system. They are saved when the entities are saved on the DFP servers which ensures data consistency and removes the need for syncing.

Data Types
The following are the supported data types of a custom field:

• String
• Number
• Toggle (true/ false)
• Drop-down (selection from user-defined values)

These data types should cover some of the most common use cases for custom fields such as comments (string), metrics (number), and internal system status (toggle/drop-down).

How-To
You can create and manage your custom fields and custom field options (for drop-down custom fields) with the new CustomFieldService. Please make sure you have the feature enabled for your network before you try to set up custom fields. We are also working on bringing custom fields to the user interface, so be on the lookout for them!

Walk-Through
The following Java sample shows how you can add a string and drop-down custom field value to your line item. This assumes that you have already created the custom fields and custom field options. You can check out how to create them using the CreateCustomFields and CreateCustomFieldOptions examples in the client libraries.

Long customFieldId = Long.parseLong("INSERT_STRING_CUSTOM_FIELD_ID_HERE");
Long dropDownCustomFieldId = 
    Long.parseLong("INSERT_DROP_DOWN_CUSTOM_FIELD_ID_HERE");
Long customFieldOptionId = 
    Long.parseLong("INSERT_CUSTOM_FIELD_OPTION_ID_HERE");
Long lineItemId = Long.parseLong("INSERT_LINE_ITEM_ID_HERE");

// Get the line item.
LineItem lineItem = lineItemService.getLineItem(lineItemId);

// Create custom field values.
List customFieldValues = new ArrayList();

// Create the String custom field value.
TextValue textValue = new TextValue();
textValue.setValue("Custom field value");
CustomFieldValue customFieldValue = new CustomFieldValue();
customFieldValue.setCustomFieldId(customFieldId);
customFieldValue.setValue(textValue);
customFieldValues.add(customFieldValue);

// Create the drop-down custom field value.
DropDownCustomFieldValue dropDownCustomFieldValue =
    new DropDownCustomFieldValue();
dropDownCustomFieldValue.setCustomFieldId(dropDownCustomFieldId);
dropDownCustomFieldValue.setCustomFieldOptionId(customFieldOptionId);
customFieldValues.add(dropDownCustomFieldValue);

// The line item can contain custom field values for the field you are
// trying to set or an unrelated one.  The following checks that you only 
// add existing custom field values for custom fields different from the 
// ones you are setting.
if (lineItem.getCustomFieldValues() != null) {
  for (BaseCustomFieldValue oldCustomFieldValue : 
      lineItem.getCustomFieldValues()) {
    if (!oldCustomFieldValue.getCustomFieldId().equals(customFieldId)
        && !oldCustomFieldValue.getCustomFieldId().equals(
        dropDownCustomFieldId)) {
      customFieldValues.add(oldCustomFieldValue);
    }
  }
}

// Set the custom field values on the line item.
lineItem.setCustomFieldValues(customFieldValues.toArray(
    new BaseCustomFieldValue[]{}));

// Update the line item on the server.
LineItem[] lineItems = lineItemService.updateLineItems(
    new LineItem[] {lineItem});

And that’s it! For the full Java code example, you can refer to the SetLineItemCustomFieldValue in the client library.

With this new feature, we aim to help you create stronger integrations with DFP through the API. If there are any features you would like us to demonstrate, please don’t hesitate to let us know with a forum post or at a Office Hour Hangout.

 - Jeffrey Sham, DFP API Team

Read More

v201204 of the DFP API has launched and is ready for you to explore. In this version, we’ve added custom fields, expanded team and user functionality, and updated the conversion reports columns. A full list of features can be found on our release notes page.

Custom fields

Custom fields is a new feature to the API that lets you add attributes to entities, such as orders and line items. For example, you can add your own field to a line item that would let salespeople add comments as a string. Those comments would then be placed into custom field values that are added to each line item. Support for custom fields will be coming or the DFP UI soon, but if you have this feature enabled on your network now, you’ll be able to start working with them right away.

Teams changes

The way in which users are added to teams has changed starting in v201204. In previous versions, users were added to team objects directly. Now, you can associate users and teams, much like line items and creatives. The new associations will also let you define per user permissions, such as only letting some users have read-only access.

Version deprecation reminder

As a reminder, we are retiring support for v201103, v201104, and v201107 on May 11th. If you haven’t upgraded yet, now would be a great time.

Our next hangout is May 9th and we’d love to see you there. As always, let us know if you have any questions on our forum.

 - Adam Rogal, DFP API Team