Working with Dynamics CRM Activity Party Lists in C# Plugins

Paul Nieuwelaar, 07 September 2015

Every time I have to do something with activities in CRM it ends up taking way longer than expected. Unlike most entities in CRM, activities have a lot of unusual relationships and field types, not to mention all the behind the scenes processes which tend to not like when you introduce your own custom logic.

In this blog post I want to simply look at party list fields, and how to read and update the field values.

An activity partylist field is like the To, CC, BCC fields on an email – they can contain multiple entity references, and they can also contain different entity types (contact, user etc). When we for example do a retrieve on the email entity using the SDK, the ‘to’ field is of type EntityCollection.

If we break this down, each Entity in the collection is an ‘activityparty’. The Activity Party entity is the intercept entity for all the activity party list fields. Activity parties are not only used for the party list fields however, they’re also used for the regarding and appointment organizer etc.

So what fields do we get from each of the activity party Entity objects?

If we break it down, it has 3 main fields. The partyid, which is the actual EntityReference to the contact, user, account etc which is being referenced. The addressused, which is only really used when emails or appointments are tracked from outlook; this is the actual email address of the recipient that CRM used to match it to a record. Finally there is a field called ispartydeleted, which simply tells us if the record behind the activity party has been deleted; since CRM does not delete the activity party, nor does it clear the partyid, this is the only way of knowing that the record actually exists (without trying to retrieve it or something).

Entity email = _sdk.Retrieve("email", emailId, new ColumnSet("to"));

EntityCollection to = email.GetAttributeValue<EntityCollection>("to");
if (to != null)
{
    to.Entities.ToList().ForEach(party =>
    {
        EntityReference partyId = party.GetAttributeValue<EntityReference>("partyid");
        bool isDeleted = party.GetAttributeValue<bool>("ispartydeleted");
        string addressUsed = party.GetAttributeValue<string>("addressused");

        // Do something...
    });
}

When you’re creating an activity party, you need to set the partyid and/or the addressused. You must set at least one, and they cannot be null – so make sure not to add it to the property bag if there’s no value. CRM will throw an error if neither attribute is set, or if you explicitly set one of the attributes to null.

If you specify an addressused and not a partyid, the activity party will be ‘unresolved’ on the activity. It will display as just the email address, with a red font.

You don’t need to do an SDK Create or Update request on activity parties, just update the EntityCollection and add it back into the parent activity ‘to’ or ‘cc’ field etc and then update/create the activity – CRM will take care of creating or updating the parties.

If you’re copying activity parties from one activity to another, or from one partylist field to another, make sure to remove the activitypartyid from the Entity objects, as these are unique for each party. Simply leave this field out of the attributes list so that CRM will create a new activity party.

// Create a new activity party linked to a contact
Entity party1 = new Entity("activityparty");
party1["addressused"] = "some@email.com";
party1["partyid"] = new EntityReference("contact", contactId);

// Create a new unresolved activity party
Entity party2 = new Entity("activityparty");
party2["addressused"] = "unresolved@email.com";

// Create a new EntityCollection and add the 2 parties
EntityCollection to = new EntityCollection();
to.Entities.Add(party1);
to.Entities.Add(party2);

// Create an email with the EntityCollection
Entity email = new Entity("email");
email["subject"] = "Test Party Lists";
email["to"] = to;

_sdk.Create(email);

If you want to delete an activity party, simply remove it from the EntityCollection. CRM will take care of deleting the activity party record behind the scenes. This example removes the unresolved and deleted parties from the ‘to’ field.

Guid emailId = new Guid("1EFCBB18-F3B6-E411-80BA-00155D048D48");
Entity email = _sdk.Retrieve("email", emailId, new ColumnSet("to"));

EntityCollection to = email.GetAttributeValue<EntityCollection>("to");
if (to != null)
{
    to.Entities.ToList().ForEach(party =>
    {
        EntityReference partyId = party.GetAttributeValue<EntityReference>("partyid");
        bool isDeleted = party.GetAttributeValue<bool>("ispartydeleted");
        string addressUsed = party.GetAttributeValue<string>("addressused");

        if (isDeleted || partyId == null)
        {
            to.Entities.Remove(party);
        }
    });
}

email["to"] = to;

_sdk.Update(email);