Service Objects’ Blog

Thoughts on Data Quality and Contact Validation

Email *

Share

Posts Tagged ‘Integration’

Salesforce Data Quality Tools Integration Series – Part 2 – Validation Plug-ins in Flows

Welcome back to our blog series where we demonstrate the various ways you can achieve high data quality in Salesforce through the use of Service Objects’ validation tools.

In the first part of this series, we showed how to create a trigger and an Apex future class to handle calls to our web service API. That blog described a common way, in code, to call our services in Salesforce. But, there are more simple ways to do this.

In this blog, we are going to step back and demonstrate an integration that requires little more than drag and drop to achieve your goals by implementing a plug-in on a flow. Because – why write code if you don’t have to? When we are done you will be able to create a flow and drop our plug-in anywhere in your process and wire it up.

We are going to start by looking at some basic setup. Then we will step through the code. What code? You are probably wondering, “Why do we need to look at the code, if we don’t need to write any”. Well, if you wanted to implement any additional business logic or tailor the plug-in, you will be equipped to do just that.

After we review the code, we will jump into creating a sample flow that allows a user to enter either a US address or Canadian address and process that data through our US and Canada validation APIs and then display those results back to the screen.

In this section, we will need to do some setup before we get started. We will need to register the Service Objects’ endpoint with Salesforce so that we can make the web service calls to the address validation API’s. We went over this in the previous blog but it is worth repeating here.

The page where we add the URL is called “Remote Site Settings” and can be found in Home->Settings->Security->Remote Site Settings. This is the line I added for this blog.

Be aware that this will only work for trial keys. With a live/production key you will want to add a URL for for ws.serviceobjects.com and wsbackup.serviceobjects.com. As a best practice, you’ll want to add both endpoints with your live key, to take advantage of our fail-over capabilities. We named this one ServiceObjectsAV3 because we are really just reusing it from the previous blog but you can name it whatever you want.

No need for custom fields to get this example to work but you will likely want to create the same ones or similar as those in the previous blog, seen here.

This section shows the structure of the plug-in class for the US address validation, that we are naming AddressValidationUSA3, and the signature of the invoke and describe methods. The invoke method will contain the business logic and the call to our web service API. The describe method sets up the input and output variables for the plug-in that end users will be able to connect to on a flow.

The describe method also allows you to supply definitions and descriptions of the variables on the plug-in itself that will appear in the flow interface. The definitions used here are important because it can save a lot of time for the end user that is developing a flow. I would resist skipping this to save time. The following is just a snippet of the code.

There really isn’t much else to the describe method, most of the business logic happens in the invoke method. In the invoke method, we will gather the inputs to the plug-in and do some initial formatting to make sure we have valid characters in the call to our API. In gathering the inputs, we make sure to use the names of the inputs that we used in the describe method.

Since we will be making a path parameters call to the API, we want to account for anything that could break the URL like missing parameters. A missing parameter using our API should break the call but on other APIs it could simply change the meaning of the call and end up returning unexpected results. To make sure there are no issues with missing parameters, we simply replace any ones that are missing with space character. Just as in the previous blog, there will be minimum field requirements before it even makes sense to call the operation. The operation we are using is GetBestMatches and these are the requirements.

  • Combination 1
    • Address
    • City
    • State
  • Combination 2
    • Address
    • Zip code

If you do not have some combination of these inputs then it is best to add code to avoid the call completely, since there is no way to validate an address otherwise. By “avoid the call,” we mean avoid even hitting the plug-in at all, since it would not be necessary. A decision component in a flow can help with the process.

In an effort to simplify the code, I pushed the logic for calling our API into a method called CallServiceObjectsAPI which should make things easier to read. Using this method, we pass in the input parameters that we cleaned up.

Below, I show how to setup the HttpRequest/HttpResponse and the request URL. After that, I add in some basic error checking to check for a couple results. First, I am checking to see if there was an error with the API call and/or the result from it. If other errors happen outside of that then we catch the general exception, which I would assume is a connectivity issue at that point. You can try to catch more specific exceptions on your own but what I have here will work in a general fashion. In the instance of an error or exception on the call to our API, we also demonstrate our standard best practice of failover by adding code to call another endpoint in these situations. In the case of this blog, we are walking you through a trial key scenario, so failover in this case will not be true failover since it is failing over to the same trial.serviceobjects.com endpoint. But in a live key scenario, you would be encouraged to use ws.serviceobjects.com for the first call and wsbackup.serviceobjects.com for the failover call.

Another thing you may have noticed in the code above is that the input parameters to the API call are URL encoded and “+” are switched to “%20”. The reason for this is that certain characters are not allowed in a URL or a path parameters call, so the built-in Apex function urlEncode cleans that kind of thing up. One side effect that the encoding has is it replaces spaces with “+” symbols. Though in a URL “+” symbols are becoming the norm, path parameter calls still have issues with them. So the proper way to make the call work is to replace the “+” symbol with a “%20” which will be deciphered correctly as a space in the end. The method returns a string response from the web service and based on the call made, it is more precisely returning a JSON string response which we save in the variable ServiceObjectsResult.

The first thing we do after we get the response from the method is deserialize it into a Map object so we can start processing the result. Here is the rest of the code.

This section of the code is checking to see the type of response that was returned. The response could have been either an address, error or network error response. Based on those variations, we populated the corresponding output values in Map variable called “result”. In the Map, we map the outputs from the service to the expected outputs described in the describe method. Those values are the output values of the plug-in and are directly interfaced with in the flow. Adding code anywhere in the method we just went through would be appropriate based on your own specialized business logic.

Now that we have gone over the code, we are ready to jump in and show an example of our plug-in in a flow. For this example, I also created a Canadian address validation plug-in to make it a little more interesting. However, I do not see any service we offer that would not make for an appropriate and powerful example.

As I mentioned on the outset of this blog, I will show you a demonstration of a flow where the end user will be presented with a data entry screen. They will have options for adding either a US address or a Canadian address. From there, we will wire it up to either the US address validation plug-in or the Canadian address validation plug-in and then finally display the results to the screen. This flow will be more of an example on how to wire up the plug-ins rather than creating an input and output screen. Though doing something with screens is not out of the question, it will be more realistic to have a flow that manipulates Contact, Account or Custom objects without an interface.

Start by creating a new flow in the Process Automation section. I am just going to open the one I already had saved. Dragging on the Screen object is the first step and be sure to set it to be the starting interface by setting the green down arrow on the object. A flow cannot be saved without one part of it being a starting point.

Inside this interface you will setup the input fields that you want to retrieve from the user. In this example, we forced the Address 1 field to be a required field and at the bottom we added a radio button selection for the desired country, defaulted to USA.

Once we have the inputs from the user, we need to find some way to route the variables to either a US address validation or a Canadian address validation. For that we can use Decision Logic Tool. We will configure it to look at the country field and make a decision on which way it should continue to process.

The actual logic simply decides to go down the US address validation path if USA is found otherwise it will assume it is a Canadian input address.

Now we are ready to drop our US and Canada address validation plug-ins on the screen. On the left, in the Tool area you can find the plug-ins under the respective names you gave them in the creation of the plug-in.

You can and will be forced to drag them onto the flow canvas one by one and set them up individually. Inside you will be mapping the inputs from the user data entry to the inputs for the plug-ins. Additionally, you will be mapping the outputs to variables you create or objects variables in the system. This can take some time depending on how many of the address validation outputs you want/need to use.

When you are done with that part, you will wire them up in the flow to the decision tool you added earlier as shown below.

In this last part, we will setup two output screens, one for the US address validation results and one for the Canadian address validation results. This time instead of adding text boxes to the interface, we just add a display object for each field we want to show.

After wiring the last screens, the completed flow will look like this.

From here you can choose to save the flow and then add layout options on other screens that will give you access to executing the flow, schedule the work flow to run at a specific time (not useful in our example though) or you can run it directly from this interface by clicking Run. We will demonstrate it by clicking Run. We’ll start with a US address and then view the results on the output screen. In this example, you can see there are several issues with this address. Street name is incomplete, it uses unit instead of suite, city name is misspelled and even the postal code is wrong.

Upon validation, we see that the system was able to correct the address and had a DPV score of 1 meaning the result is a perfect address. The DPV score is one of the most important fields to pay attention to in the output. It indicates the validity level of the address. You’ll see other information in the response that will give you an idea about what was changed or if there were any errors. You’ll also have access to the fragments of the address so you can process the response at a more granular level. More details about the fields can be found here.

In the last example, we will use a Canadian address. In this case the only thing wrong with the address is the postal code, so we’ll see how the system handles that.

Sure enough that address validated and the postal code was corrected. In the US address validation service, the DPV score and error result indicated the validity of an address. In the Canadian validation service, we really only need to look at the error fields. Empty or blank error fields will mean that the address is good and can receive mail.

In conclusion, we learned how to create a plug-in and then use it in a flow. Though you do not need to know how the plug-in was made to be able to use them, it is very helpful to know the details in the case that your business logic requires a more tailored solution. And you can see that in this demonstration adding additional code does not take much effort. These plug-ins allow you to get up and running very quickly without needing to know how to code. As I mentioned earlier, the flow created here is definitely a use case but more often than not I would imagine Salesforce administrators creating flows to work on their existing objects such as Contact, Account or some other custom object.

A quick note on the license key, you will want to add you own license key to the code. You can get one free here for US address validation and here for Canadian address validation (Each service will require a different license key).

The last thing I want to discuss about the license key is that it is good practice to not hard code the key into the code. I would suggest creating a custom object in Salesforce with a key field. Then restrict the permissions on the field so that it is not view-able by just anyone. This will help protect your key from unwanted usage or theft. At this point, we have the code for these two address validation plug-ins, but Service Objects will continue to flush out more for our other services and operations. With that said, if there is one you would like to request, please let us know by filling out the form here and describe the plug-in you are looking for.

Salesforce Trigger Integration – Video Tutorial

Here at Service Objects, we are dedicated to helping our clients integrate our data quality services as quickly as possible. One of the ways we help is educating our clients on the best ways to integrate our services with whatever application they may be using. One such application where our tools are simple to implement is Salesforce.

Salesforce is, among other things, a powerful, extensible and customizable CRM. One of the advantages of Salesforce’s extensibility is that users can set up triggers to make external API calls. This is great for Service Objects’ customers, as it allows APIs calls to any our DOTS web services and helps ensure their contact data in Salesforce is corrected and verified.

In the video below, we will demonstrate how to set up a trigger that will call our DOTS Address Validation 3 service whenever a contact is added to our list of contacts.

See full transcript below.

Hello, and welcome to Service Objects video tutorial series. For today’s tutorial we’ll be setting up a trigger and a class in Salesforce that will call out to our DOTS Address Validation 3 web service. If you don’t already know, Salesforce is an extremely powerful, extensible and customizable CRM. One of the great things that we like about Salesforce here at Service Objects is the ability to call out to APIs so that the data going into your CRM can be validated and verified before it gets entered. This means that you can call out to any of our APIs from Salesforce. You can use this video as an overview for how to integrate any of the service, but for this specific example we’ll be using DOTS Address Validation 3.

To participate in this tutorial, you need the following items. A Service Objects web service key, whether that is a trial key or a production key. You can sign up for a free trial key at www.serviceobjects.com. You will need a developer account in Salesforce. You will also need a working knowledge of Salesforce and Apex, which is the native programming language inside Salesforce. We will go ahead and get started.

To start off, one of the first things we’ll need to do is add the Service Objects endpoint into the list of allowed endpoints that Salesforce is allowed to contact within your developer platform. To do this, you can navigate here and type in remote site settings, or remote, and the remote site settings field will pop up. Here, you’ll see a list of all the websites that your Salesforce platform is allowed to contact. In my account here you can see I have ws.serviceobjects.com and wsbackup.serviceobjects.com. To add a new site, you’ll go and select new remote site. Give an appropriate name, and you will type in the URL here. You can see for this example I’m going to type in trial.serviceobjects.com which will only work if you have a trial license key. If you have a production key, you want to add ws.serviceobjects.com and wsbackup.serviceobjects.com as those will be the two primary URLs that you will be hitting with your production Service Objects account.

This trial.serviceobjects.com URL will only work with trial license keys. Click save and new or just save. You see here if we go back to our remote site settings, you can see that trial.serviceobjects.com was successfully added to our remote site settings. Now that we have successfully added the Service Objects endpoint, we’ll want to add some custom objects in our contact field that will hold some of the values that are returned by our DOTS Address Validation 3 web service. To do that, we’ll scroll down and go to customize. In our example we’re using the contacts field, but you can add custom fields to whatever field is most appropriate for your application, and we’ll select add custom field to contacts. Once we are here, we will scroll down and scroll to this contact custom fields and relationship. You can see here I have several custom fields here already defined. I have a DPV, mostly DPV information and error information, which our field set will parse out from our Address Validation 3 response.

We’ll add another field here for the sake of example. For this field we’re going to add the Is Residential Flag that comes back from the Address Validation 3 service. For this we’ll select text, select next, and here we’re going to go ahead and enter an appropriate field name, which I have in my clipboard. We’re going to call it DotsAddrVal_IsResidential. If you hover over this little “i,” it will say this is the label. This is the label to be used on displays, pages layouts, reports, and list views. This will be a more of a pretty type display. You’ll want to name it something more appropriate and something that will work better in your workflow, but for our example we’re just going to name it this.

For length, we’re going to do length of 15, and for the field name we’re just going to call it AddrValIsResidential. This is the internal field name here. When you’re calling an internal field name, you’ll have to add a double underscore and C in the Apex class. We’ll see an example of that in the next piece of code that we’re going to add. We’ll select next. You’ll select the appropriate field level security here. Next again, and go ahead and click save. To add the actual code that will call out to our Address Validation 3 web service, we’ll scroll down here, go to develop Apex classes. I have already added the class to my developer console, but just for the sake of example, I’ll go ahead and delete it and re-add it. I already have the code in a text editor, so I’m just going to copy and paste that, and just go over the code and explain some key points of it.

Now that I have my code copy and pasted in, I’ll walk through some key elements of it. In the sample code that we have, we have some extra commented out information here that gives you some resources like the product page, the developer guide. You can download this sample code along with this tutorial so you don’t have to pause the video and type it out and everything. The first thing we do is substantiate some of the HTTP request objects in this call WS by ID method. We’ll pull back the contact that’s just been added, and so we’ll pull back all these fields. Mailing street, mailing city, postal code, and state as well as the custom DPV and error information fields that we’ve entered into Salesforce. To call an internal field, an internal custom field that you’ve created in Salesforce, you’ll need to add this double underscore C at the end of it. We can see that we’ve done that here and other place where we reference these objects in the code.

Here, you can see we set the endpoint of the request to the trial URL endpoint, and this will point to the GetBestMatches JSON operation, so this will return a JSON formatted output. We’ve URL encoded all of the address information here. As you can see with this EncodingUtil.urlEncode. We’ll encode it to the UTF-8 standard. Another thing to note here is that you’ll have to put in your license key in this field here. Right now we just have it as a generic WS72 XXX, etc, but you’ll want to put in your specific license key. Here, we’ll send a request to the service, and if the response back is null, then that means there was something wrong with the primary endpoint, so we’ll come back here and check out our backup endpoint. For this example, it’s pointing to the same URL, the same trial endpoint. If you have a production key, you will want to point this primary URL to ws.serviceobjects.com, and this backup URL to ws.backup.serviceobjects.com. You’ll want to be sure to change both the license keys to whatever your license key is.

After that failover configuration, we’ll see here we checked the status code. If it’s equal to 200, we’ll go into processing the response from the service. Create some internal address fields here, and we’ll initialize the error response here to none, which would indicate that no error was returned from the service. What this does is it traverses through the JSON response of the service, and it finds the appropriate field. For this case we’ll see if it finds address1, it will set our initial address field to the address1 that was returned from the service. That will be the standardize and validated address information that is returned. We do that with all the fields that are pertinent to us. The DPV and DPV description, DPV notes description, as well as the IsResidential and error fields down here.

Here, you can see if we get a DPV score equal to 1. That indicates that the address is mailable, it is deliverable, and it is considered good by the USPS. This is the L-statement for the 200 code check here. If the 200 code wasn’t right, then we’ll say put the error description as this generic error message. At the end of this, we’ll update the list of contacts, so we’ll go ahead and click save. Now that we have our TestUtil class made here, we’ll go ahead and scroll down, select Apex triggers. To add a new trigger, we’ll select developer console, select file, new, trigger. For a name, we’ll simply call it Test Trigger.

We’ll go down here and select the contact object. We have the little bit of code right here. I have the actual code in a text editor that will call the service, so I’ll just copy that in. Now that I have this copied, you can see here that whenever a contact is added, or before it’s inserted rather, it will call the class that we made which was called WS by ID, and it will send the contact to it. To save this, just simply go to file and save. Hit refresh. We can see we now have a test trigger here. Now, to add a contact and to test out our new trigger, we’ll simply go up here, select contacts. In recent contacts, you can see here we don’t have any, so let’s go ahead and add one. We’ll add in a fake person by the name of Jane Doe. Go down here to the mailing street information, and we’ll enter in an address. For this example, we’re just going to use our Service Objects office address. We’ll put some typos in there so you can see the standardization and validation that the Service Objects web service does.

We’ll do 27 East Coat. That’s suite number 500. We’ll do Sant Barb for Santa Barbara and CA and 93101. We’ll go ahead and save the contact. You can see here that we still have the old values here, and that’s because the Salesforce doesn’t immediately call the outside APIs. It cues it up a little bit, but if we go and select Jane Doe again, we can see that now we have a standardize address here. In our DPV description, we have a message that indicates, “Yes, this record is a valid mailing address.” For this DPV score, we get a score of one. We can find the “Is Residential,” says false, meaning this is a business address. Again here, we see that the validated address, we see the USPS standardize version of the address which is 27 East Cota Street, Suite 500, as well as the validated city and zip-plus four information.

This concludes our tutorial for how to add a trigger and a class that will call out to our Service Objects web service. If you have any questions or any requests to other tutorials, please feel free to let us know at support@serviceobjects.com. We’ll be happy to accommodate.

 

The Struggles with Deprecated Services

The word “deprecated” is thrown around frequently in the software development world. It is used to indicate a product or service that is either not going to continue being maintained or it is going to be sunsetted. Often times, when companies roll out a new product or API they decide to give their users a heads up that the older operations are going to be deprecated. This prompts the users to update to the latest version to take advantage of the latest and greatest features that the company is offering.

Marking a service to be deprecated is a warning to the users of the product or service that it will no longer be supported and it is highly recommended to upgrade to a newer, supported service.  Here at Service Objects, we don’t particularly like the practice of deprecating services.  Although we don’t rule it out completely, our mission is to maintain support for our legacy services. This is because we understand that it takes time, resources, and money to integrate with APIs. The time it takes for developers to integrate, test, and deploy new code inevitably costs money. To help solve the issue of legacy services falling behind the advancements, we keep our core code separate from the individual service outputs. A fixed set of output fields enables us to provide our clients with peace of mind that the service they have invested their time and resources into won’t change beneath their feet.

A clear picture of this concept can be seen in our DOTS Address Validation services. We have DOTS Address Validation 1, 2 and 3. The 3rd iteration is currently our primary and most robust address validation service yet. It has the latest and greatest in terms of available output fields. Even though Address Validation 3  is our latest version of our address services, both DOTS Address Validation 1 and 2 are actively supported.

The reason we are able to maintain these is due to the fact that the share a core address validation code set, which is continuously refined to return the most accurate and up to date data available.

By choosing our services, you can rest assured that the service you integrate will not be left to be put out to pasture in the future  and will continue to push to provide you with the best data, regardless of which version of the service you are using.

We invite you to get started testing any of our 23 data quality services today.

Salesforce Data Quality Tools Integration Series – Part 1 – Apex Insert Trigger

With Salesforce being the dominant platform in the Customer Relationship Management (CRM) universe, we are excited to demonstrate how our tools can benefit the data quality of your contact data in this robust system.  Salesforce is highly customizable and one of the great things about it is that you don’t need to be a developer to create a rich user experience on the system.  Although, being a developer, will help with understanding some of the coding concepts involved with some of the components. With all the data in your organization don’t you want it to be clean, accurate, and as monetizable as possible? The Service Objects suite of validation API tools are here to help you achieve those goals. Our tools make your data better so you can gain deeper insights, make better decisions and achieve better results.

This blog will demonstrate various ways that a Salesforce administrator or developer can boost the quality of their data.  We will look into various flows, triggers, classes, Visualforce components, and Lightning components, and more as we demonstrate the ease of integration and the power of our tools in this series.

To get started, we will focus on demonstrating an Apex trigger with a future class.  I will show you the code, part by part, and discuss how it all fits together and why.  You will also learn how to create an Apex trigger, if you didn’t already know.

Apex triggers allow you to react to changes on a Salesforce object.  For our purposes, those objects will typically be objects that have some kind of contact information like a name, address, email or phone, IP, etc.  Additionally, the objects can contain various combinations of these as well.  In this example, we will use the Contact Salesforce object and specifically the mailing address fields, though the Account object would have made just as much sense to demo.  Service Objects has services for validating United States, Canadian and international addresses.  In this example, I am going to use our US address validation API.

We are going to design this trigger to work with both a single Contact insert and bulk Contact inserts.  This trigger will have two parts: the Apex trigger and an Apex future class.  We will use the trigger to gather all of the Contact Ids being inserted and the future class will process them with a web service call to our address validation API.

It is important to note a couple things about the future class method and why it is used.  First, using a future call tells the platform to wait and process the method at the next convenient time for the platform. Remember that Salesforce is a multi-tenanted platform, meaning organizations on the platform share, among others, processing resources.  With that in mind, the platform tries to govern processing so that everyone on the platform gets the same experience and not one organization can monopolize the system resources. Typically, the future calls get initiated very quickly but there are no guarantees on timing but you can be sure that the future method will process soon after calling it. Second, callouts to a web service cannot be executed within a trigger, so the future method acts more like a proxy for the functionality.  There are plenty more details and ways that a web service can be called and you can dive deep into the topic by going through the Salesforce documentation. If for no other reason, it forces you to separate the call to the web service from your trigger, in turn, exposing your future call to other code you may want to write.

Once we are finished the trigger and the future class, we will test out the functionality and then you will have some working code ready to deploy from your sandbox or development edition to your live org.  But wait, don’t forget to write those unit tests and get over 75% coverage…Shoot for 100%.  If you don’t know what I am talking about with unit tests I suggest you review that documentation on Salesforce.

The results of the future method will update mailing address fields and custom fields on the Contact object.  For this example, here are the fields you will need to create and their respective data types.  We will not need these until we get to the future method but it is a good idea to get them created and out of the way first.

  • Field name
    • Internal Salesforce name
    • Type
    • Service Objects field name
  • dotsAddrVal_DPVScore
    • AddrValDPVScore__c
    • Number(1, 0)
    • DPV
  • dotsAddrVal_DPVDescription
    • AddrValDPVDescription__c
    • Text(110)
    • DPVNotesDesc
  • dotsAddrVal_DPVNotes
    • AddrValDPVNotes__c
    • Long Text Area(3000)
    • DPVNotesDesc
  • dotsAddrVal_IsResidential
    • AddrValIsResidential__c
    • Checkbox
    • IsResidential
  • dotsAddrVal_ErrorDescription
    • AddrValErrorDescription__c
    • Long Text Area(3000)
    • Desc
  • dotsAddrVal_ErrorType
    • AddrValErrorType__c
    • Text(35)
    • Type

The last thing we will need to setup before we get started is registering the Service Objects’ endpoint with Salesforce so that we can make the web service calls to the address validation API.  The page to add the URL to is called “Remote Site Settings” and can be found in Home->Settings->Security->Remote Site Settings. This is the line I added for this blog.

 

Be aware that this will only work for trial keys.  With a live/production key you will want to add one for ws.serviceobjects.com and wsbackup.serviceobjects.com.  You’ll want both endpoints with a live key and we’ll explain more about that later.  We named this one ServiceObjectsAV3 but you can name it whatever you want.

Let’s get started with the trigger code.  The first thing needed is to setup the standard signature of the call.

The method will be acting on the Contact object and will execute after an insert.  Next, we will loop through the Contact records that were inserted pulling out all the associated Contact Ids.  Here you can add logic to filter out contacts or implement other business logic before adding the contact Id to the Id list of contacts to update.

Once we have gathered all the Ids, we will send them to the future method which is expecting list of Ids.

As you can see, this will work on one-off inserts or bulk inserts.  Since there is not much code to this trigger, I’ll show you the entire sample code for it here.

So that was painless, let’s move to the future class and we will see how easy it is to make the call to the web service as well.

Future methods need to be static and return void since they do not return and values.  They should also be decorated with the @future annotation and callout=true.

It will be more efficient to update the newly inserted records all at once instead of one at a time and with that in mind, we will store the results from our address validation web service in a new list of Contacts.

Based on the results from the service, we will either update the mailing address on the Contact record and/or the DPV note descriptions or errors, as well as, the Is Residential flag.  Some of these fields are standard on the Contacts object and some are custom ones that we created at the beginning of this project.  Here is a sample of initiating the loop in order to loop through the Contact Ids that we passed into this method from the trigger and then the SOQL call to retrieve the details.

In case you are wondering why we just didn’t create a list of Contacts and send those in from the trigger instead of building up the list of Contact Ids, the reason is there is a limitation to @future calls. You can only pass in primitive objects such as Ids, strings, integers and so on.  So we went with a list of Ids where in Salesforce Id is its own primitive type.

Demonstrated in the code, which is shown in the next screen shot, are our best practices for service failover to help ensure 100% uptime when making calls to the API.  Note, that with a live production key for our API, the URL for the first trial.serviceobjects.com would need to be ws.serviceobjects.com and the second one, the one inside the “if” statement, would need to be wsbackup.serviceobjects.com.

I left both of these as trial.serviceobjects.com because most people starting out will be testing their integration with a free trial key.  In the screen shot you will see that I have added the API license key to the call “ws-72-XXXX-XXXX”.  This is factitious. You will need to replace that with your proper key based on the live/production or trial endpoint your key is associated with.  A best practice suggestion for the key is to “hide” it in a custom variable or custom configuration instead of exposing here in this method.

Once we get a response back from the call to the API and everything is okay, we setup some variables and start parsing the response.  There are several ways to parse JSON and definitely better ways than the one described here but this is not an exercise in parsing JSON, it is an example in how to integrate.  In this example, we loop through the JSON looking for the field names that we are interested in.  We are looking for:

  • Address1
  • City
  • State
  • Zip
  • DPV
  • DPVDesc
  • DPVNotesDesc
  • IsResidential
  • Type
  • Desc

But the service returns many other valuable fields, which you can learn about from our comprehensive developer guide found here, which has other helpful information along with the fields mentioned.  Remember, if you do end up using more fields from the service and you want to display them or have them saved in your records, you will need to create corresponding custom fields for them.  The next screen shot is just a part of the code that pulls the data from the response.

In practice, you may want to make decisions on when to update the original address using more criteria, but in this example we are basing that decision on the DPV score result alone.  You can find out more about the different DPV codes back in the documentation.  When the DPV value is 1 then we are returning a valid mailing address.  Corrections to the address may have occurred so it would be best to update the address fields on the Contact record and that is what we are doing here just before adding the updated Contact to our new list of Contacts.

Once we have looped through the entire list of Ids that we sent into this method, we are ready to do the update in Salesforce.  Before this point, nothing yet would have been saved.

And there you have it, go ahead and add some new contacts with addresses and test it out.  Over at the Contacts tab I add a new contact and then refreshed the page to see the results.  I will purposely make an error in the address so we can see more of the validation results.

The address we added is for our office and there are several errors in the street name, city and zip code.  Let’s see if our system gets it right.

The address validation API fixed the address and returned that the fixed address is the correct address to use based on the inputs.  Next, we will demonstrate a bad, non-salvageable address. You will see more than a few things wrong here.

There were so many problems that the address was not salvageable at all.

Let’s try one more, but this time instead of a completely bad address, we will add a bad (not completely bad) address but missing key parts.

The input address is still not good enough to be good but this time we were able to get details back that can help with fixing the problems.

From the results, we can see that the address is there but perhaps a unit number or something key to the address is missing to get full delivery by the USPS.

In conclusion, there are a few things to take into consideration when integrating data quality tools into Salesforce. First, you need to do more error checking.  These were simple examples to show how to integration our service and the error checking was the bare minimum and not something I would expect to see in a production environment. So, please…please, more error checking. Second, don’t forget to write the unit tests and try to get 100% coverage.  Salesforce only requires 75% to be able to deploy your code, but we highly recommend striving for 100%, it is definitely attainable.  Salesforce has this requirement for several reasons. One being that when Salesforce makes updates to their platform, they can run all the units in all the organizations on the platform and ensure they are not going to break anyone’s system. It is just good practice to do so.  There is tons of documentation on Salesforce that will help you down the right path when it comes to testing. Lastly, we didn’t make any considerations in the code for the situation where a contact being inserted doesn’t have an address to validate or enough address components.  Clearly, you would want to add a check to the code to see if you have a valid combination of data that will allow for an address validation against our API.  You will want to see if any of these combinations exist. These represent the minimum or required fields.

  • Combination 1
    • Address
    • City
    • State
  • Combination 2
    • Address
    • Zip code

You can find the sample code for this blog on our web site with the file names TestTrigger.trigger and TestUtil.cls at this link.

Service Objects ColdFusion Integration Tutorial

As part of our commitment to making our data quality solutions easy to integrate, our Application Engineering team has developed a series of tutorials on how to integrate our services.  The series highlights various programming languages, with this tutorial exploring the “how-to’s” of applying our services using ColdFusion.

ColdFusion is a scripting language that has been around since 1995. It was created to make development of CGI scripts easier and faster.  ColdFusion has unique aspects, including use of its native ColdFusion Markup Language (CMFL for short) to allow HTML style tags for programming with systems. Like most things in the tech world, it can draw a lot of polarized opinions, where some are ardent supporters, and others, less than enthusiastic fans. If you fall in the supporter camp, and want to learn how to call a web service with ColdFusion, that is where our experts can step in and help.

To get started you will need a ColdFusion IDE (we’re using ColdFusion Builder 3) and a Service Objects’ License key. We’re using one for DOTS Lead Validation but you can follow along with your service of choice.

Project Setup

The first step is to launch your IDE and select an appropriate workspace for your project. Next, we will create a new project.

Select next for a blank template and then click next again.  On the following screen give your project an appropriate name and click finish.

Congratulations! You created a brand new ColdFusion project. Now it’s time to add some code. For starters, we’ll want to add a form and elements to initialize our form inputs so that we can create a sample page to input data to send to our web service. This likely won’t be what you will want to do in a live environment, but this is for demonstration purposes.

The DOTS Lead Validation service that we’re using has quite a few inputs so this may take a while. Once you are finished it should look like the following:

Making the Web Service Call

The next bit of code that we will add is to make the actual HTTP GET call to the Service Objects’ web service. Let’s use the CFML tags to make the actual web service call.

After the code makes the call to the trial.serviceobjects.com endpoint, we perform a failover check in the code. This failover check and the try catch blocks that it is nested in will help ensure that your integration of our web service will continue to work uninterrupted in the event that the primary web service is unavailable or not responding correctly.

The primary endpoint should be pointing to ws.serviceobjects.com and the backup endpoint should be pointed to wsbackup.serviceobjects.com.

Displaying the Results

Now that you have successfully called the web service, you will obviously want to do something with the results. For demonstration purposes we will simply display the results to the user.  You can use the code snippet below to display.

If you are having trouble figuring out how a particular output is mapped in the ColdFusion response, then you can use the <cfdump var=””> tag to dump the outputs onto the screen. This should allow for easy troubleshooting.

Now that our CFML is all set up, lets see an example input and output from the service. Below is sample lead information that you might encounter:

And here is some of the response that DOTS Lead Validation will return:

The DOTS Lead Validation service can return a multitude of information about your lead.  To download a trial key for any of our 23 contact validation solutions, please visit https://www.serviceobjects.com/products

P.S.  Here is the full ColdFusion script page in case you need it to get up and running.

 

Service Objects’ Application Engineers: Helping You Get Up and Running From Day 1

At Service Objects, one of our Core Values is Customer Service Above All. As part of this commitment, our Application Engineers are always available to answer any technical questions from prospects and customers. Whether users are beginning their initial investigation or need help with integration and deployment, our Engineers are standing by. While we continually make our services as easy to integrate as possible, we’d like to touch on a few common topics that are particularly helpful for users just getting started.

Network Issues

Are you are experiencing networking issues while making requests to our web services? It is a very common problem to face where outbound requests are being limited by your firewall and a simple rule update can solve the issue. When matters extend beyond simple rule changes, we are more than happy to schedule a meeting between our networking team and yours to get to the root cause and solve the issue.

Understanding the Service Outputs

Another common question revolves around the service outputs, such as how they should look and how they can be interpreted. From a high level, it is easy to understand what the service can provide but when it comes down to parsing the outputs, it can sometimes be a bit trickier. Luckily there are sets of documentation for every service and each of their operations. Our developer guides are the first place to check if you are having trouble understanding how individual fields can be interpreted and applied to your business logic. Every output has a description that provides insight into what that field means. Beyond the documentation, our Application Engineering team is available via multiple channels to answer your questions, including r email, live chat, and phone.

 Making the Move from Development to Production

Eventually everyone who moves from a being a trial user to a production user undergoes the same steps. Luckily for our customers, moving code from development to production is as easy as changing two items.

  • The first step is swapping out a trial license key to a production key.
  • The second step is to point your web service calls from our trial environment to our production environment. Our trial environment mirrors the exact outputs that you will find in production so no other code changes are necessary.

We understand that, even though we say it is easy, making the move to production can be daunting. That is why we are committed to providing your business with 24/7/365 technical support. We want the process to go as smoothly as possible and members of our team are standing by to help at a moment’s notice.

We have highlighted only a few broad cases that we have handled throughout our 16 years of providing genuine, accurate, and up-to-date data validation. Many technical questions are unique and our goal is to tackle them head on. If a question arises during your initial investigation, integration, move to production, or beyond, please don’t hesitate to contact us.

API Integration: Where We Stand

Applications programming interfaces or APIs continues to be one of the hottest trends in applications development, growing in usage by nearly 800% between 2010 and 2016 according to a recent 2017 survey from API integration vendor, Cloud Elements. Understandably, this growth is fueling an increased demand for API integration, in areas ranging from standardized protocols to authentication and security.

API integration is a subject near and dear to our hearts at Service Objects, given how many of our clients integrate our data quality capabilities into their application environments. Using these survey results as a base, let’s look at where we stand on key API integration issues.

Web service communications protocols

This year’s survey results bring to mind the old song, “A Little Bit of Soap” – because even though the web services arena has become dominated by representational state transfer (REST) interfaces, used by 83% of respondents, a substantial 15% still use the legacy Simple Object Access Protocol (SOAP) – a figure corroborated by the experiences of our own integrators.

This is why Service Objects supports both REST and SOAP among most if not all services. We want our APIs to be flexible enough for all needs, we want them to work for a broad spectrum of clients, and we want the client to be able to choose what they want, whether it is SOAP or REST, XML or JSON.  And there are valid arguments for both in our environment.

SOAP is widely viewed as being more cumbersome to implement versus REST, however tools like C# in Visual Studio can do most of the hard work of SOAP for you. Conversely, REST – being URL http/get focused – does carry a higher risk of creating broken requests if care is not taken.  Addresses, being a key component in many of our services, often contain URL-breaking special characters.  SOAP inherently protects these values, while REST on a GET call does not properly encode the values and could create broken URLs. For many clients, it is less about preference and more about tools available.

Webhooks: The new kid on the block

Webhooks is the new approach that everyone wants, but few have implemented yet. Based on posting messages to a URL in response to an event, it represents a straightforward and modular approach versus polling for data. Citing figures from Wufoo, the survey notes that over 80% of developers would prefer this approach to polling. We agree that webhooks are an important trend for the future, and we have already created custom ones for several leading marketing automation platforms, with more in the works.

Ease of integration

In a world where both applications and interfaces continue to proliferate, there is growing pressure toward easier integration between tools: using figures cited from SmartBear’s State of the APIs Report 2016, Cloud Elements notes that this is a key issue for a substantial 39% of respondents.

This is a primary motivation for us as well, because Service Objects’ entire business model revolves around having easy-to-integrate APIs that a client can get up and running rapidly. We address this issue on two fronts. The first is through tools and education: we create sample code for all major languages, how-to documents, videos and blogs, design reference guides and webhooks for various CRM and marketing automation platforms. The second is a focus on rapid onboarding, using multiple methods for clients to connect with us (including API, batch, DataTumbler, and lookups) to allow easy access while APIs are being integrated.

Security and Authentication

We mentioned above that ease of integration was a key issue among survey respondents – however, this was their second-biggest concern. Their first? Security and authentication. Although there is a move toward multi-factor and delegated authentication strategies, we use API keys as our primary security.

Why? The nature of Service Objects’ applications lend themselves well to using API keys for security because no client data is stored. Rather, each transaction is “one and done” in our system, once our APIs perform validation on the provided data, it is immediately purged from our system and of course, Service Objects supports and promotes SSL over HTTPS for even greater protection.  In the worst-case scenario, a fraudster that gains someone’s key could do transactions on someone else’s behalf, but they would never have access to the client’s data and certainly would not be able to connect the dots between the client and their data.

Overall, there are two clear trends in the API world – explosive growth, and increasing moves toward unified interfaces and ease of implementation. And for the business community, this latter trend can’t come soon enough. In the meantime, you can count on Service Objects to stay on top of the rapidly evolving API environment.

Testing Through Batches or Integration: At Service Objects, It’s Your Choice

More times than not, you have to buy something to really try it.  At Service Objects, we think it makes more sense to try before you buy.  We are confident that our service will exceed expectations and are happy to have prospects try our services before they spend any money on them.  We have been doing this from the day we opened our doors.  With Service Objects, you can sign up for a free trial key for any of our services and do all your testing before spending a single cent.  You can learn about the multiple ways to test drive our services from our blog, “Taking Service Objects for a Test Drive.” Today, however, I am focusing on batch testing and trial integration.

Having someone go through their best explanations to convey purpose or functionality can be worthwhile but, as the saying goes, a picture is worth a thousand words.  If you want to know how our services work, the best way to see them is simply try them out for yourself.  With minimal effort, we can run a test batch for you and have it turned around within a couple hours…even less time in most cases.  Another way we encourage prospects to test is by directly integrating our API services into their systems.  That way you see exactly how the services behave and get a better feel for our sub-second response times.  The difference between a test batch and testing through direct integration is the test batch will show the results and the test through integration will demonstrate how the system behaved to deliver results.

TESTING THROUGH BATCHES

Test batches are great.  They give you an opportunity to see the results from the service first hand, including all the different fields we return.  Our Account Executives are happy to review the results in detail and you always have the support of the Applications Engineering team to help you along.  With test batches, you can quickly see that a lot of information is returned regardless of the service you are interested in.  Most find it is far more information than expected and often clients find that the additional information helps them solve other problems beyond their initial purpose.  Another aspect that becomes clearer is the meaning of the fields. You get to see the fields in their natural environment and obtain a better understanding than the strict academic definitions.  Lastly, it is important to see how your own data fairs through the service and far more powerful to show how your data can be improved rather than just discussing it conceptually.  That is where our clients get really excited about our services.

TESTING THROUGH INTEGRATION

Testing through integration is a solid way to gain an understanding of how the service behaves and its results.  It is a great way to get a feel for the responses that come back and how long it takes.  More importantly, you can identify and fix issues in your process long before you start paying for the service.  Plus, our support team is here to assist you through any part of the integration process.  Our services are built to be straightforward and simple to integrate, with most developers completing them in a short period of time.  Regardless, we are always here to help.  Although we highly recommend prospects run their own records through the service, we also provide sample data to help you get started.  The important part is you have a chance to try the service in its environment before making a commitment.

Going forward with either of these approaches will quickly demonstrate how valuable our services are. Even more powerful is when you combine the two testing procedures with your own data for the best understanding of how they will behave together.

With all that said, if you’re still unsure how to best begin, just give us a call at 805-963-1700 or sign up for a free trial key and we’ll help you get started.

Introducing Service Objects New Open API

Service Objects is committed to constantly improving the experience our clients and prospective clients have with our data quality solutions. This desire to ensure a great experience has led us to revamp and redesign our lookup pages. These pages are easy to use and give all the information necessary for integrating and using our API in your application. This blog presents some of the key features.

Sample Inputs

One request we often receive is a quick sample lookup that will show our customers and prospects what to expect when calling our API. We are implementing just that in our new lookup pages.

In the example below, we are using our Lead Validation International lookup page. If the “Good Lead” or “Bad lead” link is selected, sample inputs will be filled into the appropriate fields. For this example we’ve selected, “Good Lead.”

We implemented this option so that users can get a quick idea of what types of inputs our services accept and what type of outputs the service will return. The form simply needs a license or trial key and it will return the validated data.

All Operations and Methods

Another benefit of these new pages is that they concisely and easily display all the methods available for an API along with all the potential HTTP methods that can be used to interact with the service.

If you want a JSON or XML response, select the appropriate GET operation and you will have everything you need to make a successful request to the service. If you want to make a POST request to the service, simply select the post operation and it will detail all that you need to have your data validated in your method of choice.

Detailed Requests and Responses

Arguably the most important pieces for a developer looking to integrate with an API would be to know how to make a request to the service, and what type of response to expect. These new lookup pages provide that information in a very easy way as shown below.

 

After making a sample request, you will see the URL used to fetch the validated data, the actual response from the web service, and the response headers that the service provides. These are all vital pieces of information that will have you up and running in no time. The new pages also list what type of response object will be returned from the service. This can be seen below the response body and headers.

Additional Resources

The page also offers up extra pieces of information that will assist with integration. The link to our developer guides, WSDL (for SOAP integrations) and host paths can be found on the page as well. These resources will help you have your application up and running as quickly as possible.

Feel free to sign up for a Service Objects trial key to test with our new look up pages!

Service Objects is the industry leader in real-time contact validation services.

Service Objects has verified over 3 billion contact records for clients from various industries including retail, technology, government, communications, leisure, utilities, and finance. Since 2001, thousands of businesses and developers have used our APIs to validate transactions to reduce fraud, increase conversions, and enhance incoming leads, Web orders, and customer lists. READ MORE