Search

Latest Post

In my last post on this subject, I provided an overall framework for exchanging data with Hobsons Connect via web service calls. In this post, I’ll provide specific examples of how to call web services from PowerShell. Although the examples in this post were written with Hobsons Connect product in mind, similar web services are available for the Retain product and in fact many of the functions are identical.

Hobsons Connect uses SOAP-based web services for communication. SOAP, short for “Simple Object Access Protocol”, encapsulates input and output information in XML constructs. There are five main steps for dealing with SOAP-based calls in PowerShell

Instantiate a Web Service object. This is done through a command such as the following:

Hobsons provides a number of different web service functions and the parameters for each call varies. Fortunately, Hobsons has created a document that describes each call and provides some examples. This web service documentation is available at the link below:

In most Connect service calls, you’ll need to supply a “Client Name” and “Pass Key” as credentials. These are represented in the call above by the $ClientName and $PassKey variables respectively, and are unique strings provided to you by Hobsons. In this case, we also have two input strings, $InputXML and $AttributeXML.

4. Capture the output XML returned by the service call. In the sample call above, output is returned in the $ReturnValue variable.

5. Finally, you parse the output XML and do something with it. You will see how this is done in some of the examples that follow.

Let’s look at some real examples of code to see how these steps work together. This first example illustrates how to call the GetAllAttributes function. This function is useful to determine the internal name of attributes which you might want to use in other web service calls. Within the Hobsons Connect application you are able to see the “Mapped Name” of each attribute. The Mapped Name is the user friendly name you define for attributes and use in the application interface provided by Hobsons — “Application Status” for example. However, you must use the corresponding “Internal Name” when working with attributes in web services. Internal names are assigned by the system and are based on the type of attribute — text, numeric, or date. For example, the internal name for “Application Status” might be “text359″.

Each attribute description begins with a <attribute> tag. The <type> tag is used to identify whether the information refers to a folder or attribute. Notice the <name> and <mappingname> tags, as well as additional tags that identify the type and size of the attribute.

Below is a partial view of what a formatted view of the output might look like after the XML is parsed. In this case, some information such as the type and size of the attribute have been left out.

Now let’s look at sample code for searching for a contact record using the GetContact web service call. In the previous example, our only inputs were our Hobsons Client Name and Passkey. However for the GetContact call we have two more input parameters. The first of these is the search criteria, which consists of one or more attribute values used for comparison. Each criterium in the search consists of three parts: the internal name of the attribute, a value for comparison, and the type of comparison (equals, greater than, etc.). The example code below illustrates how to construct an XML search string to match on first and last name:

When more than one attribute is included in the search criteria, results for contacts which meet all conditions will be returned. That is, there is an implied “AND” between the attribute conditions. Hobsons also provides a function called GetContacts (easily confused with GetContact) which returns contacts meeting any of the conditions. That is, there is an implied “OR” between the attribute conditions.

In addition to search criteria, an XML string containing a list of attributes to returned with the contact information also needs to be provided in the call. The internal names rather than the mapped names from the Connect application interface must be specified. Below is an example which references both fixed (standard) attributes and custom attributes.

In order to make practical use of this information, you will likely have to parse the attributes out into individual variables. This can be done in several ways. The sample code below shows you how to assign the output to an XML variable and use object nomenclature along with the “where” verb to split each attribute into a separate variable.

In addition to querying data from Connect, you can also use web service calls to create or update contacts. To create a new contact, you first form the XML containing the attributes and values you want the new contact to use. A simple example appears below:

In this example, the variable $wsResponse will contain an XML string denoting if the operation was successful or not. Below is what the response looks like when a new contact is successfully created. The unique ContactID of the new contact (12345 in this case) is returned and a Code value of 1 indicates success.

A code of 2 indicates that a contact already exists. This determination is made based on the duplicate checking rules you have established in Connect. For example: First Name + Last Name + eMail. When a duplicate contact is found, the existing ContactID will be returned in the XML and attribute values will not be updated.

Updating an exising contact is similar to adding a new contact. You start out by forming the attribute XML, including only those attributes which need to be changed. An example of changing an address is shown below:

Note the inclusion of the $ConnectID variable in this call. This variable must contain a string containing the contact’s existing Connect ID. If you do not have the Connect ID, you can use the previously mentioned GetContact service call to obtain it.

As with other service calls, Connect will return an XML string noting success or failure. An example is shown below:

<result>
<code>1</code>
<ErrorMessage></ErrorMessage>
</result>

If the value of code is anything other than 1, the call failed. The contents of ErrorMessage may give you a clue as to what the problem is.

There are many more web service calls available than I’ve shown, but hopefully this post gives you a framework to get started.