[mailchimp-api-announce] Important Changes to Interest Groups coming 4/26/2010

[jesse]

This is to notify everyone of some very important changes coming to
Interest Groups coming 4/26/2010 (that's next Monday). Our next
release should be out then and will include the changes detailed
below. API documentation is ready and should follow shortly after we
have the release out.

About the Changes
======================
First, we recognize that these changes are not exactly API friendly,
especially for people using wrappers and who have integrations in
place. There are several reasons behind the changes and they do, in
fact, bring some nice extra functionality to the app. IF you are
already using interest groups, these changes are completely backwards
compatible. HOWEVER, once users start adding new groupings of groups,
you may start having some issues until you adopt the new methods and
method signatures.


A quick overview of the changes:
* The 30 Interest Group limit has been raised to 60 interest groups
* We've added a thin layer for creating groupings of groups so you
could now have 10 groupings that contain 6 groups each (or any
combination upto 60) and have separate field formats and titles/labels
for each grouping
* Hidden interest groupings/groups
* Bit values are now unsigned *64 bit integers* (double double,
unsigned int, etc)

Existing interest groups are being auto-converted into a single,
default grouping for each list. Existing API methods which operate on
Interest Groups will use groups in that grouping by default. We are
also giving users the opportunity to convert our drop-down and radio
button type merge fields directly to interest groups - there is a
warning to contact their developer/integrated system before starting
to use converted fields.


Concrete Examples
======================
Let's say that before the system update you have a list with the
following interest groups:
Label/Title = "What's your favorite primate?"
* Chimps
* Monkeys
* Gorillas

After the update, the list will have 1 grouping with 3 groups:

Group Id = 1
Label/Title = "What's your favorite primate?"
* Chimps
* Monkeys
* Gorillas

Then, a user sees the new options and adds a new grouping, so you now
have:
Group Id = 1
Label/Title = "What's your favorite primate?"
* Chimps
* Monkeys
* Gorillas
Group Id = 2
Label/Title = "What's your favorite color?"
* Red
* Blue
* Green

While full documentation will be available when the changes go live,
the results of and changes to some API methods are:

listSubscribe() and listUpdateMember():
* the INTERESTS parameter in merge_vars, including when used with
replace_interests, will *only* affect the default grouping, not all
groupings.
* each will also start accepting a GROUPINGS parameter which will "Set
Interest Groups by Grouping. Each element in this array should be an
array containing the "groups" parameter (same restrictions as
INTERESTS above) and either an "id" or "name" parameter to specify the
Grouping"


listInterestGroups() will *always* return the data for Group Id 1.
listInterestGroupings() is new will return essentially the same data
for both/all groupings created (we've also added some extra data to
it)

listAddInterestGroup($list_id, 'New Group Name!') will add the new
group to Group Id 1
listAddInterestGroup($list_id, 'New Group Name!', 1) will add the new
group to Group Id 1
listAddInterestGroup($list_id, 'New Group Name!', 2) will add the new
group to Group Id 2
listAddInterestGroup($list_id, 'Chimps') will throw an error because
there is already a "Chimps" group in Group Id 1
listAddInterestGroup($list_id, 'Chimps',2) will add the new group to
Group Id 2

listDelInterestGroup($list_id, 'Chimps') will delete the "Chimps"
group from Group Id 1
listDelInterestGroup($list_id, 'Chimps', 1) will delete the "Chimps"
group from Group Id 1
listDelInterestGroup($list_id, 'Blue', 2) will delete the "Blue" group
from Group Id 2
listDelInterestGroup($list_id, 'Chimps', 2) will throw an erro because
the "Chimps" group is not in Group Id 2

listRenameInterestGroup($list_id, 'Chimps', 'Chumps') will rename
"Chimps" group in Group Id 1
listRenameInterestGroup($list_id, 'Chimps', 'Chumps',1) will rename
"Chimps" group in Group Id 1
listRenameInterestGroup($list_id, 'Green', 'Black',2) will rename
"Green" group in Group Id 2
listRenameInterestGroup($list_id, 'Chimps', 'Chumps',2) will throw an
error since the "Chimps" group doesn't exist in Group Id 2

Again, just to reiterate, all changes are backwards compatible. In
cases where method signature have changed, the additional parameter is
completely optional.

--
You received this message because you are subscribed to the Google Groups "MailChimp API Announce" group.
To post to this group, send email to mailchimp-a...@googlegroups.com.
To unsubscribe from this group, send email to mailchimp-api-ann...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/mailchimp-api-announce?hl=en.