As you may have figured out by now, Drupal is a great platform for 3rd party integrations. Whether it’s eSignatures with Hellosign, more sophisticated search with Solr, or a host of other options, Drupal works best when it’s not trying to reinvent every wheel and is instead used to leverage existing business tools by tying them all together into a robust and useful package. Today, we’re going to take a look at a new set of integration modules that Ashday has just contributed back to the Drupal community: Omeda, Omeda Subscriptions and Omeda Customers.
The Omeda Solution
If you haven’t heard of Omeda by now, let’s take care of that. They are a family-founded company who have been around for over 30 years and offer a host of Audience Relationship Management tools meant to properly leverage modern technology to properly segment and target your customer base. They are on top of their game and really know their stuff (they even collaborated on the brainstorming of these new modules). And best of all, they offer a very complete and well-documented API, which is key to any good integration.
While their API is extensive, much of it can be very tailored to a particular customer’s needs so we set out to build a contributable integration that covers some great typical use cases as well as allow for custom development where necessary. So far, this has taken the shape of three modules that potentially can be extended later on.
Omeda Base Module
The Omeda base module is meant to be a simple core module to get you wired up to Omeda so you can start doing things. It has settings to configure your connection to the API as well as a setting to work in testing mode. At its heart is a Drupal service that is meant to be injected into other contrib modules that can tackle specific Drupal solutions. This service provides the Comprehensive Brand Lookup, which the module uses to cache your Omeda brand config daily, as well as a generic utility for making API calls, which has the benefit of consolidating some basic error handling and formulation of HTTP requests. Here’s a little example of how simple it is to call the API using this service:
$brand_lookup = \Drupal::service('omeda')->brandComprehensiveLookup();
So that’s pretty easy, right? If anything is wrong with the API config or the service is down or something along those lines, the service throws an exception with a helpful message. Otherwise, it returns the Omeda API response to the caller. Again, it’s simple but provides the base functionality you need everytime you wish to connect with Omeda.
Omeda Subscriptions Module
The first module to leverage the Omeda base module is the Omeda Subscriptions module. This module adds a My Subscriptions tab to the user profile, for the roles you select, where users can manage their deployment subscriptions. You can also configure which Omeda deployments you wish to allow your users to manage. The available deployments come from the stored Comprehensive Brand Lookup data cached by the base Omeda module. This module includes a new Omeda Subscriptions service that adds functions to fetch a logged in user’s opt ins and opt outs as well as allow the user to opt in or opt out of a deployment. It’s a simple, specialized module (which is the best kind) to provide an out-of-the-box solution for the most common Omeda user subscription management needs.
Omeda Customers Module
The Omeda Customers module is another extension to the base Omeda module that allows you to map user fields to your Omeda customer entities and sync them on user updates. You can choose which roles will sync and which user fields will sync. Since field mapping can get quite hairy, we provide a solution for simple use cases where you need to simply tell Omeda that “this field = that field”. If it’s a standard base Omeda field like “First Name”, those are called base fields and are meant to be a simple hand off of the Drupal field value to Omeda. If it’s an email, phone number, or address field, you can choose that type and we will then ask you to determine which contact type it represents so that it gets into Omeda properly. It should be noted that for addresses, we only support Address fields from the Address module since mapping a bunch of individual Drupal fields to a single Address entity in Omeda is more complicated and likely needs a custom solution.
This mapping config also provides a simple solution for Omeda Demographic fields, which are more complex and dynamic fields that store IDs instead of literal values. It allows you to choose which demographic field a Drupal user field maps to and then create a mapping of possible Drupal field values with available Omeda field values. So if you have a field on the Drupal user called “Primary business role”, but you want to map it to the Omeda “Job Title” demographic field, you can do that. You would then hand enter a mapping that indicates that a Drupal field value of “President” maps to the Omeda value of “President / CEO” so that we can send Omeda it’s desired ID value of 5******* instead of the literal text of “President / CEO”, which would be invalid. Again, this is for more simple use cases; if your Omeda fields don’t map 1-to-1 to Drupal fields, the necessary business logic is wide-ranging and you will likely need custom programming. The great thing though is that we’ve included support for a custom hook (hook_omeda_customer_data_alter) to inject your own adjustments into the data mapping process and provide your own custom alterations.
Hopefully these modules prove useful to you - especially if you’re already an Omeda client with a Drupal site - and the goal again is to provide some basic functionality that doesn’t require developer resources to integrate with some basic Omeda functionality. We ourselves have custom needs beyond what the modules can offer and find that it’s quite easy to extend them to do what we need for particular customer solutions, largely thanks to Drupal 8’s architecture. As always, if you need assistance please feel free to contact us and if you’d like to offer any module patches or report a bug, feel free to use the issue queues for each project and we’ll check it out!