This sample code shows how to send a bulk e-mail and monitor its progress.
1: //# Send a Bulk E-mail and Monitor the Job
2: using System;
3: using CrmSdk;
4: using Microsoft.Crm.Sdk.Utility;
5:
6: namespace Microsoft.Crm.Sdk.HowTo.BulkOperation
7: { 8: public class SendBulkEmailAndMonitor
9: { 10: public SendBulkEmailAndMonitor()
11: { 12:
13: }
14:
15: public static bool Run(string crmServerUrl, string orgName)
16: { 17: bool success = false;
18:
19: try
20: { 21: // Set up the CRM Service.
22: CrmService service = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.GetCrmService(crmServerUrl, orgName);
23: service.PreAuthenticate = true;
24:
25: // Create some contacts to send a bulk e-mail to.
26: // Typically, this would be an existing list of customers, such as a marketing list.
27: object[] contactIds = new object[2];
28:
29: contact emailContact1 = new contact();
30: emailContact1.firstname = "Adam";
31: emailContact1.lastname = "Carter";
32: emailContact1.emailaddress1 = "adam.carter@example.com";
33:
34: // Create the contact.
35: contactIds[0] = service.Create(emailContact1);
36:
37: contact emailContact2 = new contact();
38: emailContact2.firstname = "Adina";
39: emailContact2.lastname = "Hagege";
40: emailContact2.emailaddress1 = "adina.hagege@example.com";
41:
42: // Create the contact.
43: contactIds[1] = service.Create(emailContact2);
44:
45: // Create the bulk mail request.
46: SendBulkMailRequest bulkMailRequest = new SendBulkMailRequest();
47:
48: // Create a query expression for the bulk operation to use to retrieve
49: // the contacts in our e-mail list.
50: ConditionExpression condition = new ConditionExpression();
51: condition.AttributeName = "contactid";
52: condition.Operator = ConditionOperator.In;
53: condition.Values = contactIds;
54:
55: FilterExpression filterExpression = new FilterExpression();
56: filterExpression.Conditions = new ConditionExpression[] { condition }; 57:
58: ColumnSet returnColumns = new ColumnSet();
59: returnColumns.Attributes = new string[] { "contactid" }; 60:
61: QueryExpression queryRequest = new QueryExpression();
62: queryRequest.ColumnSet = returnColumns;
63: queryRequest.EntityName = EntityName.contact.ToString();
64: queryRequest.Criteria = filterExpression;
65:
66: // Attach the contact query to the bulk e-mail request.
67: bulkMailRequest.Query = queryRequest;
68:
69: // Get a system user to use as the sender.
70: bulkMailRequest.Sender = GetEmailSenderMoniker(service);
71:
72: // Set the RegardingId to the e-mail sender.
73: bulkMailRequest.RegardingId = bulkMailRequest.Sender.Id;
74: bulkMailRequest.RegardingType = EntityName.systemuser.ToString();
75:
76: // Use a built-in e-mail template.
77: // NOTE: The e-mail template's 'template type' must match the type of customers
78: // in the e-mail list. Our list contains contacts, so our template must be for contacts.
79: bulkMailRequest.TemplateId = new Guid("07B94C1D-C85F-492F-B120-F0A743C540E6"); 80:
81: // Create a tracking ID for the bulk operation to monitor its progress.
82: RequestIdOptionalParameter trackingId = new RequestIdOptionalParameter();
83: trackingId.Value = Guid.NewGuid();
84:
85: // Attach the tracking ID to the bulk e-mail request.
86: bulkMailRequest.OptionalParameters = new OptionalParameter[] { trackingId }; 87:
88: // Execute the async bulk e-mail request.
89: service.Execute(bulkMailRequest);
90:
91: // Now that we have executed the bulk operation, we have to retrieve it using our tracking ID.
92: ColumnSet asyncColumns = new ColumnSet();
93: asyncColumns.Attributes = new string[] { "requestid", "statecode" }; 94:
95: QueryByAttribute bulkQuery = new QueryByAttribute();
96: bulkQuery.ColumnSet = asyncColumns;
97: bulkQuery.EntityName = EntityName.asyncoperation.ToString();
98: bulkQuery.Attributes = new string[] { "requestid" }; 99: bulkQuery.Values = new object[1];
100: bulkQuery.Values[0] = trackingId.Value;
101:
102: // Retrieve the bulk e-mail async operation.
103: BusinessEntityCollection aResponse = service.RetrieveMultiple(bulkQuery);
104:
105: // Monitor the async operation through polling.
106: const int ARBITRARY_MAX_POLLING_TIME = 60;
107: int secondsTicker = ARBITRARY_MAX_POLLING_TIME;
108:
109: asyncoperation createdBulkMailOperation = null;
110:
111: while (secondsTicker > 0)
112: { 113: // Make sure that the async operation was retrieved.
114: if (aResponse.BusinessEntities.Length > 0)
115: { 116: // Grab the one bulk operation that was created.
117: createdBulkMailOperation = (asyncoperation)aResponse.BusinessEntities[0];
118:
119: // Check the operation's state.
120: if (createdBulkMailOperation.statecode.Value != AsyncOperationState.Completed)
121: { 122: // The operation has not yet completed. Wait a second for the status to change.
123: System.Threading.Thread.Sleep(1000);
124: secondsTicker--;
125:
126: // Retrieve a fresh version the bulk delete operation.
127: aResponse = service.RetrieveMultiple(bulkQuery);
128: }
129: else
130: { 131: // Stop polling because the operation's state is now completed.
132: secondsTicker = 0;
133: }
134: }
135: else
136: { 137: // Wait a second for the async operation to become active.
138: System.Threading.Thread.Sleep(1000);
139: secondsTicker--;
140:
141: // Retrieve the entity again.
142: aResponse = service.RetrieveMultiple(bulkQuery);
143: }
144: }
145:
146: // When the bulk e-mail operation has finished, all sent e-mail messages will have a status of "Pending Send" and
147: // will be picked up by your e-mail router. Or, you can then use BackgroundSendEmail to download
148: // all the e-mail messages that were created by using the SendBulkEmail message. See the BackgroundSendEmail sample for an example.
149:
150: #region check success
151:
152: // Validate async operation succeeded.
153: if (createdBulkMailOperation.statecode.Value == AsyncOperationState.Completed)
154: { 155: success = true;
156: }
157:
158: #endregion
159:
160: #region Remove Data Required for this Sample.
161:
162: // Delete the sent e-mail messages.
163: ColumnSet sentMailColumns = new ColumnSet();
164: sentMailColumns.Attributes = new string[] { "statuscode" }; 165:
166: ConditionExpression statusCondition = new ConditionExpression();
167: statusCondition.AttributeName = "statuscode";
168: statusCondition.Operator = ConditionOperator.Equal;
169: statusCondition.Values = new object[] { EmailStatus.PendingSend }; 170:
171: // Create the query filter.
172: FilterExpression emailFilter = new FilterExpression();
173: emailFilter.Conditions = new ConditionExpression[] { statusCondition }; 174: emailFilter.FilterOperator = LogicalOperator.And;
175:
176: // Query for e-mail activity.
177: QueryExpression emailsQuery = new QueryExpression();
178: emailsQuery.ColumnSet = sentMailColumns;
179: emailsQuery.EntityName = EntityName.email.ToString();
180: emailsQuery.Criteria = emailFilter;
181:
182: // Retrieve the e-mail activity.
183: BusinessEntityCollection emails = service.RetrieveMultiple(emailsQuery);
184:
185: foreach (email sentMail in emails.BusinessEntities)
186: { 187: service.Delete(EntityName.email.ToString(), sentMail.activityid.Value);
188: }
189:
190: // Delete the contacts created for e-mails.
191: foreach (Guid createdContactId in contactIds)
192: { 193: service.Delete(EntityName.contact.ToString(), createdContactId);
194: }
195:
196: #endregion
197: }
198: catch (System.Web.Services.Protocols.SoapException)
199: { 200: // Perform error handling here.
201: throw;
202: }
203: catch (Exception)
204: { 205: throw;
206: }
207:
208: return success;
209: }
210:
211: /// <summary>
212: /// Retrieves a systemuser to use as the sender of an e-mail.
213: /// </summary>
214: /// <param name="service">The CRM service</param>
215: /// <returns>Moniker to use as e-mail sender</returns>
216: public static Moniker GetEmailSenderMoniker(CrmService service)
217: { 218: Moniker emailSender = new Moniker();
219:
220: ColumnSet selectClause = new ColumnSet();
221: selectClause.Attributes = new string[] {"fullname"}; 222:
223: QueryExpression allSystemUsersQuery = new QueryExpression();
224: allSystemUsersQuery.EntityName = EntityName.systemuser.ToString();
225: allSystemUsersQuery.ColumnSet = selectClause;
226:
227: // Create the query request.
228: RetrieveMultipleRequest allSystemUsersRequest = new RetrieveMultipleRequest();
229: allSystemUsersRequest.Query = allSystemUsersQuery;
230:
231: // Execute the request.
232: RetrieveMultipleResponse allSystemUsersResponse = (RetrieveMultipleResponse)service.Execute(allSystemUsersRequest);
233:
234: // Grab a system user for the bulk e-mail.
235: if (allSystemUsersResponse.BusinessEntityCollection.BusinessEntities.Length > 0)
236: { 237: // For demonstration, grab the first system user.
238: systemuser emailUser = (systemuser)allSystemUsersResponse.BusinessEntityCollection.BusinessEntities[0];
239: emailSender.Id = emailUser.systemuserid.Value;
240: emailSender.Name = EntityName.systemuser.ToString();
241: }
242: else
243: { 244: // If no system user was found, we cannot continue with bulk e-mail.
245: throw (new Exception("No system user found to send e-mail.")); 246: }
247:
248: return emailSender;
249: }
250: }
251: }
