1. Encompass Support Center
  2. Data
  3. Anthology Encompass Web Services 2.1 - Engineering Documentation

Upgrading From Web Services 1.0 to 2.x

Print Friendly and PDF Follow

Advantages of WS 2.x

  • Encompass Web Services was designed to leverage best practices for web services utilizing the latest features of the Microsoft .Net 3.5 platform.
  • All methods are fully compatible with all common request types (HTTP Get, HTTP Post and SOAP).
  • The methods and parameters have been consolidated and simplified, making them more intuitive.
  • The definition of the web service methods is available in standard WSDL format.
  • Instance data, such as Campaign contributions and Event tickets are now available via web services.
  • All parameters for the web service methods are now appropriately typed.
  • WS 1.0 doesn't support anything for events, campaigns, and commerce. It has only one web service that covers biographical data.

Syntax Changes

The syntax change (from <export_header_name>value</export_header_name> to <column name=”export_header_name” value=”value” />) supports a consistent service definition. Previously, the service definition could vary based on the parameters passed to a method. This makes integration via built-in language tools (such as web references in .Net) much simpler.

For an integration using SOAP, escaped characters are handled per the XML specification. Only the five “predefined entities” require encoding (quotation mark, ampersand, apostrophe, less-than, greater-than).
For an integration using HTTP post or get, escaped characters are handled per the URL encoding specification (i.e. content-type=x-www-form-urlencoded). All non-ASCII characters require encoding.

Null values are handled and maintained within the web services implementation. A zero-length value for the value attribute is converted and/or compared appropriately based on the data type and nullability of the underlying column.

  • For methods that return data, nulls are represented as empty value attributes (i.e. value=””).
  • For methods that update data, an empty value may be passed in place of a null value. It will be compared appropriately. You may also specify a null value with xsi:nil="true". You cannot pass value=”null” and have it evaluate as a null value.

Upgrading from Web Services 1.0

Backwards Compatibility

While Encompass Web Services 2.x provide similar functionality to version 1.0, they are not backwards compatible with regard to their syntax. Parameters have been added and their names have been modified. Methods have been consolidated. Functionally, the final version of version 2.x will provide all the functionality of version 1.0 and more.

General Changes

The following are some general changes that must be accounted for when upgrading from Encompass Web Services 1.0 to version 2.x.

  • MemberInformation
    • The syntax for all web service methods that return MemberInformation elements has changed. The attribute of the MemberInformation element is now always called Constituent_Id. Previously, the attribute name was the name of the constituent id field. The child elements are now all Column elements and contain the field name and value as attributes. Previously, the Field name was used as the element name and the value was the inner text of the element.

Web Service Method Changes

The following are guidelines for upgrading specific method access from Encompass Web Service 1.0 to version 2.x.

  • AllColumnResults
    • Use GeneralQuery::AllColumnResults
    • The return syntax is the same except for an additional attribute called “Is_Instance”. As GeneralQuery::AllColumnResults will not return instance fields, you can safely ignore this attribute when using this method.
  • GetOneMember
    • Use GeneralQuery::GetOneMember
    • The member_id parameter is now called constituentId.
    • The filter parameter has been removed.
    • The style parameter has been removed and only style 1 is now supported.
    • The return syntax has changed (see MemberInformation under General Changes).
  • GetMembersChangedDuring
    • Use GeneralQuery::GetMembersChangedDuring
    • The StartDate parameter is now called changedFrom.
    • The EndDate parameter is now called changedTo.
    • The style parameter has been removed and only style 1 is now supported.
    • The return syntax has changed (see MemberInformation under General Changes).
  • GetUpdatedMemberChangedDuring
    • See GetMembersChangedDuring above as well as the following.
    • Any identifier columns (surrounded with parenthesis) previously included in the columns parameter should still be included in the column parameter. Any non-identifier previously included in the columns parameter should be included in the changeColumns parameter.
    • The IncludeGuests parameter is now called includeNonMembers.
    • The IncludeBlankConstituentIds parameter is now called includeBlankIds.
  • GetUpdatedMemberChangedDuringSOAP
    • See GetUpdateMembersChangedDuring above as the SOAP protocol is now supported when accessing all web service methods.
    • GetMembersChangedSince
    • Use GeneralQuery::GetMembersChangedSince
    • The date parameter is now called changedSince.
    • The style parameter has been removed and only style 1 is now supported.
    • The return syntax has changed (see MemberInformation under General Changes).
  • GetUpdatedMembersChangedSince
    • See GetMembersChangedSince above as well as the following.
    • Any identifier columns (surrounded with parenthesis) previously included in the columns parameter should still be included in the column parameter. Any non-identifier previously included in the columns parameter should be included in the changeColumns parameter.
    • The IncludeGuests parameter is now called includeNonMembers.
    • The IncludeBlankConstituentIds parameter is now called includeBlankIds.
  • GetUpdatedMembersChangedSinceSOAP
    • See GetUpdatedMembersChangedSince above as the SOAP protocol is now supported when accessing all web service methods.
  • Update
    • Use GeneralQuery::Update
    • The authentication (login and password) and the addNonExistingIDs values are no longer passed as attributes of the authentication element. Instead they are separate parameters for the method. The authentication element has been removed.
    • The style attribute has been removed and only style 1 is now supported.
    • The input parameter was previously an array of any XML element. It is now an array of MemberInformation elements as there is no need to include an authentication element.
    • The MemberInformation syntax has changed (see MemberInformation under General Changes).
    • The return syntax has changed. Previously, the response from this method contained a single message and a list of errors, if applicable. The new version of the response has changed significantly, containing more information on what was added and updated. See UpdateResults under Return Syntax.

Related articles