As a start to 2016, we decided to clean up our contact list. Over the period of last 4+ years, users submitted their contact details to us in various places like trial download, event registration, blog subscription, video subscription etc. In some places, we restricted users from using same email address twice (example: trial download), which forced them to use alternate email addresses. We wanted to improve the user experience across the board and we din’t want users to give their contact details again and again to access the resources we produce. Once we know we have the details of a particular user, it’s a bit pointless to ask them again for the same information.
As part of this process, we wanted to build a robust contact management system – a central master store where all the contact details are kept with rich metadata. The following picture shows the workflow from the beginning to end and what we do behind the scenes.
As you can see, even though the user input screen is very minimal (simple contact form with 5 fields), behind the scene there is quite a substantial integration going on. As soon as we receive the form data, the first thing we do is store it in the safe place. Then it calls 2 different external services to enrich the quality of the data. The email validation service is an external third party service that validates the provided email for things like whether it’s a group email, accept-all email, invalid email, temporary email and so on. If it tells us something is wrong, we reject the request with an exception. Next, we validate the user input against location service to store some metadata like user location, especially country. Then, we store that information on our CRM system and finally push that data into our marketing system – the one we use to send email newsletters. Throughout the journey, the master contact detail is updated with more metadata.
At the end of the process, if everything is good, the user gets a nice “Thank You” notification. If there is an exception in the process, the user receives “Sorry there was a problem..” notification. If there is a problem, we record the exception against the original form data and send a notification to the admin saying there is a problem.
After making numerous testing with about 50 people internally, we were happy to have built a robust system for contact management with a bunch of SaaS integrations.
At this point, when we were convinced that everything is good, and we finally launched it live and sent an email to everyone in our mailing list to update their contact information, the system was good for the first 30 minutes or so. Then we started to see failures happening in the final “marketing system” integration. The underlying system is a SaaS based system connected via their API’s, and it started giving some strange socket errors, timeout errors, and so on.
Things You Should Keep in Mind When Building an Integration Solution
Take care of the data: At any cost, you do not want to lose that important message (contact data) submitted by your user. You only have one chance and you really do not want to mess it up. We thought about this up front, hence we store the submitted form data at the very first step into the database.
Be pessimistic about 3rd party systems: Never assume the 3rd party systems you are integrating is going to work smoothly and have 100% reliability. Especially in this modern world of lightweight SaaS application integration over unreliable protocols like HTTP, the rate of failure is extremely high. You have to design the system, keeping this in mind.
Design for duplicate message processing: Make sure your system is capable of processing duplicate messages at every stage of the journey. In our case, email address is the de-duplicate key. All other information can be added or updated in the system. In our case, you can process the input user form data multiple times. The system will upgrade relevant systems accordingly without any complaint. In some cases, this may not be possible, especially if you are designing for only-once delivery system, in which case guaranteed delivery principles need to be applied.
Don’t confuse the users: In our case we made a trivial mistake. When the exception was raised, we were sending that message back to the user saying “Sorry there was a problem..”. This confused a lot of people. We could have simply said, “Thank You…”, even though there was a problem, and simply run a batch process in the background to re-run the failed ones slowly.
Make sure you have a good notification system on failures: In our case, we received few emails from the users saying they are experiencing some problems. By that time, we were also aware that one of our system integration was failing. We were able to know the problems even before the user notified us, thanks to the notification system we built as part of the design on failures. It just proves the importance of a built in notification system or some external monitoring systems to watch the health.
As you can see from this experience, the strength of your integration solution is determined by one of the weak systems in your end-to-end flow. So keep the above points in mind as a base while doing your integration.