How to Retrieve an Activity Party List in Microsoft Dynamics 365 Using Web API
If you were to read the value of a Microsoft Dynamics 365 field in JavaScript, you would use Web API, wouldn’t you? That’s what I did, anyway, not realizing that you cannot read the Party List fields in the Web API directly.
Unlike most entities in Microsoft Dynamics 365, activities have a lot of unusual relationships and field types. Don’t worry, I will not let you go through the same pain I did. In this blog post I want to share how to retrieve Party List fields in Microsoft Dynamics 365 using Web API.
What is an Activity?
Before we dive in, we need to know what activities are. Activities are the actions users do in Microsoft Dynamics 365, often tracking the interaction between users and customers.
There are several different activities in Dynamics 365:
- Phone Call
- Task
- Letter
- Appointment
- Fax
Whenever you create any of the above entity records, a corresponding activity pointer record is created.
We can say that the Activity entity acts like an interface between primary entities and individual activities.
What is an Activity Party?
So now that we know what an activity is, let’s look at what an activity party is.
An activity can have multiple activity parties. It is a special entity that is used only to store the parties associated with any activity type.
You might have seen a special field with type Party List in all Activity entities. CRM Activity Party List field is a special type of lookup field which refers to multiple entities. This field is not directly visible in the Web API for the entity. To hold or store these multiple entities references, Microsoft has provided a special type of entity named Activity Party.
Activity Party has a special field called Party Id. which has the capability to store multiple entities references like user, contact, account, lead etc.
Microsoft defines activity party as, “An activity party represents a person or group associated with an activity”.
Where are these party lists used?
The most common area in CRM where Activity Party is used is the To and From in an Activity, for example in case of an email, letter etc.
The reason the ActivityParty is used is because an email can have multiple email addresses in the To, such as CC.
Examples of Party List fields are To, From, CC, BCC, Attendees etc.
How to read values from Web API/Java Script
Now since the concepts are clear, let’s come on to some real facts as to how to read these values from Web API/JavaScript.
There are 11 activity party types in Microsoft Dynamics CRM. The activity party type is stored as an integer value in the ActivityParty.ParticipationTypeMask .
The following table lists the different activity party types, the corresponding integer value for the ActivityParty.ParticipationTypeMask attribute.
Activity party type | Value | Description |
---|---|---|
Sender | 1 | Specifies the sender. |
ToRecipient | 2 | Specified the recipient in the To field. |
CCRecipient | 3 | Specifies the recipient in the Cc field. |
BccRecipient | 4 | Specifies the recipient in the Bcc field. |
RequiredAttendee | 5 | Specifies a required attendee. |
OptionalAttendee | 6 | Specifies an optional attendee. |
Organizer | 7 | Specifies the activity organizer. |
Regarding | 8 | Specifies the regarding item. |
Owner | 9 | Specifies the activity owner. |
Resource | 10 | Specifies a resource. |
Customer | 11 | Specifies a customer. |
How to build your Web API Query
Building your Web API Query is super simple.
- First, you need to access to the ActivityParty entity.
- Provide the activityId. This will be the GUID of your Activity (letter/email/task etc.).
- Provide the participationtypemask: It can be obtained from the table above, depending on the value you need to obtain (example to, from, CC etc.).
- You will need the field PartyId, which is the GUID of the Account/Contact/Lead. Using the partyId you can also determine the type of the entity.
Below is the JavaScript code I used to read the entity details in the To field of an activity.
(async (entityId)=>{
const activityEntity=await Xrm.Web API.retrieveMultipleRecords("activityparty", "?$filter=_activityid_value eq " +
entityId + " and participationtypemask eq 2&$select=_partyid_value,_activityid_value");
activityEntity.entities
.map(x => ({
id: x._partyid_value,
entityLogicalName: x['_partyid_value@Microsoft.Dynamics.CRM.lookuplogicalname'],
Name: x['_partyid_value@OData.Community.Display.V1.FormattedValue']}))
.forEach(console.log);
}
)('Your entity ID');
Output:
1. 0: {id: "fa8c729e-31b4-e911-a99d-000d3ab34f97", entityLogicalName: "account", Name: "proMX AG"}
2. 1: {id: "0f2ba5cd-34b4-e911-a996-000d3ab311f1", entityLogicalName: "contact", Name: "John Adam"}
3. 2: {id: "7ca6600e-2cb4-e911-a99d-000d3ab31f17", entityLogicalName: "contact", Name: "Manali Kapoor"}
Simpler than you thought it was, right?!
I hope this article helps you next time you face difficulties with Activities.