/// <summary>
/// 360 Examples. This example requires you to create a test 360
/// project that contains an inbound and outbound 360 API connection
/// node, and the ID of a contact to test with.
///
/// NOTE that this will remove things from outbound nodes. Make sure
/// your project you test with is indeed a testing project.
/// </summary>
public void SimplyCast360Example(int contactID, int projectID, int inboundConnectionID, int outboundConnectionID)
{
SimplyCast360.Responses.ProjectEntity project = api.SimplyCast360.GetProject(projectID);
Console.WriteLine("Loaded 360 project '" + project.Name + "'");
ContactManager.Responses.ContactEntity contact = api.ContactManager.GetContact(contactID);
Console.WriteLine("Loaded contact " + contact.ID);
int listID = 0;
if (contact.Lists.Length == 0)
{
throw new Exception("The test contact must belong to at least one list.");
}
listID = contact.Lists[0].ID;
api.SimplyCast360.PushContact(projectID, inboundConnectionID, listID, contactID);
Console.WriteLine("Pushed contact to inbound node.");
Console.WriteLine("Reading from outbound node to see if any contacts have arrived");
SimplyCast360.Responses.ContactCollection contacts = api.SimplyCast360.GetOutboundContacts(projectID, outboundConnectionID);
//Iterate through each contact and remove them from the outbound
//node.
if (contacts != null && contacts.Contacts.Length > 0)
{
foreach (SimplyCast360.Responses.ContactEntity c in contacts.Contacts)
{
Console.WriteLine("Found contact " + c.ContactID);
api.SimplyCast360.DeleteContact(projectID, outboundConnectionID, c.ID);
Console.WriteLine("Removed contact " + c.ContactID + " (360 ID " + c.ID + ") from outbound node.");
}
}
else
{
Console.WriteLine("No contacts in outbound node.");
}
Console.Write("Press enter to continue...");
Console.Read();
}
/// <summary>
/// Examples of contact management resources.
/// </summary>
public void ContactManagementExample()
{
ContactManager.Responses.ListEntity list;
//Create a testing list.
try
{
list = api.ContactManager.CreateList("test list");
}
catch (APIException)
{
list = api.ContactManager.GetListsByName("test list").Lists[0];
}
Console.WriteLine("Created test list " + list.ID);
//Retrieve our column mapping. We can use this to find out the
//column IDs we'll need when setting contact fields.
ContactManager.Responses.ColumnCollection columns = api.ContactManager.GetColumns();
//Build up our contact data. Notice that we're using the column ID
//as the field key, *not* the column name.
Dictionary <string, string> fields = new Dictionary <string, string>();
fields.Add(columns.GetByName("email").ID, "*****@*****.**");
fields.Add(columns.GetByName("name").ID, "Test Contact");
//Create a new contact, and assign them to the test list at the
//same time.
ContactManager.Responses.ContactEntity contact = api.ContactManager.CreateContact(fields, new int[] { list.ID });
Console.WriteLine("Created contact " + contact.ID);
//Attempt an 'upsert operation' on the created contact. The name
//should be updated to the given value.
Console.WriteLine("Attempting upsert (should update contact " + contact.ID + ").");
fields[columns.GetByName("name").ID] = "Updated Test Contact";
ContactManager.Responses.ContactCollection contacts = api.ContactManager.UpsertContact(fields, columns.GetByName("email").ID);
foreach (ContactManager.Responses.ContactEntity c in contacts.Contacts)
{
Console.WriteLine("Updated contact " + c.ID + " (email address: " + c.GetFieldsByName("email")[0].Value + ") to have name '" + c.GetFieldsByName("name")[0].Value + "'.");
}
//Run a query on the contact database to retrieve our contact.
//A contrived example, but an example nonetheless. The syntax
//is detailed in the online documentation, but basically looks
//something like: '`colID` = "value" AND `col2ID` = "other value"'
string query = "`" + columns.GetByName("email").ID + "` = \"[email protected]\" AND `"
+ columns.GetByName("name").ID + "` = \"Updated Test Contact\"";
Console.WriteLine("Executing query: " + query);
ContactManager.Responses.ContactCollection queryResult = api.ContactManager.GetContacts(0, 100, query);
if (queryResult.Contacts.Length > 0)
{
Console.WriteLine("Ran search query and found " + queryResult.Contacts.Length + " contacts");
}
else
{
Console.WriteLine("Ran search query and found no contacts.");
}
//Retrieve a field by its name, and get the value from it.
string email = contact.GetFieldsByName("email")[0].Value;
Console.WriteLine("\tContact email: " + email);
//Output each list that the contact belongs to (should only be our
//test list).
foreach (ContactManager.Responses.ListEntity l in contact.Lists)
{
Console.WriteLine("\tContact belongs to list " + l.ID);
}
//Change the contact's phone number.
Dictionary <string, string> updateFields = new Dictionary <string, string>();
updateFields.Add(columns.GetByName("phone").ID, "15555551234");
contact = api.ContactManager.UpdateContact(contact.ID, updateFields);
Console.WriteLine("Updated phone number: " + contact.GetFieldsByName("phone")[0].Value);
//Add tags to a contact.
ContactManager.Responses.MetadataColumnCollection metadataColumns = api.ContactManager.GetMetadataColumns();
string metadataFieldID = metadataColumns.GetByName("Tags").ID;
api.ContactManager.UpdateContactMetadataField(contact.ID, metadataFieldID, new string[] { "tag 1", "tag 2" });
Console.WriteLine("Updated metadata tags");
//Get metadata tags and display them.
ContactManager.Responses.MetadataFieldEntity metadataField = api.ContactManager.GetContactMetadataFieldByName(contact.ID, "Tags").MetadataFields[0];
Console.WriteLine("Retrieved metadata tags.");
foreach (string value in metadataField.Values)
{
Console.WriteLine("\tMetadata tag: " + value);
}
//Delete our test list
api.ContactManager.DeleteList(list.ID);
Console.WriteLine("Deleted test list");
//Refresh the contact and see if it still belongs to the list.
contact = api.ContactManager.GetContact(contact.ID);
Console.WriteLine("Contact belongs to " + contact.Lists.Length + " lists");
api.ContactManager.DeleteContact(contact.ID);
Console.WriteLine("Deleted contact.");
Console.Write("Press enter to continue...");
Console.Read();
}
/// <summary>
/// Metadata column management examples.
/// </summary>
public void MetadataColumnManagementExample()
{
//Create a new contact to test with.
ContactManager.Responses.ColumnCollection columns = api.ContactManager.GetColumns();
Dictionary <string, string> fields = new Dictionary <string, string>();
fields.Add(columns.GetByName("email").ID, "*****@*****.**");
fields.Add(columns.GetByName("name").ID, "Test Contact");
ContactManager.Responses.ContactEntity contact = api.ContactManager.CreateContact(fields);
Console.WriteLine("Created test contact " + contact.ID);
ContactManager.Responses.MetadataColumnCollection metadataColumns = api.ContactManager.GetMetadataColumns();
Console.WriteLine("Retrieved all metadata columns.");
//Add new metadata columns.
if (metadataColumns.GetByName("Test Single Column") == null)
{
api.ContactManager.CreateMetadataColumn("Test Single Column", ContactManager.ContactManagerAPI.MetadataColumnType.SingleNumber);
}
if (metadataColumns.GetByName("Test Multi Column") == null)
{
api.ContactManager.CreateMetadataColumn("Test Multi Column", ContactManager.ContactManagerAPI.MetadataColumnType.MultiString);
}
if (metadataColumns.GetByName("Test Sum Column") == null)
{
api.ContactManager.CreateMetadataColumn("Test Sum Column", ContactManager.ContactManagerAPI.MetadataColumnType.SumNumber);
}
Console.WriteLine("Created metadata test columns.");
//Update our single number field to have the value 2.
ContactManager.Responses.MetadataFieldEntity singleColumn =
api.ContactManager.UpdateContactMetadataField(contact.ID, metadataColumns.GetByName("Test Single Column").ID, new string[] { "2" });
Console.WriteLine("Updated single column field with one integer.");
Console.WriteLine("Value: " + singleColumn.Values[0]);
//Update our multi-string field to have two values.
ContactManager.Responses.MetadataFieldEntity multiColumn =
api.ContactManager.UpdateContactMetadataField(contact.ID, metadataColumns.GetByName("Test Multi Column").ID, new string[] { "test multi value 1", "test multi value 2" });
Console.WriteLine("Updated multi-valued field with two strings.");
foreach (string value in multiColumn.Values)
{
Console.WriteLine("Value: " + value);
}
//"Sum number" fields are incrementers. Updating the field with a
//number will actually add to the existing value, rather than
//replacing it.
ContactManager.Responses.MetadataFieldEntity sumColumn = new ContactManager.Responses.MetadataFieldEntity();
for (int i = 0; i < 4; i++)
{
sumColumn = api.ContactManager.UpdateContactMetadataField(contact.ID, metadataColumns.GetByName("Test Sum Column").ID, new string[] { "1" });
Console.WriteLine("Incremented sum number field by 1");
Console.WriteLine("Value: " + sumColumn.Values[0]);
}
api.ContactManager.DeleteMetadataColumn(singleColumn.ID);
api.ContactManager.DeleteMetadataColumn(multiColumn.ID);
api.ContactManager.DeleteMetadataColumn(sumColumn.ID);
Console.WriteLine("Removed test metadata columns.");
api.ContactManager.DeleteContact(contact.ID);
Console.WriteLine("Removed test contact " + contact.ID);
Console.Write("Press enter to continue...");
Console.Read();
}
/// <summary>
/// List management resource examples.
/// </summary>
public void ListManagementExample()
{
//Create a new list.
ContactManager.Responses.ListEntity list = api.ContactManager.CreateList("My new list");
Console.WriteLine("Created list " + list.ID);
//Trivially retrieve the new list again, using the ID.
list = api.ContactManager.GetList(list.ID);
Console.WriteLine("Retrieved list " + list.ID + " by ID");
//Retrieve the same list again, this time by name. Since lists can
//possibly share a name, error conditions are avoided by returning
//a collection of lists instead of a single list.
ContactManager.Responses.ListCollection lists = api.ContactManager.GetListsByName("My new list");
if (lists.Lists.Length > 0)
{
list = lists.Lists[0];
}
Console.WriteLine("Retrieved list " + list.ID + " by name");
//Create a new contact and add it to our list. You can also add
//lists upon creation of a contact as the second parameter
//(example in the contact management example).
ContactManager.Responses.ColumnCollection columns = api.ContactManager.GetColumns();
Dictionary <string, string> fields = new Dictionary <string, string>();
//Fields are added by column ID, not by the name of the column. You
//can get the ID of a column by calling GetByName() on a column
//collection.
fields.Add(columns.GetByName("email").ID, "*****@*****.**");
ContactManager.Responses.ContactEntity contact = api.ContactManager.CreateContact(fields);
api.ContactManager.AddContactsToList(list.ID, new int[] { contact.ID });
Console.WriteLine("Added contact " + contact.ID + " to list " + list.ID);
//Rename our list.
list = api.ContactManager.RenameList(list.ID, "New list name.");
Console.WriteLine("Renamed list to '" + list.Name + "'");
//Delete the list. This doesn't delete the contacts within the
//list; they'll still exist and may still be in other extant
//lists.
api.ContactManager.DeleteList(list.ID);
Console.WriteLine("Deleted list.");
Console.Write("Press enter to continue...");
Console.Read();
}
/// <summary>
/// Example of creating multiple contacts via batch. Also provides an
/// example of updating existing contacts by merging upon an existing
/// column (this will create a new contact if there are no merge
/// candidates).
///
/// Note that this is functionality is not backwards-compatible with
/// version 1.1. Because merging upon a column could return one or
/// more contact responses (if multiple merge candidates are found),
/// ContactBatchResult now contains a ContactCollection object instead
/// of a ContactEntity object. The example is updated to show the new
/// usage.
/// </summary>
public void ContactBatchExample()
{
//Get the email and name column IDs. You should probably do validation on the response ;)
string emailColumnID = api.ContactManager.GetColumnsByName("email").Columns[0].ID;
string nameColumnID = api.ContactManager.GetColumnsByName("name").Columns[0].ID;
//Precreate a contact to test the 'upsert' merge functionality.
Dictionary <string, string> fields = new Dictionary <string, string>();
fields.Add(emailColumnID, "*****@*****.**");
fields.Add(nameColumnID, "This name should be overwritten");
ContactManager.Responses.ContactEntity contact = api.ContactManager.CreateContact(fields);
Console.WriteLine("Created inital contact (ID: " + contact.ID + ") with name '" + contact.GetFieldsByName("name")[0].Value + "'.");
List <ContactManager.Requests.ContactEntity> contacts = new List <ContactManager.Requests.ContactEntity>();
for (int i = 0; i < 3; i++)
{
ContactManager.Requests.ContactEntity c = new ContactManager.Requests.ContactEntity();
c.Fields = new ContactManager.Requests.FieldEntity[] {
new ContactManager.Requests.FieldEntity(emailColumnID, "example+" + i + "@example.com"),
new ContactManager.Requests.FieldEntity(nameColumnID, "Jane Doe")
};
contacts.Add(c);
}
Console.WriteLine("Submitting " + contacts.Count.ToString() + " contacts to a batch create.");
//Supply the email column as the merge row.
ContactManager.Responses.ContactBatchResponse response = api.ContactManager.BatchCreateContacts(contacts.ToArray(), emailColumnID);
Console.WriteLine("Submitted batch job. ID is " + response.ID.ToString() + ".");
// Wait for the batch to complete.
do
{
response = api.ContactManager.GetBatchStatus(response.ID);
Console.WriteLine("[" + System.DateTime.Now.ToLongTimeString() + "] Current status is: " + response.Status.ToString());
System.Threading.Thread.Sleep(5000);
} while (response.Status != ContactManager.Responses.ContactBatchResponse.BatchStatus.Complete &&
response.Status != ContactManager.Responses.ContactBatchResponse.BatchStatus.Error);
ContactManager.Responses.ContactBatchResultCollection results = api.ContactManager.GetBatchResult(response.ID);
foreach (ContactManager.Responses.ContactBatchResult result in results.Results)
{
//Output information about the created contacts, showing that we did indeed merge the
//new contact information in. We're assuming that there is only one contact returned
//as a result of each contact batch operation in the request, but there could be more.
Console.WriteLine("Created / updated contact " + result.ContactCollection.Contacts[0].ID + " (" +
result.ContactCollection.Contacts[0].GetFieldsByName("email")[0].Value + " / " +
result.ContactCollection.Contacts[0].GetFieldsByName("name")[0].Value + ").");
Console.WriteLine("Cleaning up: removing contact " + result.ContactCollection.Contacts[0].ID + ".");
api.ContactManager.DeleteContact(result.ContactCollection.Contacts[0].ID);
}
Console.Write("Press enter to continue...");
Console.ReadLine();
}
/// <summary>
/// Perform an upsert operation by either creating a contact or merging
/// the given data into all contacts that match the provided merge
/// column. For example, if the email field is provided in the fields
/// parameter and is also specified as the merge column, all contacts
/// with that email value will have their entries updated with the new
/// data. If there is no match, a new contact will be created.
/// </summary>
/// <param name="fields">The fields to create / update.</param>
/// <param name="mergeColumnID">The column ID to merge upon.</param>
/// <returns>A collection containing all contacts modified by the
/// <param name="listIDs">An array of list IDs to add the contact(s) to.
/// </param>
/// operation.</returns>
public Responses.ContactCollection UpsertContact(Dictionary <string, string> fields, string mergeColumnID, int[] listIDs)
{
Dictionary <string, string> queryParameters = new Dictionary <string, string>();
queryParameters.Add("mergecolumn", mergeColumnID);
Requests.ContactEntity contact = new Requests.ContactEntity();
Requests.FieldEntity[] fieldArray = new Requests.FieldEntity[fields.Count];
int fieldCounter = 0;
foreach (KeyValuePair <string, string> f in fields)
{
Requests.FieldEntity fieldEntity = new Requests.FieldEntity();
fieldEntity.ID = f.Key;
fieldEntity.Value = f.Value;
fieldArray[fieldCounter++] = fieldEntity;
}
contact.Fields = fieldArray;
if (listIDs.Length > 0)
{
int listCounter = 0;
Requests.ListEntity[] listArray = new Requests.ListEntity[listIDs.Length];
foreach (int id in listIDs)
{
Requests.ListEntity listEntity = new Requests.ListEntity();
listEntity.ID = id;
listArray[listCounter++] = listEntity;
}
contact.ListIds = listArray;
}
contact.ID = null;
string xml = this.connection.Call <string>("POST", "contactmanager/contacts", queryParameters, contact);
//We're going to deserialize ourselves, since the response could be
//either a contact collection or a contact entity. We're going to
//turn the contact entity into a collection for consistency.
using (System.Xml.XmlReader reader = new System.Xml.XmlTextReader(new System.IO.StringReader(xml)))
{
//If it's a collection, return it.
System.Xml.Serialization.XmlSerializer serializer = new System.Xml.Serialization.XmlSerializer(typeof(Responses.ContactCollection));
if (serializer.CanDeserialize(reader))
{
return((Responses.ContactCollection)serializer.Deserialize(reader));
}
serializer = new System.Xml.Serialization.XmlSerializer(typeof(Responses.ContactEntity));
//If it's an entity, create a collection and put the contact in it.
if (serializer.CanDeserialize(reader))
{
Responses.ContactEntity c = (Responses.ContactEntity)serializer.Deserialize(reader);
Responses.ContactCollection contactCollection = new Responses.ContactCollection();
contactCollection.Contacts = new Responses.ContactEntity[] { (Responses.ContactEntity)c };
return(contactCollection);
}
else
{
throw new Exception("Invalid XML response: could not deserialize into a ContactEntity or ContactCollection.");
}
}
}
