We recently revamped our developer guides to make them more user-friendly. The information for each service has been broken into its component parts, to make each feature more comprehensible. In this article, we share some of the changes we have made and they help you get the most from our products.

1. A new, easy-to-navigate landing page

Our new landing pages now have a developer guide map (our US Address Validation product is a good example) to provide easy access to each web service’s component parts. By clicking on the links on this page, you will be taken directly to the respective page that provides a more in-depth breakdown of the service’s individual fields. Below is an example of one of these landing pages.

2. Quick lookup & Open API

Our quick lookup page has been greatly simplified to provide only the most relevant data at your fingertips. Once you have received a trial or production license key, the validation process is as simple as plugging your input data into the fields, adding your license key, and clicking Execute. The web service request is made for you and the response formatted in the output section.

Similarly, if you are looking to run a different operation the Service Reference page has quick lookups for every operation within its respective service.  Check out an example of Address Validation US.

3. Citations and Additional Field Information

Have questions about the service fields? Need more information about how to leverage them to fit your business needs? Our redesign now includes accordion panels that can be expanded to provide more information about the field. We’ve also added citations next to some of the inputs and outputs where we have additional information available. In the example, below the Barcode Digits is linked to the following blog:

https://www.serviceobjects.com/blog/address-deduplication-using-usps-barcodes/

By clicking a reference link, you can read a more in-depth analysis of the field and often gain ideas about how to use the data point in your workflow.

Each of these new features is designed to help you get up and running more quickly with our services, and serve as an easy-to-use reference for your development work. Try out our new developer guide soon, and let us know what you think!

Now that you have your free trial key, what should you do with it?

First, you’re going to want to try it out right away. If you’re like the rest of us, when you get something new you want to see how it works. Testing it in your integration to see if it meets your needs is the best approach.

This article walks you through simple steps and tools that will help you get started, so you can be up and testing quickly.

Testing multiple validation services

If you’re interested in testing additional data validation services, you’ll need a unique key for each one. You are welcome to test as many of our services as you’d like and can easily request additional keys directly from the product page or check out our product directory to see what else interests you.

Although it may seem obvious that a key for DOTS Address Detective won’t work with our DOTS Email Validation service, the same is true for versions within a product. For example, you require unique trial keys for DOTS Address Validation – US 3 and DOTS Address Validation – US 2. In this case, it is the difference between the latest and greatest version of address validation and a legacy service with fewer features.

Why do we keep old services around? To ensure our clients are supported and allow them to control when and if they want to upgrade to the latest version.

Step-by-step with your trial key

To get started, you will want to visit our trial keys’ Service Path page, where all of our products and their multiple versions are listed. Select the product that you are working with to see the endpoint specifications page.

For demonstration purposes, we will use Address Validation – US. Each endpoint specification page can be considered a hub, as it has links to other places of interest (like the developer guides) and a section that allows you to do real-time tests. Below is a screenshot of the page for Address Validation – US.

On the right, you will see a list of the available operations. Expanding any of these items will reveal the expected inputs for the selected operation.

You can see the output format for the response or result shown below the input section.

This is a great place to test out the service. If you click the “Try it out” button at the top right of the input section, you can add any address and see the result immediately. If you provide your own data, you can see exactly what the request and response look like with your inputs.

On the left side of the endpoint specifications page, you’ll see two sections:

Sample Inputs has examples of both good and bad addresses that can be clicked on to prepopulate the form for the operation. Try these out to get a good grasp on the difference in the responses.

Other Links has links to the developer guide showcasing the service you have requested, a link to the WSDL for SOAP calls, and links to the REST and SOAP paths.

Moving on to integration

Once you are comfortable with the sample results and how the requests and responses perform, it’s time to move on to a quick integration. Depending on your resources and/or process, there are two typical approaches; creating a testing environment (recommended) or using sample code to test.

1. Create a test environment

We recommend creating a sandbox, copy, or clone of your current environment and dropping our code right in. This may sound a bit heavy this early in the trial process, but the ease of integration makes it quite simple and gives you the strongest sense of how our services work.

Once you have created your test environment, take a look at your process and code to determine where to add our code to execute the validation service. After you have identified where to implement the code, you can visit our developer guides for a comprehensive guide to getting started, including a list of operations and code snippets for most major programming languages.

In the example below, we are looking at the Address Validation – US developer guide and you can see that we have a variety of code snippets. Select your preferred code snippet, add your trial key and you will be up and running in short order.

2. Use sample code to test

If you do not have the opportunity to integrate directly at this stage, you can download our sample code for a demonstration of a UI form and a validation completed on button click. We find that this sample code is also useful in facilitating integrations (like the one discussed above).

You can find all of our sample code under the developer section of our site’s main navigation and in three easy steps, download the code you need.

Step 1: Select the programming language(s) you are working with.

Step 2: Choose the product(s) you are interested in.

Step 3: Download your sample code from the right-hand column.

Quick note on sample code: We are always adding new languages and sample code but if you don’t see what you need, let us know and we will be happy to help create it for you.

Testing with sample code

Once you have the code downloaded, open it in your respective integrated development environment (IDE). In this case, I am using the C# sample code, so I am opening it in Visual Studio. You should see something like this list of files when you open the solution:

Now, simply run the code and you will have a fully functioning demo. You can also modify it to suit your own needs and add your own design.

Note: In practice, you won’t want to display the license key as an input. We recommend adding it to the code in the background, in a web config file or something similar.

We are here to help!

This covers the basics of getting started with our services. We are also happy to share our experience with common use cases and provide recommendations on best practices to solve your business needs. However you choose to test and use our services, our knowledgeable application engineers are available to help any time.

In an ideal world, data entry would always be perfect. Sadly, it isn’t – human errors happen to end users and call center employees alike. And while we make a good living cleaning existing bad data here at Service Objects, we would still much rather see your downstream systems be as clean as possible.

To help with that, many organizations are getting an assist with Google, in the form of the Autocomplete with their Places API.  If you setup your form properly and use their API you can have address suggestions appear in a dropdown for your end users to take advantage of to help enter correct data into your system. That’s great, isn’t it?

It does sound great on the surface, but when you dig a little deeper there are two problems:

• First, Google Places API often does not often suggest locations to the apartment or suite level of detail. The point is that a considerable segment of the population lives in apartments or does business on separate floors, suites or buildings.
• Second, the locations the Google Places API suggests are often not mail deliverable. For instance, a business may have a physical location at one address and receive mail at a completely different address.  Or sometimes Google will just make approximations as to where an address should be.

For example, check this address out on Google Maps: 08 Kings Rd, Brighton BN1 1NS, UK.  It looks like a legitimate address, but as the street view shows, it does not seem to correspond to anything.

These issues can leave gaping holes in your data validation process.  So, what can you do? Contact us at Service Objects, because we have the perfect solution: our Address Suggestion form tool. When combined with the Google Places API you will have a powerful tool that will both save time and keep the data in your system clean and valid.

This form tool is a composite of the Google Places API and our Address Validation International service.  The process consists of the data entry portion, the Google Paces API lookup, then the Address Validation International service call, finally displaying selectable results to the end user.

Let’s start by discussing the Google API Key, and then the form, and finally the methods required to make that Google Places API call.

Google Places API requires a key to access it.  You can learn more about this API here.  Depending on your purposes you may be able to get away with using only Google’s free API key but if you are going to be dealing with large volumes of data then the premium API key will be needed.  That doesn’t mean you can’t get started with the free version: we in fact use it to put our demos together, and it works quite well.

When setting up your key with Google, remember to also turn on the Google Maps Javascript API, or else calls to the Places API will fail.  Also, pay particular attention to the part about restricting access with the API key.  When you have a premium key this will be very important because it will allow you to set the level at which you want the key to be locked down, so that others can’t simply look at your Javascript code and use your key elsewhere.

The form we need to create will look like a standard address data entry form, but with some important details to note.  First let’s look at the country select box: we recommended that this be the first selection that the user makes. Choosing a country first benefits both you and the user, because it will limit suggested places to this country, and will also reduce the number of transactions against your Google Places API key.  Here is a link to how Google calculates its transaction totals.

Another important note is that we need to have the Apt/Suite data entry field.  As mentioned earlier, the Google Places API often does not return this level of resolution on an address, so we add this field for the information be provided by the end user.

The rest of the fields are really up to you in how you display them.  In our case, we display the parsed-out components of the results from selected address back into the rest of the address fields.  We keep all the address input fields editable so that the end user can make any final adjustments they want.

The methods associated with this process can be summarized by a set of initializations that happen in two places: first, when a country is selected, and second, when the focus is on the Address field by a user clicking into it.  For our purposes we default the country selection to the United States, however when the country is changed the Autocomplete gets reinitialized to the selected country. And when a user clicks into the Address field, the initialization creates a so-called bias, e.g. Autocomplete returns results based on the location of your browser.  For this functionality to work, the end user’s browser will ask to let Google know its location.  If the user does not permit Google to know this the suggestion is turned off and does not work.

This bias has a couple of interesting features.  For instance, you can change the code to not utilize the user’s browser location but instead supply a custom latitude and longitude.  In our example, the address suggestion does not end up using the user’s current position when the selected country is not in the same country as the user.  But when the user is in the same country as the selected country then the results returned by the Google Places API are prioritized to your location.  This means that if you are in Santa Barbara, CA and select the United States as the country, when you start typing a United States address you will first see matching addresses in Santa Barbara, and then work outward from there.

You can customize the form bias to any particular location that you have a latitude and longitude for.  The ability to change this bias is very useful in that setting the proper bias will reduce the number of lookups against the Google Places API before finding an address match, and will also save manual typing time.

Now let’s discuss the Address Validation International service API call, which consists of a key, the call to the service and setting up best practices for failover.

Let’s start with the key.  You will need to either have a live or free trial license key from us, the latter of which can be gotten here.  For this example, a trial key will work fine for exploring and tinkering with this integration.  One of the great things about using our service is that when you want to turn this into a live production-ready solution, all you have to do is switch out the key from the trial to the production key and switch the endpoint to the production URL, both of which can be done in minutes.

The call to the Address Validation International service will be made to either the trial or production endpoints, which will depend on the key that you are using.  The details of the service and how to integrate with it can be found in our developer guides.  In the Javascript code you will round up all the data in the fields that were populated by the address suggestion selection and send them off to the service for validation.  The code that manages the call to the Address Validation International service needs to be executed on some back-end server client.

It is strongly discouraged to make the call to the service directly from Javascript, because it will expose your license and allow someone to take it and use your transactions maliciously.  You can read more about those dangers here.  Also, here is a blog about how to make a call to another one of our services using a proxy.  The basic idea is that your Javascript call will call the proxy method that contains your license key, essentially hiding it from the public.  This proxy method will make the final call to the Address Validation International service, get the results from it and pass those results back to the original call in the Javascript.  In this situation, the best place to implement failover is in the proxy method.

So what is failover? Failover, from the perspective of an end user developer, is just a secondary data center to call in the unlikely event that one of our primary data centers go down or does not respond in a timely manner.  Our developer guides can again help with this topic.  There you will also find code snippets that demonstrate our best practice failover.

Once this call is set up, all that is left is evaluating the results and displaying the appropriate message back to the end user. While you can go through our developer guides to figure this out, the first important field to examine in the response from the Address Validation International service is the Status field – here is a table of what is expected to be returned:

Address Status

Another important field will be the ResolutionLevel, which can be one of the three following values: Premise, Street and City.  The values returned in these two fields will help you make a decision in the code with respect to what exactly you want to display back to the end user.  What we do in our demo is display the Status and ResolutionLevel to the end user along with the resulting address.  Then we give the user a side-by-side view of both the resulting address just mentioned and the original address the user entered.  This way the end user can make a decision based on everything we found. In the case shown here, for example, we updated Scotland to Dunbartonshire and validated to the premise resolution level.

There are many customizations that can be made to this demo, such as the example we mentioned earlier about setting up the bias.  Additionally, instead of using the Address Validation International service you could also create an implementation of this demo using our Address Validation US or our Address Validation Canada products.

Want to try this out for yourself? Check out our Address Suggestor video tutorial or contact one of our Account Executives to get the code for this demo – we’ll be glad to help.

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 it 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 allow 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 the 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 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.

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 3^rd 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.

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.

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.