This documentation is archived and is not being maintained.

Create a Distribution Group

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Creating a distribution group amounts to publishing the e-mail address and private ID of an existing distribution group as an IUccGroup object to Office Communications Server. The publishing action adds a reference to the distribution group and any nested distribution groups to your contact list. The source of the distribution group is the Active Directory maintained by your organization. Distribution group membership is updated globally by a server administrator. You cannot add or remove distribution group members from a client. A distribution group is considered read-only from the client but you have the ability to request distribution group expansion to see individual members.

When a local user includes a distribution group in her contact list, the distribution group is provided to the local client in unexpanded form. Making a distribution group expansion request requires a single XML message to a dedicated Web service. The Web service returns a SOAP packet containing the expanded distribution group. The Office Communicator-hosted Web service provides distribution group data with the following limitations:

  • Federated distribution groups can be added to your contact list but they cannot be searched or expanded.
  • Distribution group expansion is limited to 100 entries. A distribution group with no nested entries returns up to 100 contacts. Expanding a distribution group that includes nested distribution groups and contacts returns up to 100 entries composed of un-expanded distribution group entries and individual contacts. Nested groups do not expand if the action causes the total entries returned to exceed 100. The total number of entries in the expanded distribution group count against your subscription limit of 300 total contacts.
  • Distribution group nesting is limited to 10 levels.

The distribution group has many benefits including:

  • Bulk contact adding. Distribution groups are an easy way to bulk add contacts to the contact list.
  • Group membership maintenance. No need to constantly keep track and update which contacts are in a group. The membership roles are maintained on Office Communications Server automatically. The distribution group is considered to be read-only from the client.
  • Consistency. Everyone who has the distribution group in his contact list sees the same set of members.
  • Presence. See presence of individual members in the distribution group and selectively communicate with those people.
  • Group tasks. With distribution groups, you can perform a set of actions on the group as a whole. For example, you can initiate an IM conference by adding the distribution group as a participant to the IM session. Every member of the distribution group is automatically invited to the conference.

Unified Communications Client API gives you the ability to add a collapsed distribution group to your contact list. To expand the distribution group and expose the individual members, you must make a SOAP request to a Web service dedicated to this purpose. The URL of the Web service is provided to your client application through in-band provisioning from Office Communications Server. The service is provided by the Live Server Distribution List Expander supported by Office Communications Server.

You are responsible for creating the SOAP request, communicating with the service using the provided URL, and parsing the response from the service. For information about getting the distribution group expansion Web service URL, see Query Office Communications Server Configuration.

Creating a distribution group involves the following steps:

  • Create a publication manager object by casting an IUccEndpoint object into a IUccPublicationManager object. The publication manager is responsible for creating a publishable category instance object and publication object.
  • Create a publishable category instance representing the group to be added. In this example, the added group has no expiry date. For this reason, the enumeration value UCC_CATEGORY_INSTANCE_EXPIRATION_TYPE.UCCCIET_STATIC is used.
  • Set the publication operation on the created publishable category by filling the PublicationOperation property using a UCCP enumeration value UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_ADD.
  • Cast the IUccCategoryInstance object to the IUccGroup interface.
  • Set the group PrivateId property to the e-mail address of the distribution group.
  • Create a publication object by calling CreatePublication and casting the returned value to the IUccPublication interface.
  • Register for publication events to catch the asynchronous response to this publication request.
  • Add the IUccCategory instance created earlier to the publication with a call into AddPublishableCategoryInstance.
  • Publish the new group by calling the Publish method on the publication object. In this example, the optional Operation Context is not supplied with the request.
public void AddDGGroup(string groupEmail)
      IUccPublicationManager pubMgr = endpoint as IUccPublicationManager;
      //Create a publishable category instance representing the contact to be added
      IUccCategoryInstance cat = pubMgr.CreatePublishableCategoryInstance(

      //Set publication operation type for this category

      //Cast the category to IUccContact to set the URI of the contact to be added
      IUccGroup g = cat as IUccGroup;
      g.PrivateId = groupEmail;
      IUccPublication pub = pubMgr.CreatePublication() as IUccPublication;
      UCC_Advise<_IUccPublicationEvent>(pub, this);
   catch (COMException ex)