You know what it is like when that new phone doesn’t get a dial tone, or your router isn’t getting an internet signal. In much the same way, connectivity issues are an annoying but common part of implementing web services in your applications software. Whether it is navigating your system’s firewalls, moving from development to production environments, or simply dealing with calling out to an API, few things are as frustrating as troubleshooting a piece of code that should be working but isn’t.

We are here to help. The Applications Engineering team here at Service Objects understands the full range of connection issues, and after 15-plus years in business we’ve seen it all. Between the sample code we’ve written and the support we provide our customers, chances are that we can help you get your application up and running as quickly as possible with the Service Objects’ API of your choice. But first let’s look at some of the most common issues we’ve seen, and how you can troubleshoot them.

Monitoring Tools

Tools like Wireshark and Fiddler can be invaluable when debugging a connection to a web service.  These tools allow you to see all the different network connections that your system is making, and can also allow you to view the information that is being sent to the service.  This can be helpful for cases where you want to see what exactly is being sent to our services. Often these tools can highlight malformed requests, blocks by your firewall or any other odd behavior that is getting in the way of receiving valuable data from one of our APIs.

Firewalls, IP Addresses and Connection Issues

Another issue we see quite frequently is a connection issue when moving a website or application from development to production.  If this happens, and you experience issues connecting to our services, a couple of quick checks can get you pointed in the right direction to debug your application.

First, check if your firewall needs to have IP addresses whitelisted. If it does, reach out to us at support@serviceobjects.com and we will be happy to provide the most up-to-date set of IP addresses that our services utilize. Still having a tough time connecting to our services? Check through a command prompt on the server in question to ensure you can ping our primary (ws.serviceobjects.com) and backup (wsbackup.serviceobjects.com) endpoints. After that, you can perform a trace route to our endpoints to determine if there is any packet loss between your system and ours.

Failover and Service Downtime

A frequent question that we receive about connectivity to our services is what to do if the Service Objects’ API is unreachable.

First, understand that this should normally be an extremely rare event. Our SLA guarantees “five 9” availability, meaning that our services will be available 99.999% of the time. The equates to less than 5 minutes service downtime per year or around 26 seconds of downtime per month. We have several data centers around the country to help provide redundancy to ensure that your data keeps on getting validated in the event that our primary servers are down.

In addition to this, we recommend that you implement a failover call to our web services. What this means is that if our primary endpoint at ws.serviceobjects.com is down or working unexpectedly, your application should call our backup endpoint at wsbackup.serviceobjects.com.  Below is an example of what failover configuration would look like while calling our AV3 service and using C# syntax.

Contacting Service Objects Tech Support

Finally, whether you are just beginning to troubleshoot or are at the end of your rope, don’t hesitate to reach out to us! We can assist you in tracking down issues you are encountering.  It always helps if you can provide any relevant information about the problem you are encountering, such as the error message received, inputs that are causing the error, or time that the issue started. This information will help us isolate whether your problem is an issue with our services or an issue on your end.

Whatever your connectivity issues are, Service Objects support is here to help you. We are always happy to speak with you by phone, do a live screen sharing session with you, share tips or troubleshooting steps by email, or help in any way we can. Don’t hesitate to reach out to us anytime, and best of success with your connections!

Searching for the proper tool to fit your business needs can be a daunting task. At Service Objects, ease of integration is engineered in as part of each of our products, ranging from seamless API interfaces to list processing services that work directly on your data files. This article discusses each of our integration strategies in detail, to simplify your research process and to help pinpoint the type of integration that will best suit your needs.

Service Objects products are created as web services. This means that any programming language that can make a web service request, can make use of our services. From programming languages like  PHP, Java, C#, Ruby, Python, Cold Fusion and many more, to CRM systems such as Salesforce, Marketo, Hubspot and beyond. Nearly all major languages and platforms can make use of Service Objects’ web services.

Below we discuss the most common types of integrations we see from our clients . And if you have a platform that isn’t listed below and would like more information on how it could tie in with our services, please reach out to us – we are happy to provide tips, sample code, plug-ins and recommend best practices and procedures.

API integration

This is our most popular option for real time validations, and allows our capabilities to be integrated directly into your software. Our services can be called via web requests either by HTTP GET or SOAP/POST, and the service response can be delivered in XML or JSON format. These protocols and output formats generally allows enough flexibility to meet  your needs. We also offer a web service description language (WSDL) file that can be consumed to auto generate the necessary methods and classes to call our various web services. If you have a specific language in mind, please check out our Sample Code page – chances are we have sample code already written for your needs.

List Processing

List processing involves sending us a list of your data to be validated. We take this list and process it through the appropriate web service and then return the results, appended to each record in your file. From there you can take the data, apply your business logic, and save it to your database.

This type of process is often the best approach for cleaning up existing data in bulk. A large export is generally easier than integrating via the API and processing it manually. However, depending on the resources you have available, both API or list processing are completely viable options and we have a number of clients that use both in concert.

We offer two convenient solutions for list processing: single batch runs for one-time processing, or automated batches. Let’s look at the differences between them:

Single batch runs. A single batch run is one of the simplest ways to have your data processed. You send us a comma separated value (CSV) file and we’ll run it against our services, append the data, and return it to you. It is perfect for cleaning up existing data. Many clients run a single one-time batch process to clean up their existing data and then implement a real time solution into their product, giving them the best of both worlds: clean existing data together with a process to ensure that incoming data is the highest quality possible.

Automated List Processing. Your data can be processed securely and automatically by uploading the data file to our secure FTPS server. Once uploaded, our system will recognize the new list to process and get to work. The input file will be parsed, run through a web service, and the results will be appended to original file. It is nearly identical to the one-time processing service that we offer, with the added benefit that you can upload files at your convenience to be processed automatically.

CRM integration

If you currently use one of the major customer relationship management (CRM) or marketing automation software platforms like Salesforce, Marketo, Hubspot, or others, chances are that our services integrate with it and we likely have sample code or plug-ins for themEach platform has its own level of customizability but they almost universally offer some variation on a plugin, api, or exposed interface to integrate with. Contact us to learn more about integrating our capabilities with your specific platform.

Whether you develop an API interface for your current software, use batch list processing, or integrate our capabilities with your CRM or marketing automation platform, Service Objects is with you every step of the way with support, sample code, tutorials, and the experience that comes with serving nearly 2500 customers. Get in touch with us today and see how easy it can be to integrate best-in-class data quality with your own applications environment.

Welcome to our third installment in our Salesforce Data Quality Tools Integration Series. In the first two parts, we covered creating a plug-in that could be dropped on a flow and a trigger. Today, we are going to jump into creating a VisualForce app that you’ll be able to extend for your purposes. At the end, you will have all the code you’ll need to get started, so don’t worry about implementing this step by step as I have it laid out in this blog.

The goal of this app is to display to a table of contacts that can be selected to have their emails validated. We will add a filter to the table to better target certain emails for validation. We will also display a few charts that will provide a good overview of the state of the emails in their system. These charts will refresh according to the filter selected for the table of contacts.

As always, we are going to start with some basic setup, then switching to look at what the final VisualForce page is going to look like, after that we’ll run through the code. During this walk-through, it should be clear where there are opportunities for customizing this solution.

The very first thing you need to start with is setting up the Service Objects endpoint. I am not going to go over it this time because I go over it in the first and second parts of this series. So, if you need help setting up your endpoint or a description of what this is, please check out the previous blogs. If you have been following along from the first two blogs, then you have already completed this part. Once you have set up your endpoint, you will need to add the following custom fields to the Contact object. If you are customizing this for your own purposes, you will want to add these fields to the object you are working with. If you want to map more of the fields that our service returns, you’ll have to create the appropriate fields on the object, if there isn’t an existing field already at your disposal.

• Field name
  • Internal Salesforce name
  • Type
  • Service Objects field name

• Email Catch All
  • EmailCatchAll__c
  • Text(20)
  • IsCatchAllDomain

• Email Score
  • Email_Score__c
  • Number(2,0)
  • Score

• Email Score Name
  • EmailScoreName__c
  • Text(20)
  • DPVNotesDesc

• Email Top Level Domain
  • EmailTopLevelDomain__c
  • Text(50)
  • TopLevelDomainDescription

Here is a view of the table with the filter and the Validate button.

Next is a screen shot of a couple of the charts.

As you can see, it is a pretty simple example that can be tailored to whatever custom solution you are looking for.

For this walk-through, we will be creating three files: one for the markup, one for the controller and one for the web service call.

MARKUP

Starting with the markup page, the actual VisualForce page, we will create a file called EmailValidation.vfp. For the first element, the Apex:page element, we define which controller we want to have associated to the page. We will make a custom controller for this app, “ContactEmailValidationController”, which is the name of the class that we will build later in the controller section. After we establish the controller that we are going to use, we override some styles so that we get the headers in the charts to stand out properly.

Next, we create the page block that will house the components to the page inside a form. The four main components are the filter, the table of contacts, the validate button(s) and the charts. You will more than likely want to implement a paging system for the table, so you can page through your contact records but I do not go into that here.

The filter section is basic:

Throughout the code you will see instances of values that come in the form of {! [Some variable name]}. That is simply a reference to a value in our custom controller. In the case of the filter, we have two of those instances, one for the filterId and one for Items. In this case, the filterId is telling the select dropdown list which item is selected. When the page first loads, nothing is selected, so the filterId is empty or null, which will render the default table view. You can certainly set this to have some other default value. The Items variable simply holds all the possible select options for the dropdown list. Items is populated in the controller, which we will take a look at later. Since we want the charts and the table to refresh when the filter is changed, we set the reRender attribute on the actionSupport element to target contacts_list. This is the id of the overarching page block section. Any markup outside of the contacts_list page block section will not be refreshed. The underlying code does an ajax call to refresh just a part of the page, which can be handy when you don’t want the whole page to reload.

In the next section of the markup, we setup the table of contacts and the columns that we will display back to the user. I have collapsed much of the code here so we can first focus on the apex:pageBlockTable element.

There are two things to notice in the page block table element. First, the contacts variable holds all the contacts coming back from the controller. Later, you will see a method on the controller that is called getContacts which is specifically named that way to sync up with this contacts variable. For example, if the variable was called people then the controller would need a method to retrieve those records called getPeople. The second thing to notice is the value cont for var. This value will be the container for each of the contacts in the contacts variable. The format and setup of the page block table element can be described such that it acts like your traditional for each loop. On a side note, there are many ways we could have created this table. For instance, we could have used a repeater or a couple of other elements to display the contacts to the user.

Next, we are going to look at the way we setup the columns and we’ll start with the checkbox column, since it is unique to the rest of them.

This column consists of an apex:facet and a checkbox input. The facet will implement its own checkbox input as well. We use the facet to customize the header of the column with a checkbox. Salesforce defines the facet as this “A placeholder for content that’s rendered in a specific part of the parent component, such as the header or footer of an <apex:dataTable>”. The checkbox in the header will act as the select all/select none functionality of the column. The checkboxes in the rows will be populated with a contact id so we can track which contacts were selected. The onclick functions in both input elements reference JavaScript functions that we will discuss in more detail shortly. Simply put, those functions will manage the storage of selected rows.

The columns I have highlighted with the red boxes are going to be your standard output columns and those outside of the red boxes will need the header label, for the respective columns, updated to be more readable.

Earlier we created the custom fields to house some of the values that will be coming back from the call to the email validation service. Creating custom fields can, at times, lead to having to create a more “technical” label for the field instead of “displayable”. One obvious reason is so new custom fields do not conflict with existing fields or any future fields. Keeping that in mind, we do not want to use the labels of a couple of our custom fields in the header, so we will update them using the facet like we did earlier for the checkbox header but this time without a checkbox.

In this simple example, we are updating the header text, but the values in the column will still be pulled from the cont.EmailTopLevelDomain__c variable. And that is really it for the columns, pretty straightforward. And easy to extend, with little effort you can alter this example to display any of the columns you want in the table, as long as you have access to them from the controller.

In the next section, we will focus on the pie charts. The sample code will have a chart for Email Scores, Catch All Domains and Top Level Domains. The code becomes redundant, so I will only demonstrate one of them here. With that said, you can add any chart you want that focuses on the particular situation you are solving for. The overarching chart container is a page block element that I titled “Email Details”. This will house the three charts.

Each pie chart is wrapped in a page block section with it’s own unique title. For the apex:chart element, we see the variable EmailScorePieData. That links up to the getEmailScorePieData method on the controller which pulls in a list of wedgeName and count combinations which we can see referenced in the apex:pieSeries element.

Next, we’ll jump into the JavaScript portion of the client code. The JavaScript code on the markup page was designed to handle the checkboxes and compiling a list of ids based on checked/unchecked boxes. I used the code from this source on the internet. My only contribution to the code was to update some of the variable names to match more of what was going on in it. As you can see there is a function for selecting/deselecting one or all checkboxes at a time.

I am not going to take a deep dive into this code, since reading through it should illustrate what is going on there. At this point, all you need to know is that it compiles a list of Contact ids into the ContactIdBuilder variable based on which boxes have been checked as I mentioned earlier.

I did skip over the last part of the markup because it would be easier to make the connection between the ContactIdBuilder variable and the following markup code.

This part of the code, when the Validate button is clicked, it takes the id list stored in ContactIdBuilder and assigns it to the returnString hidden input element. After the value is assigned, the ValidateCheckedEmails method on the controller is called. The returnString value associates to the returnString variable in the controller that we will see shortly. And that is it. That’s all for the user facing part of the code.

CONTROLLER

The controller code consists of two main parts. First, getting data from Salesforce and displaying it to the screen. And the second part is validating the selected rows from the user interface.

Based on the filter selected from the user interface, the getContacts method will return a list of contacts. The main thing that you need to do here is make sure you are pulling back all the fields that the user interface needs to work with, taking into account both the visible and hidden fields. For example, the contact id which is in the background on the checkbox columns.

The method, getItems, retrieves all the filter options for the dropdown list in the user interface. In this method, we put together a list of hardcoded options and then some dynamic options that will allow us to filter on each company in the list.

The three methods that get the data for the charts return a list of EmailData records which are simply key/value pairs. Key being the name of the pie wedge and value being the count or size of the wedge. You can use the pie methods here to copy or modify to suit your own purposes. The more stats you want to present to the user, the more fields you’ll need to retain from the call to our email validation web service. Some of the other fields you may be interested in adding here are, the warning notes, the notes descriptions and/or the SMTP flags (server and mailbox level). There are many other fields that our email validation service returns and you can look at them in more depth here.

The last part of the controller to go over is the call to the method that does the email validate request. The method ValidateCheckedEmails pulls all the contact ids from the returnString variable and sets them up for processing in the CallEV3ByIdList method of the EmailValidationUtil class.

WEB SERVICE CALL

The EmailValidationUtil.apxc is the last file left to discuss. This file does the actual request to the email validation web service. This is the part of the code that you can customize the most; from what you decide to process to what is returned by the service. It is also a good place for any additional logic you may want to implement.

This code should seem very familiar to you if you had read the previous parts of this blog series. It is setup in a very similar way. Just as with the other examples in this blog series, we demonstrate the best practices when it comes to implementing failover. The inputs to the service are the EmailAddress, AllowCorrections, Timeout and Licensekey.

In our example, the email address comes from the contact records selected in the user interface and the rest of the inputs are hardcoded (but they don’t have to be). AllowCorrections accepts true or false. The service will attempt to correct an email address if set to true. Otherwise, the email address will be left unaltered if set to false. Here, I hardcoded it to true but you may want it to be false or use some other business logic to make that determination. The Timeout value specifies how long the service is allowed to wait for all real-time network level checks to finish. Real-time checks consist primarily of DNS and SMTP level verification. Timeout time is in milliseconds. A minimum value of 200ms is required. I have hardcoded it to 2000ms. For the LicenseKey, you will want to either hardcode this into the call (depending on the access that people have to the code) or create a custom object and/or a custom field with the license key that you can lock down with user permission only available to the administrator.

Before I wrap this up I wanted to make mention of writing tests to cover the code. This example is complete but expects you to customize parts of it, so I have not provided any test code. You will want to do that. It will ensure that even as Salesforce updates their system or you make changes to your organization, everything will continue to work as expected.

In conclusion, VisualForce pages are mostly used with the old Salesforce UI the Classic UI, but it can be created in a way so that it will continue to work with the new Lightning experience. In a future blog, I will show a demonstration of how to create a Lightning App while incorporating our validation services. Service Objects has validation services for all kinds of solutions, making Salesforce a perfect platform to demonstrate our services on.

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.

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.

 

Many of us use Google Maps to quickly verify that a location exists or give us an idea of what that location looks like. However, there is a common misconception that it will validate that the address found is correct and deliverable. So although Google Maps is an extremely powerful lookup tool, it will not validate addresses nor does it include the robust features and support included with our DOTS Address Validation-US service. To jumpstart your understanding and dispel some standard misconceptions, let’s explore some of the differences in our Address Validation service and Google Maps.

What Does DOTS Address Validation Do?

Although Service Objects can verify and validate many contact data points such as name, phone and email, our specialty is address validation. For us, addresses consist of business names, address fields, cities, states, and postal codes. Our USPS CASS Certified address validation service is designed to improve internal business mail processes and delivery rates by standardizing contact records against USPS data.

It’s All in the Documentation

Our Developer Guide is a great place to start for an in-depth breakdown of the service and response features for Address Validation. It is extremely useful while integrating and can be used as a reference guide as well when learning more about the information each output field conveys.

24/7 Support When Your Business Needs It Most

With the amount of information provided in the results, it is common to have questions along the road to understanding each of the outputs. Our team is here to help you in this process and provide 24/7 technical support. We can be reached by phone (805-963-1700), email and even live chat on our website. “Best Practice” and “Step by Step Tutorial” blogs are also posted on a regular basis.

Deliverability is Key

One of the biggest misconceptions about Google Maps and Address Validation is the ability to determine DEVLIVERABILITY. Beyond correcting and standardizing an address, our advanced algorithms and wide-reaching data sources allow us to determine if an address is deemed deliverable by the United States Postal Service. The service response will contain a Delivery Point Validation (DPV) indicator of 1-4 that can be used based on specific business logic. A DPV score of 1 indicates a perfectly deliverable address whereas a score of 2-4 indicates missing or incorrect inputs in the address field. The corrected address, component fields, and extra information such as the DPV indicator, residential delivery indicator (RDI), vacancy flags and more will be included and can be leveraged in your workflow.

Primarily, the locations that Google Maps will mark aren’t necessarily mail deliverable. There is a lot of leniency within the Google algorithms that allows for guess work to be made. Although Google can put a pin on the map for a given input address, it does not mean that a postal carrier will deliver mail at that location. However, if DOTS Address Validation marks a location as invalid, you can be sure you are getting genuine and accurate information.

When Is Google Maps Useful for Address Lookup?

With all of that said, Google Maps should not be discounted in its ability to investigate a location. If the image data was captured recently it can be used to understand why our service marked an address the way it did. A prime example of this is an address marked as having a “street number out of range.” By checking Google Maps data and cross referencing our service response, more light can sometimes be shed about that address location.

While you can use Google Maps to potentially confirm if a location exists, it is imperative to use robust validation tools like DOTS Address Validation to ensure any mail your business sends can actually be delivered, saving time and money.

If you have any questions about validating, verifying or appending addresses, or any other contact data points including name, phone, email and device, feel free to contact us.

At Service Objects, we are fully committed to our customers’ success, which is a main factor in why over 90% of our business is from repeat customers. And with over 16 years of experience in contact validation, we have accumulated a broad base of industry expertise, created numerous best practices and are considered thought leaders in global data validation.

It is because of this knowledge that some of our customers turn to us when they lack the internal resources to carry out their data quality project. Whether it is assistance in implementing a data quality initiative, asking for customization to our products to meet specific business needs or help integrating our solutions into Marketing or Sales Automation platforms, Service Objects’ Professional Services can assist your business in achieving optimal results on your project in a quick and efficient manner.

Here are just three of the ways we can help:

Integration Programming and Code Support

If your team is overwhelmed or lacks the technical resources to integrate data quality solutions into your existing systems, Service Objects can step in and quickly get your project moving. We provide your team with the technical knowledge, support, and best practices needed to implement your chosen solution in a timely fashion and within your budget.

CRM or Marketing Automation Platform Integration

We have created cloud connectors for the leading sales and marketing platforms and have developed extensive knowledge on how these systems work with our data quality solutions. We enable your organization to implement best practices, allowing your business to verify, correct and append contact data at the point of entry. The result is your contact database contains records that are as genuine, accurate and up-to-date as they can possibly be.

Custom Services

Our engineers have years of experience creating, implementing and supporting data quality services in many different programming languages. As a result, we can customize our existing services to solve a challenge that is specific to your business. Our proactive support services team will work with your technical team to refine, test and implement the custom service to work for your business’ specifications.

These are just some of the ways we can help. For more information about how you leverage our industry expertise and technical knowledge, contact us.

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.