Home http://www.othenos.com developers of rich internet applications Mon, 18 Jan 2010 02:05:08 +0000 http://wordpress.org/?v=2.9.1 en hourly 1 MailChimp and Java Integration – Part 2 http://www.othenos.com/2010/01/17/mailchimp-and-java-integration-part-2/ http://www.othenos.com/2010/01/17/mailchimp-and-java-integration-part-2/#comments Sun, 17 Jan 2010 19:18:49 +0000 admin http://www.othenos.com/?p=321

In the previous article, we showed how to connection your Java application to MailChimp using the MailChimp api and the XML-RPC library provided by Zviki Cohen at nWire Software. The code in the article also provided a method to initialize the MailChimp mailing list by using the batch upload function in the api. This article will finish off the MailChimpHandler class by adding functionality to add, remove and update records to an existing list.

We are going to make use of two additional MailChimp api calls, listSubscribe and listUnsubscribe. Here is the completed MailChimpHandler class that adds the functionality of adding, removing and updating a record in the MailChimp list.

In a future, I'll post another article (or two) about how to get MailChimp to notify your Java application when changes are made to the mailing list (such as bounced emails, or a user unsubscribing from the list) so you can keep your contacts database in sync with changes made in the mailing list.

MailChimpHander Class (Version 2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177

public class MailChimpHandler implements IMailChimpHandler {
    private final Log log = LogFactory.getLog(getClass());
    // API Key - see http://admin.mailchimp.com/account/api or run login() once
    private String apiKey = "put your api key info here";
    // A List Id to run examples against. use lists() to view all
    // Also, login to MC account, go to List, then List Tools, and look for the
    // List ID entry
    private String listId = "put your list ID here";
    // Instance of the MailChimpServices
    private IMailChimpServices mcServices = null;
    // Flag indicating status of our connection to MailChimp
    private boolean connectionStatus;
    // Class to get the attributes associated with a company from database
    private ICompanyAttributesDao companyAttributesDao;
 
    public MailChimpHandler() {
        connectionStatus = false;
    }
 
    /**
    * prepare an instance of the MailChimpServices and determine
    * if we can connect using our apiKey.
    */
    private void initialize() {
        // OMITTED FOR BREVITY. SEE ARTICLE 1
    }
 
    /**
    * test the connection to see if it is still good
    * @return result
    */
    private boolean testConnection(){
        // OMITTED FOR BREVITY. SEE ARTICLE 1
    }
 
     /**
     * Performs the initialization of the mail chimp list by adding
     * all the appropriate customer contacts to the list
     * @param companyId (this is optional and only here because my application needs it. Yours almost certainly won't need it)
     * @return number of successful insertions
     */
     public int initializeMailChimpList(int companyId){
        // OMITTED FOR BREVITY. SEE ARTICLE 1
     }
 
    /**
    * add a new contact to the MailChimp List
    * @param contactId - I need this to get the contact info in question. You will use something else.
    * @return result
    */
    public boolean addUser(int contactId){
	boolean listSubscribe = false;
        // This will hold the contact data we are going to add to the mailing list
	final Map<String, String> merges = new HashMap<String, String>();
        // Get the new contact from the database. You will use something else to get your contact
	CustomerContact contact = customerContactDao.getMailChimpCustomerContact(contactId);
        // make sure we got it, else return
	if(contact == null)
		return listSubscribe;
 
	// make sure we have had a good connection, otherwise try it again	
	if (testConnection() == false){
		log.info("Attempting to re-connect to MailChimp");
		initialize();         // reinstantiate the MailChimpServices and test connection
	}
 
        // assuming we could connect, proceed
	if (connectedStatus) {
                // Add the new contact information into the Map
		merges.put("FNAME", contact.getFirstName());
		merges.put("LNAME", contact.getLastName());
		merges.put("EMAIL", contact.getEmail());
		merges.put("EMAIL_TYPE", "html");
                // Attempt to add the new contact using the listSubscribe api
                // 5th parameter is normally HTML. We set it here so we can specify 6th parameter
                // 6th parameter is whether double opt-in message is sent (defaults to true)
		try {
		        listSubscribe = mcServices.listSubscribe(apiKey, listId, contact.getEmail(), merges,
					IMailChimpServices.EMAIL_TYPE_HTML, false);
		} catch (MailChimpServiceException mcse) {
			log.error("Error in adding user to list. " + mcse.getMessage());
			mcse.printStackTrace();
		}
		log.info("listSubscribe: " + listSubscribe);
	}else
		log.info("Could not add user because could not connect to MailChimp");
 
        // return the result of our attempt to the caller 	
	return listSubscribe;
    }
 
    /**
    * update an existing contact to MailChimp. This is essentially like the addUser method
    * except we are unsubscribing the original email from the list before adding the new one.
    * In my circumstances, it is not really know what has changed on the contact&#39;s information.
    * It could be the email address. So this is why we unsubscribe the user from the list first
    * using their old email address (which could be the same as the new email address), then we
    * add the user back in. Regardless of what data had changed in the contact, the result is it
    * gets updated in the MailChimp list without creating a duplicate.
    * @param contactId - I need this to get the contact in question
    * @param oldEmail - this tells what the previous email was before the change
    * @return result
    */
    public boolean updateUser(int contactId, String oldEmail){
	boolean listSubscribe = false;
	final Map<String, String> merges = new HashMap<String, String>();
	CustomerContact contact = customerContactDao.getMailChimpCustomerContact(contactId);
	if(contact == null)
		return listSubscribe;
 
	// make sure we have had a good connection, otherwise try it again			
	if (testConnection() == false){
		log.info("Attempting to re-connect to MailChimp");
		initialize();
	}
 
        // make sure we have a connection
	if (connectedStatus) {
		// first UNSUBSCRIBE the original email address
                // the 4th parameter is to delete the existing MailChimp record (defaults false)
                // the 5th parameter is whether to send a goodbye message or not (defaults true)
                // the 6th parameter is whether to send a notification message or not (defaults true)
		try {
			listSubscribe = mcServices.listUnsubscribe(apiKey, listId, oldEmail, true, false, false);
		} catch (MailChimpServiceException mcse) {
			log.error("Error in unsubscribing user from list. " + mcse.getMessage());
			mcse.printStackTrace();
		}
		// then SUBSCRIBE the new email address
		merges.put("FNAME", contact.getFirstName());
		merges.put("LNAME", contact.getLastName());
		merges.put("EMAIL", contact.getEmail());
		merges.put("EMAIL_TYPE", "html");
		try {
			listSubscribe = mcServices.listSubscribe(apiKey, listId, contact.getEmail(), merges,
					IMailChimpServices.EMAIL_TYPE_HTML, false);
		} catch (MailChimpServiceException mcse) {
			log.error("Error in adding user to list. " + mcse.getMessage());
			mcse.printStackTrace();
		}
		log.info("listSubscribe: " + listSubscribe);
	}else
		log.info("Could not add user because could not connect to MailChimp");
	return listSubscribe;
    }
 
    /**
    * delete a contact from MailChimp. 
    * @param oldEmail - previous email address
    * @return result
    */
    public boolean deleteUser(String oldEmail){
	boolean listSubscribe = false;
 
	if (testConnection() == false){
		log.info("Attempting to re-connect to MailChimp");
		initialize();
	}
	// make sure we have a connection
	if (connectedStatus) {
		// UNSUBSCRIBE the original email address
                // the 4th parameter is to delete the existing MailChimp record (defaults false)
                // the 5th parameter is whether to send a goodbye message or not (defaults true)
                // the 6th parameter is whether to send a notification message or not (defaults true)
		try {
			listSubscribe = mcServices.listUnsubscribe(apiKey, listId, oldEmail, true, false, false);
		} catch (MailChimpServiceException mcse) {
			log.error("Error in unsubscribing user from list. " + mcse.getMessage());
			mcse.printStackTrace();
		}
		log.info("listSubscribe: " + listSubscribe);
	}else
		log.info("Could not remove user because could not connect to MailChimp");
	return listSubscribe;
    }
 
}
]]> http://www.othenos.com/2010/01/17/mailchimp-and-java-integration-part-2/feed/ 1 MailChimp and Java Integration – Part 1 http://www.othenos.com/2010/01/15/mailchimp-and-java-integration-part-1/ http://www.othenos.com/2010/01/15/mailchimp-and-java-integration-part-1/#comments Fri, 15 Jan 2010 19:21:13 +0000 admin http://www.othenos.com/?p=283 MailChimp™ is a great online email marketing site. It is extremely easy to use and provides tools to manage your email lists, build attractive HTML email campaigns, and track how those campaigns performed. On top of that, it offers a free account for smaller companies. How can you beat that? Those of you who are Java programmers might want to integrate your application with MailChimp. If so, then this is for you. These two articles are going to show you how to automatically create and update your MailChimp list using Java.

Assumptions

It is assumed that you have some kind of an existing list of customers, contacts or other names with email addresses that you have in a database and manage with a Java application. And, of course, you want to be able to populate a MailChimp list with these contact email addresses, as well as keep the list updated when contacts are added, modified or deleted. If either assumption is wrong, then probably these articles are not what you're looking for! But if their right, then read on. Article 1, will focus on getting everything setup and perform the initial upload of your existing contact information. Article 2, will finish up by creating the methods that will perform the continual additions, modifications and deletions to the list as your contacts change. So let's get started.

MailChimp Basics

OK. MailChimp is pretty straightforward. I am going to let you get familiar with setting up an account and creating a list. They have plenty of help to get you started. So, if you do not already have a MailChimp account, go and create one now, I'll wait. (Note that this article does not include any details on setting up the MailChimp account or creating your mailing lists, as there are sufficient resources at MailChimp to help with that.) If you have not already done so, review the MailChimp tutorials on setting up an account and creating your first mailing list. Then do both.

API Key

Once you have your account, go to the account page (button on upper left of page after sign-in). Click the API Keys and Info button. You are going to want to create an API Key for use by your Java application. This key essentially identifies your account and provides access to it. Add a key and then make a mental note of where this information is located, as we will be coming back here later to retrieve it.

List ID

You need to create a mailing list to hold the email information you are going to upload. Go ahead and create one using the default values. A mailing list that you create in MailChimp will have a unique alphanumeric identifier. This can be found by selecting a list, then clicking the list settings link. Towards the bottom of that page you will find the ID that has been assigned to the list in question. Again, we don't need it now but will later so make a note of where to find it.

Java Connections

The MailChimp api (1.2) provides several protocols for connecting to the MailChimp servers – XML-RPC, JSON, PHP. We are going to use XML-RPC. Zviki Cohen at nWire Software has provided a nice Java xml-rpc library as a starting point in our integration attempt with MailChimp. Download it from here. Read over the MailChimp api to become familiar with the operations that are possible. There are three basic groups of functions – list management, campaign creation and sending, and campaign statistics. We are only going to be using the list management portion of the api. In this article, we are only interested in testing the connection and doing a batch upload of our data into the MailChimp list. Zviki does not define all the list management functions in the IMailChimpServices interface but he defines enough for our purposes. You can easily add additional functions to the interface as needed.

Connecting to MailChimp

The first step in our integration process will be connecting to our account on the MailChimp server. To do so, we need to have our API Key handy.Using the XML-RPC library you just downloaded, we are going to create a class called MailChimpHandler which will be our entry point for all interactions between our Java application and the MailChimp server. This class will implement the methods we have defined in the IMailChimpHandler interface. Eventually, we are going to be able to initialize the mailing list with our current set of contacts, add records to the mailing list as we add more contacts to our database, update a record in MailChimp when a contact changes in our database, and delete a record from MailChimp when deleting a contact from the database. But for right now, we just want to insure we can create the MailChimpServices and connect to MailChimp.

MailChimpHandler interface
1
2
3
4
5
6
7
8

package com.othenos.mailchimp;
 
public interface IMailChimpHandler {
	public int initializeMailChimpList(int companyId);
	public boolean addUser(int contactId);
	public boolean updateUser(int contactId, String oldEmail);
	public boolean deleteUser(String oldEmail);
}
MailChimpHandler class (version 1).

This version simply tests to insure that we can make a connection to MailChimp using the provided API key and List ID. After instantiating an instance of MailChimpHandler, we can call the initializeMailChimpList method to upload our list of contacts. The method will insure that the mcServices is created and will test our connection before uploading. The code is well commented, so please read though it carefully, as this is all the explanation that is provided. I hope it is enough. Once you get this working OK, then you can move on to the next article to see how to add to, delete from and modify the list.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

public class MailChimpHandler implements IMailChimpHandler {
    private final Log log = LogFactory.getLog(getClass());
    // API Key - see http://admin.mailchimp.com/account/api or run login() once
    private String apiKey = "put your api key info here";
    // A List Id to run examples against. use lists() to view all
    // Also, login to MC account, go to List, then List Tools, and look for the
    // List ID entry
    private String listId = "put your list ID here";
    // Instance of the MailChimpServices
    private IMailChimpServices mcServices = null;
    // Flag indicating status of our connection to MailChimp
    private boolean connectionStatus;
    // Class to get the attributes associated with a company from database
    private ICompanyAttributesDao companyAttributesDao;
 
    public MailChimpHandler() {
        connectionStatus = false;
    }
 
    /**
    * prepare an instance of the MailChimpServices and determine
    * if we can connect using our apiKey.
    */
    private void initialize() {
        mcServices = MailChimpServiceFactory.getMailChimpServices();
        final String ping = mcServices.ping(apiKey);
        if (IMailChimpServices.PING_SUCCESS.equals(ping)) {
            log.info("MailChimp connection pinged successfully");
            connectionStatus = true;
        } else {
            log.error("Failed to ping MailChimp, response: " + ping);
        }
    }
 
    /**
    * test the connection to see if it is still good
    * @return result
    */
    private boolean testConnection(){
        if(mcServices != null)
            return IMailChimpServices.PING_SUCCESS.equals(mcServices.ping(apiKey));
        else
            return false;
    }
 
     /**
     * Performs the initialization of the mail chimp list by adding
     * all the appropriate customer contacts to the list
     * @param companyId (this is optional and only here because my application needs it. Yours almost certainly won&#39;t need it)
     * @return number of successful insertions
     */
     public int initializeMailChimpList(int companyId){
         int listSubscribe = 0;
         int listFailure = 0;
 
         // insure we can connect to the server, if not then re-initialize
         if (testConnection() == false){
             log.info("Attempting to re-connect to MailChimp");
             initialize();
         }
 
         // if we have confirmed we can connect OK, proceed
         if (connectedStatus) {
             // This is my way of getting all the contacts I want to add to the list
             // You will come up with your own way of getting your contacts
             List<CustomerContact> contacts = customerContactDao.getMailChimpCustomerContacts(companyId);
             // Instantiate an ArrayList to hold all the contact info to send
             // ArrayList seems to be the preferred data structure for sending and receiving array information
             List<Map<String, String>> chimps = new ArrayList<Map<String,String>>();
             // For each of our contacts, build a HashMap of MailChimp tags and add it to the list
             for(CustomerContact contact : contacts){
                 Map<String, String> chimp = new HashMap<String, String>();
                 chimp.put("FNAME", contact.getFirstName());
                 chimp.put("LNAME", contact.getLastName());
                 chimp.put("EMAIL", contact.getEmail());
                 chimp.put("EMAIL_TYPE", "html");             // define the mail type to be HTML
                 chimps.add(chimp);
             }
             // Now that we have the ArrayList populated, attempt to send it to MailChimp
             try {
                 // attempt a batch update of the list using mcServices listBatchSubscribe method
                 // the last 3 arguments have to do with double-optin, updating existing and replacing interests. All false for us.
                 HashMap<String, Object> results = mcServices.listBatchSubscribe(apiKey, listId, chimps, false, false, false);
                 // the results come back as a HashMap with three entries, success_count, error_count and errors
                 listSubscribe = (Integer)results.get("success_count");
                 listFailure = (Integer)results.get("error_count");
                 log.info("Mail Chimp results : " + listSubscribe + " inserted and " + listFailure + " errors.");
                 // interpret the results to see what went good and bad
                 // The errors comes back as an array of Objects
                 Object[] errors = (Object[])results.get("errors");
                 createLogFile(errors, companyId);
                 // and update the good contacts to indicate they have been subscribed
                 // We have opted to update our contact list to indicate that the contacts got subscribe OK
                 // This is certainly optional
                 customerContactDao.markContactsSubscribed(companyId);
                 // be sure and mark contacts that have errors as not subscribed
                 // Again, we have opted to mark our contacts that failed to get subscribed
                 // This is optional as well
                 for(Object item : errors){
                     HashMap<String,Object> result = (HashMap<String,Object>)item;
                     HashMap<String,Object> row = (HashMap<String,Object>)result.get("row");
                     String fName = (String)row.get("FNAME");
                     String lName = (String)row.get("LNAME");
                     String email = (String)row.get("EMAIL");
                     customerContactDao.markContactsNotSubscribed(fName, lName, email);
                 }
 
             } catch (MailChimpServiceException mcse) {
                 log.error("Error in adding user to list. " + mcse.getMessage());
                 mcse.printStackTrace();
             } catch(Exception e){
                 log.error("Error in adding user to list. " + e.getMessage());
                 e.printStackTrace();
              }
         }else
             log.info("Could not add user because could not connect to MailChimp");
 
         return listSubscribe;
     }
 
    /**
    * add a new contact to MailChimp
    * @param contactId
    * return result
    */
    public boolean addUser(int contactId){
        // TODO Complete
        return false;
    }
 
    /**
    * update an existing contact to MailChimp
    * @param contactId
    * @param oldEmail
    * return result
    */
    public boolean updateUser(int contactId, String oldEmail){
        // TODO Complete
        return false;
    }
 
    /**
    * delete a contact from MailChimp
    * @param oldEmail
    * return result
    */
    public boolean deleteUser(String oldEmail){
        // TODO Complete
        return false;
    }
 
}
]]> http://www.othenos.com/2010/01/15/mailchimp-and-java-integration-part-1/feed/ 1 Styling DataGrid rows with an Item Renderer http://www.othenos.com/2009/09/06/styling-datagrid-rows-with-item-renderer/ http://www.othenos.com/2009/09/06/styling-datagrid-rows-with-item-renderer/#comments Sun, 06 Sep 2009 23:55:28 +0000 admin http://www.othenos.com/?p=208 I had a need to bold the data in only one row of a Flex DataGrid. There were some solutions posted on-line (especially ninjacaptain) but honestly I could not get them to work the way I wanted. So, using their examples as a starting place, I created an extremely simple ItemRenderer which would bold the row desired.

The key to getting it to work is to have some property in your dataProvider which you can use to determine whether to bold or not. In the example, I actually added an additional property called ‘fontWeight’ and set the value to either ‘bold’ or ‘normal’ depending on the results I wanted.

You can potentially key off of any existing data element from your dataProvider, such as a property having a value greater or equal to some other value. Basically, whatever that is available to make the determination to bold or not.

Lastly, instead of fontWeight, you could set any of the additional style properties available for the DataGridItemRender class.

Here is the example with the source code.

Here is the code for the itemRenderer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

package com.othenos.renderer {
  import mx.controls.dataGridClasses.DataGridColumn;
  import mx.controls.dataGridClasses.DataGridItemRenderer;
 
  public class MyDataGridItemRenderer extends DataGridItemRenderer {
   public function MyDataGridItemRenderer() {
			super();
    }
 
    override public function set data(value:Object):void {
      super.data=value;
      /**
       * First insure the value is non-null and not a DataGridItem type but of the type that you are expecting
       * as the value. In this case, it is an Object.
       **/
       if (value && !(value is DataGridColumn) && value is Object)
         /**
          * In the example, there is a property on each value that is
          * named fontWeight and has the value of either 'normal' or 'bold'.
          *
          * Of course, you could do this in many different ways. For example,
          * you may want to bold the line only when a certain property equals
          * a certain value. Or when the property exceeds a certain value. In these
          * cases, you may or may not have multiple lines of the grid which are 'bold'.
          *
          * This example sets the fontWeight style. You could, of course, set one or many of the style
          * properties that are available to the DataGridItemRenderer. The result would apply to the
          * DataGrid row associated with this value.
          **/
          setStyle('fontWeight', value.fontWeight);
        }
      }
  }
}
]]> http://www.othenos.com/2009/09/06/styling-datagrid-rows-with-item-renderer/feed/ 1 DataGrid Footer http://www.othenos.com/2009/08/27/datagrid-footer/ http://www.othenos.com/2009/08/27/datagrid-footer/#comments Thu, 27 Aug 2009 16:28:58 +0000 admin http://www.othenos.com/?p=204 I was enjoying the enhancements made to the DataGrid control I found on Doug Marttila’s site, who in turn was working from an original update made by Alex Harui. However, I found that the footer did not work correctly when you make columns visible/invisible, especially horizontal scrolling. There was also a problem of vertical scrolling and the regular row data partially showing up in the footer area.

So the changes I made were to address those issues. Included are the ability to dynamically turn the footer on or off (make visible or invisible) and to change the background color of the footer on the fly.

If anyone comes up with a way to change the footer’s font color, I’d like to know how.

Here is a link to the demo. You can right-click and get the source.

]]> http://www.othenos.com/2009/08/27/datagrid-footer/feed/ 4