- Location and Access
- Staging Environment
- Character Encoding
- Date Criteria
- Datetime Format
- Special Elements
- Gift Integration with Identity Checkpoint and Member Merge Systems
- Matched and Unmatched Records in Encompass
- Gift Transaction Flow Diagram
- Linked Transactions
- Return Syntax
- Error Syntax
- Error Codes
- Message Syntax
- Best Practices
Web Services are designed to help make it easier for software applications to communicate. Web Services allow clients to retrieve and update raw data in the system. They help to solve the interoperability problem between provider and client systems by giving different systems a way to link their data and to exchange data between applications and platforms.
With Web services, a client’s database (such as fundraising data) can connect with their Encompass system to make information exchange easier. The information exchange can be set up by the client to happen automatically on a recurring basis, instead of downloading a file and then loading it into the system. Web Services allows clients, for example, to get all data, or just updated information from their Encompass system to update their database. Clients can use Web Services Version 2.x to query and update Event and Campaign data as well as for Profile data (available since Version 1.0). Our clients most commonly use Web Services to sync constituent data like name, address, email, and phone numbers.
Web Services – Web Services provide a standardized way of integrating Web-based applications using the XML, SOAP, WSDL and UDDI open standards over the internet. XML is used to tag the data, SOAP is used to transfer the data, WSDL is used for describing the services available and UDDI is used for listing what services are available. Web services allow organizations to communicate data without detailed knowledge of each other's IT systems behind the firewall.
SOAP – Simple Object Access Protocol. SOAP provides the envelope for sending Web Services messages. SOAP provides a way to communicate between applications running on different operating systems, with different technologies and programming languages. SOAP messages are independent of any operating system or protocol and may be transported using a variety of Internet protocols, including SMTP, MIME, and HTTP.
XML – Extensible Markup Language. XML is a markup language much like HTML; however, XML is designed to carry data, not to display data. It allows designers to create their own customized tags, enabling the definition, transmission, validation, and interpretation of data between applications and between organizations.
WSDL – Web Services Description Language. WSDL is an XML-based language for describing Web services and how to access them. WSDL is also used to locate Web services.
Form – Encompass includes many types of forms within Encompass: Profile Forms, Event Forms, Campaign Forms, Membership Forms, and regular Forms. With Encompass Web Services 2.x, web services that refer to a form could be any of these types.
Instance fields – Within Encompass, an instance field is one in which there may be multiple values per member. An instance field on a form provides for unique entry each time the form is submitted. A commerce field is always an instance field. Non-instance fields always retain a single value, for example first and last name, or email.
Nonmember transactions – un-authenticated transactions tied to a nonmember (or unknown) account
Location and Access
Encompass Web Services 2.x can be accessed by appending a service name to a base URL:
- United States base URL: https://api.imodules.com/ws/21/
- Canada base URL: https://apica.imodules.com/ws/21/
- Australia base URL: https://apiau.imodules.com/ws/21/
The available services are:
<![CDATA[GeneralQuery.asmx ]] >– Provides access to non-instance fields that are not specific to any Form. Direct URL
<![CDATA[ControlQuery.asmx]] > – All fields that are specific to a Form (represented by a control ID). Accessing a Control method and specifying a control ID of “0” is the same as accessing a General method. Direct URL
<![CDATA[TransactionsQuery.asmx ]] >– Instance fields that are specific to a commerce transaction, useful for reconciliation reporting. Direct URL
<![CDATA[EmailCategoryQuery.asmx ]] >– Allows the import and export of Email Category opt-out and opt-in information. Direct URL
<![CDATA[LoginQuery.asmx ]] >– Allows logging a constituent in by proxy. Direct URL
<![CDATA[MemberMergeQuery.asmx]] > – Allows queuing a non-member record and an associated constituent record for the nightly Member Merge process. Direct URL
<![CDATA[ContentQuery.asmx]] > – Allows pulling event listing / calendars, and event content information. Direct URL
If you do not have credentials for your site, please contact your Encompass Customer Success Manager.
A staging environment is available for testing middleware against any changes made to the Encompass Web Services (enhancements/defect fixes) prior to the release of such changes to the live production environment. The staging environment will allow you to actually see how the change will function in your particular environment and test your middleware against it. This solution will help to ensure that clients are satisfied with the changes to Web Services and that changes to the services are not breaking anything in the process of moving data. This is one of many solutions in place to keep client data synchronization processes from being disrupting following a release. The intended staging period is from the time that a code change has been successfully verified by the Encompass QA Team through the actual release of the code change to production (This time period is typically at least one month).
The Web Services Staging Environment is available to any Web Services client when:
- An agreement on a test site has been made. A separate Web Services login (GUID) and password will be given for this site.
- A one-time request to have your test site receive the staging code base following each development sprint has been made with your Encompass representative.
Separate Staging Web Service URLs are used in conjunction with test sites on the staging code base and can be accessed at the following base URL:
If there are enhancements or defect fixes that have affected the Web Services, regular email communication will be made following the development sprint announcing that the new codebase is available.
Encompass Web Services use UTF-8 encoding to meet the expected XML standard and support of foreign characters.
When using the GetMembersChangedDuring or GetMembersChangedSince methods, the criteria used for the rows returned depend on the values specified in the changedColumns parameter. If this parameter is populated, the query returns rows for which the specified fields have been updated within the timeframe.
If this parameter is not populated, the query returns rows for which the system “last_updated” field matches the specified timeframe. If transactions were requested, then time frame will also be used for the criteria for the rows returned, with the results returned based on transactions with purchase dates that match the date criteria.
In order to help support the needs of international clients, all dates and date/times are returned in a format that conforms to the ISO 8601 standard.
This is also the accepted format in Web Services requests for datetime parameter values, such as changedFrom, changedTo, and changedSince. Date values can be provided without the use of the time value.
All dates are provided or accepted in North American Central Daylight time. (Time zone offset: UTC - 5 hours. CDT is 5 hours behind Coordinated Universal Time (UTC). Note that CDT is a daylight saving time/summer time zone.)
Filter parameters allow the results of a web service method to have a custom filter applied. The syntax for this statement is very similar to a SQL “where” clause.
The syntax of the filter parameter supports the following:
- The inclusion of any field returned by the applicable GetAllColumns web service method. The Field should be enclosed in square brackets.
- Multiple criteria statement joined with “and” or “or”.
- Grouping of criteria statement using parentheses.
- The “=“, “<>”, “>”, “<”, “>=”, “<=”, “like”, “not like”, “is” and “is not” operators.
- Integer, decimal, date and string value types. String values should be enclosed in single quotes and may contain escaped single quotes.
The following are some common example of filters applied to web service method results:
- Return records with a first name of Tom: [First_Name] = ‘Tom’
- Returns all records that do not have a last name of O’Brian: [Last_Name] <> ‘O’’Brian’ (note the two ’, not one ”)
- Return all records with a class year equal to or greater than 2000 and less than 2008 (not including 2008): [Class_Year] >= 2000 and [Class_Year] < 2008
- Returns records with a last name of Smith and a first name of Tom or Thomas: ([First_Name] = ‘Tom’ or [First_Name] = ‘Thomas’) and [Last_Name] = ‘Smith’
- Return records with a first name starting with T: [First_Name] like ‘T%’
- Return records with a first name containing T: [First_Name] like ‘%t%’
- Return records with a first name ending with T: [First_Name] like ‘%t’
- Return records with email addresses: [Email_Address] is not null
There are two types of identifiers in the system: those that identify non-instance data and those that identify instance data.
- Non-instance identifiers identify a single constituent in the system. In relation to web services, these identifiers are always referred to as Constituent ID, even though it may be configured differently within the site. This is done to support a standard XML definition.
- Non-instance identifiers may or may not be editable depending on site configuration. In the absence of an editable secondary identifier, Encompass uses the system generated identifier member_id instead, which itself is not editable.
- Some examples of non-instance data include first name, last name, and email.
- Instance identifiers identify a data item for a particular constituent, though the constituent may have multiple instanced values for the item. Instance data may be referenced through the system-generated instance ID or through an optionally configured external row ID.
- External row identifiers are immutable fields that adhere to a particular naming convention as defined in the client’s database of record. The value of an external row identifier may be set for any instance that is created via web services.
- An example of instance data is the amount donated to a campaign. Each will be referred to by a unique instance identifier.
- In the event that both an instance ID and external row ID is specified for an instance, the system ensures that they refer to the same instance. If this is not the case, the system will return an error.
Biographical Updates | General fields (non-instance fields that are not specific to GeneralQuery an Event or Campaign) are available through the General methods (web service methods defined in the GeneralQuery web service).
- GetAllColumns – returns all General Fields available. These are the fields available to query on or update when accessing General methods.
- GetMembers - returns all constituent records meeting the required filter.
- GetMembersChangedDuring – returns all constituents records that have been changed within the specified timeframe.
- GetMembersChangedSince – returns all constituent records that have been changed since the specified date.
- GetOneMember – returns the specified fields for the member matching the specified constituent ID.
- GetOneMemberByMemberId – Returns the specified fields for the member matching the specified Encompass member ID.
- Update – allows fields to be updated and rows to be added. This method is only available when using the SOAP protocol due to the complex nature of the parameters this method requires.
- UpdateKeepChanged – allows fields to be updated and rows to be added. This method is only available when using the SOAP protocol due to the complex nature of the parameters this method requires. UpdateKeepChanged provides the ability to avoid overwriting fields that have been updated online over a certain period of time.
General Query Samples (SOAP envelope not shown in all cases)
Update Call (making a simple member fields request)
Event/Campaign/Form Updates | Control fields (instance fields and/or fields that are specific to an Event or Campaign) are only accessible through Control methods (web service methods defined within the ControlQuery web service). Control ControlQuery methods require that the control ID relating to the Form, Event or Campaign be specified. The fields available to these methods are limited to the fields relating to the specified control ID. At this time, Recurring Transactions will not show in the ControlQuery results. Only the first payment.
- GetAllColumns – returns all Control fields available for the specified control. These are the fields available to query on or update when accessing Control methods.
- GetAllControls – returns all controls available including the ID, name, type (i.e. form, event or campaign), the group id of the community the form was created in, the last time the structure of the form was changed, and the last submission the form received. These are the control ID used when accessing Control methods.
- GetControlSettings – returns all details/attributes for the specified control.
- GetMembersChangedDuring – returns all constituents records that have been changed within the specified timeframe for the specified control.
- GetMembersChangedSince – returns all constituent records that have been changed since the specified start date through the present time for the specified control.
- GetOneMember – returns the specified fields for the member matching the specified Constituent ID and specified control.
- GetOneMemberByMemberId – returns the specified fields for the member matching the Encompass member id.
- GetSelectedControls – Get an array of controls matching the specified control type.
- Update – allows fields to be updated and rows to be added for the specified control. This method is only available when using the SOAP protocol due to the complex nature of the parameters this method requires.
- UpdateKeepChanged – allows fields to be updated and rows to be added for the specified control. This method is only available when using the SOAP protocol due to the complex nature of the parameters this method requires. UpdateKeepChanged provides the ability to avoid overwriting fields that have been updated online over a certain period of time.
Control Query Samples
GetMembersChangedDuring Response w/ Recurring Transaction
Subsequent recurring transactions will then be available for retrieval (In our example, there would be 11 more transactions like the one below, 1 per month). Any additional transactions will show in the transactions node. Querying a date range that includes any of the transaction dates will return the entire record and all transactions that have been processed. Items in blue will be unique to that transaction.
Reconciliation Reporting | Transaction Fields (instance fields that are specific to a commerce transaction) are available through either the Control Methods or the Transaction Methods. For the control methods, only transactions relating to that control are returned. For the Transaction methods where there is not a control id, TransactionsQuery then all transactions matching the input criteria are returned. Only transactions are returned in the Transaction Methods. If you need other fields along with the transactions then the Control Methods should be used. Accessing a Control method and specifying a control ID of “0” is the same as accessing a General method.
- GetOneMember - This allows for simple export of a constituent’s transaction history; particularly useful when working with recurring transactions.
- GetOneMemberByMemberId - Returns all transactions for the member matching the specified Encompass Member ID.
- GetTransactionsAllBetween – Returns all transactions within the specified timeframe.
- GetTransactionsAllSince – Returns all transactions since the date specified.
- GetTransactionsByControl – Returns all transactions for a control.
- GetTransactionsByControlBetween – Returns all transactions for a control within the specified timeframe.
- GetTransactionsByControlSince – Returns all transactions for a control since the date specified.
- GetUnreviewedTransactionsAllBetween – Allows pulling transactions out of Encompass immediately without the use of the non-member merge or ICP systems. See the Gift Integration section for more information.
Transactions Query Samples
Successful One-time Transaction w/ Ledger Code
Successful One-time Transaction. If the user has a Constituent_Id (usually meaning they are logged in using their primary constituent record) it will display in any response from the TransactionQuery:
Successful Recurring Transaction:
Successful One-time Transaction with Skipped Billing (check payment through admin, etc.):
Failed Transaction (Billing information is not returned):
- GetAllCategories – Returns all categories for all communities.
- GetCategoriesByCommunity – Returns all categories within a specific community.
- GetMembersByCategory – Get all members that are opted out of or have opted back in to a specific category.
- GetMembersByCommunity – Get all members that are opted out of or have opted back in to of a specific community.
- GetMembersChangedDuring – Get all members have opted out of or have opted back in to an email category within a specific date range.
- GetMembersChangedSince – Get all members that have opted out of or have opted back in to after a specific date.
- GetOneMember – Get all all opt-outs or re-opt-ins for a specific member matching the specified Constituent ID.
- GetOneMemberByMemberId – Get all opt-outs or re-opt-ins for a specific member matching the specified Encompass Member ID.
- Update – Allows ability to opt-out members.
- ValidateCredentials – Tests credentials against the system and either returns an error code or a token.
- ValidateConstituentId – Locates account by Constituent Id, vets it, and returns an error code or a token.
- GenerateAuthenticationKey – By providing a control id and Encompass member id, this service will generate an authentication key that is valid for 15 minutes (can be adjusted by Encompass via request). To use this service, add &authkey=along with the value returned in the response from the web service to the URI for the form. Note that this link this only authenticates the user for the form itself, the entire site.
They can then hit this webmethod with their API key and password to post the information below.
The following information is posted to the webmethod:
- API key (string)
- API password (string)
- Constituent username (string)
- Constituent password (string)
- Group ID (integer)
Success will return the following example:
The token can be used to login to their site (substitute their domain):
http://imodgreen.imodules.com/controls/login/SsoProxy.ashx?Payload=v +1/x5SaNVyjWquWpt9xGErvijMTm5r5sjoxO/v2SK9VyuPQ6/apspqgz0gVTt5VCqjTxAeXoNG4C9rMMpG JKj3D+VpMAWDE
Failure will return the following example:
Login Query Error Codes
LDAP could not find the CN OR; LDAP service account credentials are invalid OR; LDAP does not permit anonymous binding OR; LDAP requires SSL for initial connect OR; LDAP does not support SSL for initial connect
|BindForAuthentication||101||LDAP invalid password for CN OR; LDAP requires SSL for authentication|
|NoEncompassMatch||102||Whatever they use for lookup (LDAP, CAS) there was no match in our database for the account on the authentication provider's end|
|NetworkError||103||Mapped ReturnCode in SsoStackProviderConfiguration.config OR; "Error calling graph." for OpenAuth||In the case of calling a third-party authentication and we timeout or 404|
|NotInGroup||108||[Login_No_Group_Access]||[[Community_Name]] token resolution supported!|
|NoResponseRedirect||111||[LOGIN_NO_REDIRECT]||This is for CAS from a WS call, for example|
|TokenNotSupported||112||"General SSSO configuration error"||Generic Simple Single Sign-on configuration problem|
|NoWsCmsOnlyAdmin||113||CMS-only administrators unsupported through WS|
|WsLatestSecurity||114||latest_security notification tailored for WS|
password_expires_soon notification tailored for WS
|OpenAuthAccessToken||119||"Error getting access token."|
|FacebookGraph||120||"Unable to access Facebook Graph."|
- InsertMemberMerge – Inserts a Member Merge mapping record that will be ran with the nightly MemberMergeTool run. This performs the backend merge of associated gift transactions, event registrations, etc. This does not include the fields updated in the Identity Checkpoint Member Merge grid. If an update of biographical fields is needed, this can be done via the GeneralQuery's Update method.
- GetAllEventContentTypes – Returns all Event Listing / Calendars for the site, regardless of community.
- GetAllEvents – Returns all Events for the site, regardless of community, specified by a given date range. Note that this has no dependence on a ControlId, which is a limitation of ControlQuery/GetControlSettings.
- GetCommunityEventContentTypes - Returns all Event Listing / Calendars for a specified community.
- GetCommunityEvents - Returns all Events for a specified community, specified by a given date range. Note that this has no dependence on a ControlId, which is a limitation of ControlQuery/GetControlSettings.
All web services share the following two required parameters:
- login – part of the credentials required to authenticate the request. This is provided by Encompass.
- password - part of the credentials required to authenticate the request. This is provided by Encompass.
What follows is a list of all remaining possible parameters. Many of these are shared between different methods.
- baseMemberId – Used in the MemberMergeQuery to specify the Encompass constituent identifier that another account will be merged into.
- categoryId – used by EmailCategoryQuery to specify the email category’s identifier
- communityId – Encompass sub-community or group identifier. Same as groupId
- controlId – specifies the form, event or campaign for the request. Applicable only for Control methods.
- columns – a comma-separated list of field names that will always be returned.
- changedColumns – a comma-separated list of field names that will be returned only when they have been changed within the specified timeframe.
- constituentId – the identifier of the user to return.
- constituentLogin – used in LoginQuery to pass the constituent’s primary login key (email, username)
- constituentPassword - used in LoginQuery to pass the constituent’s password
- changedFrom – the start date for the timeframe.
- changedTo – the end date for the timeframe.
- changeSince – the start date for the timeframe.
- endDate – the end date for the timeframe.
- filter – allows filtering of rows based on field name, operators and criteria (see Filters).
- groupId – Encompass sub-community or group identifier. Same as communityId
- includeNonMembers – specifies whether or not to include constituents records that are not marked as members of the community.
- includeBlankIds – specifies whether or not to include constituents records that do not have a constituent ID populated.
- includeFailedTransactions – include transactions that did not result in success
- includeTransactions – include the Transactions special element in the output (implicitly true for TransactionsQuery)
- includeTransactionDetails – include the TransactionItems special element in the output (ignored if includeTransactions is false)
- includeUnreviewed – specified whether or not to include constituent records that are pending a member or Identity Checkpoint merge
- keepChangedFrom – the start date for the timeframe of which to not overwrite updates that have been made online.
- keepChangedTo – the end date for the timeframe of which to not overwrite updates that have been made online.
- mergeMemberId – Used in MemberMergeQuery to specify the Encompass constituent identifier that will be merged into the “base” member id.
- memberInformation – a collection of information in XML format containing identifiers and fields (see MemberInformation in Parameters).
- memberId – Encompass unique identifier of the user. Used by many web services to get information, and also used to assign an external Constituent_ID to a non-member record in Encompass.
- startDate – the start date for the timeframe.
(General & Control Queries) Each record returned or updated in a Web Service request is represented by a MemberInformation element. The MemberInformation type contains additional attributes to distinguish updates made by the administrator. MemberInformation is the response type for the GetOneMember, GetMembersChangedDuring, and GetMembersChangedSince web service methods. It is also part of the request for the Update method.
The MemberInformation Element:
- May contain one or more Column elements representing the non-instance fields specified in the request or the non-instance columns to update.
- May contain one or more Instance elements.
- Will contain a Constituent_Id attribute containing the constituent ID (primary key).
- Will contain a Last_Updated attribute containing the date the constituent record was last updated if the record has been updated.
- This will only be excluded for the GetOneMember method. All other methods require that the constituent record has been updated in order to be included in the result.
- This attribute may be passed to the Update method, but will not be updated on the constituent record. It is effectively read-only.
- Will contain a Last_Updated_By_Constituent_Id attribute if the record has been updated.
- This attribute contains the constituent id of the constituent/administrator who made the update (if they have a constituent id).
- This attribute may be passed to the Update method, but will not be updated on the constituent record. It is effectively read-only.
- May contain a Last_Updated_By_Name attribute if the record has been updated.
- This attribute contains the full name (i.e. first name + ' ' + last name) of the constituent/ administrator who made the update (if they have a first and last name).
The following is a sample of an array of MemberInformation elements returned in a response:
*NOTE: The Encompass web services will return an empty string value as opposed to excluding the node for a column when the clearing of data occurs. Fields included in changedColumns will still be returned if updated and not returned if untouched in the online database for the specified time period. The example below shows a constituent that has cleared their "address_2" field:
- Will contain an Instance_ID containing the instance ID. The Instance_ID attribute is optional for the Update web service method (see External Row Identifier).
- May contain one or more Column elements representing the instance columns in the request or the instance columns to update.
- May contain one or more Transaction elements representing a commerce transaction.
- May contain a “Transaction_Id” attribute containing the transaction ID. If this attribute is missing and the IsSuccess attribute is “true”, then it was a transaction processed with Skip Billing.
- Will contain one IsSuccess attribute containing “True” or “False” to indicate if the transaction was successful or not.
- May contain one or more Column elements containing the transaction data.
- Will contain an “isReviewed” Boolean attribute, whose purpose is to let administrators know when records have gone thru the merge process to be pulled offline. See “Reviewed Attribute” for more information.
- Will contain a “transaction_last_updated” column, which is a datetime field initially set to the transaction “purchasedate.” This field will then be updated on various scenarios. See “Transaction last Updated Attribute” for more information.
- Will contain one Type attribute containing either "CommerceItem" or "CommerceAmount"
- Will contain one Transaction_Item_Id attribute containing the primary key of the commerce item or donation driver, prepended with 'Item-' or 'Amount-' respectively
- Will contain one or more Column elements containing the transaction item data.
- CommerceItems will contain a "total" and "quantity" column
- CommerceAmounts will contain a "total" column
- CommerceItems and CommerceAmounts will only return a "sku" column if the sku contains a real value
- Will contain a Name attribute containing the name of the field.
- Will contain a Value attribute containing the value of the field for the containing member or instance.
Gift Integration with Identity Checkpoint and Member Merge Systems
Enhancements have been made to the Encompass Web Services that are important to the success of gift integration. Recently, systems have been deployed to address the unauthenticated transactions in Encompass, which are also called non-member transactions. The Web Services were modified to support both the Encompass Non-Member Merge, a nightly process that coalesces non-member accounts, and the Encompass Identity Checkpoint system, an administrative tool that works to recognize constituent accounts on the front end (in the transaction form), suggest a match to the user, and then queue that transaction up for review by an administrator for association with the official constituent record.
Modifications have been completed to ensure that only “reviewed” transactions are returned (which are transactions that are not in limbo in the Non-member or Identity Checkpoint processes) in the Web Services and to also provide a new transaction date attribute or “transactionlastupdated” that marks when a transaction may have been updated by either of the two processes.
The main Web Services currently being used for gift exchange are the TransactionsQuery’s GetTransactionsAllBetween and GetTransactionsAllSince methods. Due to recent enhancements, no adjustments will need to be made to the parameters that are passed to these methods in order to receive “reviewed” records. This will be true for all rows returned by these methods. To get unreviewed transactions, you must call a separate method called “GetUnreviewsTransactionsAllBetween.”
This field will be set to TRUE when the following occurs:
1. Authenticated User - Is immediately set based on having a Constituent_ID
- Non-Member with Identity Checkpoint turned off
- Meets the following criteria:
- Identity Checkpoint is turned off
- Record has been through the Non-member merge process
2. Identity Checkpoint - Match made in the Member Merge Grid
- Has been through Non-member merge process
- Went to the Identity Checkpoint Member Merge grid for potential matching
- Match was approved by administrator
- Nightly Member Merge process has occurred
3. Identity Checkpoint - Non-Match made in the Member Merge Grid
- Has been through Non-member merge process
- Went to the Identity Checkpoint Member Merge grid for potential matching
- Match was declined by administrator
4. Identity Checkpoint - Non-Match (record never makes the Member Merge Grid based on match settings)
- Has been through Non-member merge process
- Did not make the Member Merge Grid (based on admin match settings)
Transaction Last Updated Element
In order to ensure that a record is not pulled prior to review, the GetTransactionsAllBetween and GetTransactionsAllSince date parameters of “startDate” and “endDate” now pull based on the new “transactionlastupdated” timestamp, not based on “purchasedate”. The “transactionlastupdated” is updated upon the different review/merge steps that occur during the Non-Member Merge and Identity Checkpoint systems and will ultimately reflect the time that the record was marked as IsReviewed=”true”. Initially set to the transaction "purchasedate," the “transactionlastupdated” field will then be updated in the following scenarios:
- Merge Tools
- For clients with Identity Checkpoint turned off, it will be updated to the current datetime at runtime of the Non-member Merge application to be included in changed records.
- For clients with Identity Checkpoint turned on, it will be updated to the current datetime when the following occurs:
- Records that are sent to the Identity Checkpoint Member Merge grid and APPROVED FOR MATCH are updated at runtime of the Identity Checkpoint Member Merge application to be included in changed records.
- Records that are sent to the Identity Checkpoint member merge grid and DECLINED FOR MATCH are updated at the time of the administrator Identity Checkpoint decline to be included in changed records.
- Records that are NOT SENT TO IDENTITY CHECKPOINT member merge grid based on administrator match settings are updated at time the application excludes the record from making the Identity Checkpoint Member Merge grid to be included in changed records.
- When the MemberMerge Web Service method is used (allows for external non-grid Identity Checkpoint Merge Requests, mentioned above).
Matched and Unmatched Records in Encompass
Records Matched in Encompass
Records with a constituent_id will have been authenticated or matched using Identity Checkpoint. These records should flow into your offline database without any further processes taking place (other than administrative review if necessary).
Records Unmatched in Encompass
There will continue to be transactions that come through that are not associated with a constituent account – the Identity Checkpoint process is not going to catch all of the potential constituent matches. In order to ensure that duplicates are not created in Encompass and if these records are ever expected to be part of the biographical sync from your offline database to Encompass , there are three (3) Non-Member scenarios to ensure success:
1. Match is found outside of Encompass and the Constituent_ID of the record exists in Encompass .
If a match is found outside of Encompass and the gift record is then assigned to a constituent record that is present in Encompass (a check should be done to confirm this), the Encompass MemberMerge Query should be used to apply the same behavior on the Encompass end. The MemberMerge Query requires the Encompass member_id of the official constituent record and the member_id of the non-member record. This API allows the gift associated with the non-member record to be moved under the official member record.
2. Match is found outside of Encompass and the Constituent_ID of the record does not exist in Encompass
So that duplicates are not created in Encompass, these records will need their Constituent_ID updated in Encompass with the value of the matched record in the offline database prior to the biographical sync taking place. Updates using the iMod_Member_ID as the primary key are now available in GeneralQuery’s Update method, including updating the record’s Constituent_ID value.
3. No match is found outside of Encompass and the record is to be added to the offline database These non- member records should be marked with a constituent code that indicates they are non-members from Encompass. Such records could be given an “Encompass Non-Member” constituent code and excluded from the regular biographical sync process from the offline database to Encompass.
(Same as Scenario 2) So that duplicates are not created in Encompass, these records will need their Constituent_ID updated in Encompass with the value of the matched record in the offline database prior to the biographical sync taking place. Updates using the iMod_Member_ID as the primary key are now available in GeneralQuery’s Update method, including updating the record’s Constituent_ID value.
In the event that an administrator decides that a non-member record in the offline database should now become an official constituent record that is synchronized with Encompass, one small adjustment should be made to make sure that this record is no longer considered a non-member in Encompass. A value of false for the “is_nonmember” field should be set for all records in the biographical sync going from the offline database to Encompass. While the constituent code would also be held in Encompass, the “is_nonmember” field handles the assignment of certain rights within the Encompass system.
Gift Transaction Flow Diagram
Some form types may contain embedded donations support (e.g. Events with Donations).
For the ControlQuery, if you are querying the Event, you get the event transaction (if applicable) with the linked information for the donation transaction (if applicable). Conversely, if you are querying the Campaign, you get the donation transaction (if applicable) with the linked information for the event transaction (if applicable). Similarly, the TransactionQuery that specifies the Event form by Control_Id (e.g. GetTransactionsByControl) you get the event transaction (if applicable) with the linked information for the donation transaction (if applicable). If you are calling a method that specifies the Campaign form by Control_Id (e.g. GetTransactionsByControl) you get the donation transaction (if applicable) with the linked information for the event transaction (if applicable).
For the TransactionQuery, if you are calling a method that does not specify the form (e.g. GetTransactionsAllSince) you get both transactions.
For the ControlQuery and the TransactionQuery in order to see the linked transaction information IncludeTransactionDetails must be TRUE.
The LinkedTransaction element will be added as a child node of the Transaction element. The syntax will be as follows:
The 'Amount' is the initial donation amount received from the linked transaction. For a recurring payment it would be the first payment amount. The Payment Type can be OT (One Time), RT(Recurring), or PT(Perpetual). The TotalScheduledAmount would be the total donation amount promised.
If there is no linked transaction, the TransactionID, Amount and ControlId will default to '0' and the ControlType and ControlName will default to blank.
A note about free tickets on Event forms
- If you have a $0 event with a donation, the Event Transaction Query will not show the linked donation transaction. This mirrors what we have in the reconciliation export.
- If you have a $0 event with a donation, the Event Control Query will not show the linked donation transaction.
- If you have a $0 event with a donation, the Campaign Transaction Query will not show the linked event transaction.
- If you have a $0 event with a donation, the Campaign Control Query will not show the linked event transaction.
The following is a sample of the AllColumnResults response. This applies to the GetAllColumns web service method.
Each field returned is represented by an AllColumnResults element.
- Will contain a Column attribute containing the name of the field.
- Will contain a Column_Info attribute containing the data type of the field.
- Will contain an Instance attribute indicating whether or not the field is an instance field.
The following is a sample of the AllControlResults response. This applies to the GetAllControls web service method.
Each control returned is represented by an AllControlResults element.
- Will contain a Control_Id attribute containing the ID of the control.
- Will contain a Control_Name attribute containing the name of the control.
- Will contain a Control_Type attribute containing the type of the control (either “form”, “event”, or “campaign”).
- Will contain a Group_Id attribute that shows the group (or sub-community) id associated with the control.
See the MemberInformation section under Parameters for information on this return type.
Transactions may be returned from the control query methods or the transactions query methods. When returned in from a control query method, the transactions will be inside the <Transactions> element of the <Instance> element. When returned from the transactions query methods you will receive an array of <Transaction> elements ordered by the last updated date of the transaction.
TransactionsQuery - Parameters and Response Entities
|string||36||n/a||Part of the credentials required to authenticate the request, provided by Encompass.|
|password||string||30||n/a||Part of the credentials required to authenticate the request, provided by Encompass. Unique ID that specifies the form, event, or campaign for the request. Applicable only for Control specific methods.|
|controlId||int||0||n/a||Unique ID that specifies the form, event, or campaign for the request. Applicable only for Control specific methods.|
|filter||string||n/a||n/a||Similar to SQL where clause, allows filtering of rows based on field name or Control_Type, operators and criteria|
Example - \"Homecoming Dinner\"
|Control_Id||int||0||Y||Unique ID that specifies the form, event, or campaign|
|Control_Type||string||8||Y||\"campaign\",\"event\", or \"form\"|
|Control_Name||string||500||Y||Example - \"Homecoming Dinner\"|
|authorizationcode||string||200||N||will match with processor|
OT - One Time transaction
|paymentfrequency||int||0||N||Number of payments per year. Can be: "1","2","4", or "12" (does not correspond with amount of payments left)|
The Encompass system provides clients the capability to deploy recurring billing in their Online Giving and Membership systems. In the Online Giving system, the options are for Scheduled Payments and / or Perpetual Payments:
Scheduled Payments - User selects to donate a certain amount, for example $1,000, and spread that donation out over a payment schedule with the first payment being now and the subsequent payments as selected by the user. If selected as quarterly, the user would submit and be charged an initial amount of $250, and then three subsequent quarterly amounts of $250 for the remaining $750. Encompass clients configure the options available to their members for Scheduled Payments.
Perpetual Payments - Users selects to donate a certain amount, for example $100, on a regular recurring base with no set end date. Encompass clients configure the available options for the perpetual scheduled. The user selects the amount they want to commit to, in this case $100, and determines the occurrence of the subsequent perpetual donation transactions They are then charged for the initial $100 amount, and then subsequently charged for the subsequent perpetual amount commitments. Each donation is for the same amount as the initial transaction.
If the PaymentType contains a Value of ‘RT’ (Recurring Transaction) or 'PT' (Perpetual Transaction instead of a Value of ‘OT’ (One-time Transaction), additional recurring billing fields will be returned.
Original Recurring Transaction (Control Query)
Subsequent Recurring Transactions (Control Query)
Subsequent recurring transactions are then available for retrieval (In our example above, 11 more transactions would take place in theory). After they occur, additional transactions will be available for return in the transactions node. In the Control Query, querying a date range that includes any of the transaction dates will return the entire record and all transactions that have been processed. Items in blue will be unique to that transaction.
Recurring Transactions (Transactions Query)
Subsequent Transaction ... one month later (Transactions Query)
TransactionItems may be returned from the control query methods or the transactions query methods. Any transaction items will be inside a <TransactionItems> element within each <Transaction> element.
Designations (Control & Transactions Queries)
A Designation interface is available for users to select from a large number (400+) of designation options for allocating their overall donation amount. Behind the scenes, administrators have the ability to assign and export custom IDs associated with each designation and to provide reporting output for integration with offline database systems.
Manage Designations Screen:
Adding/Editing a Designation Screen:
Some very old designation controls will display the designation info in a column underneath the instance (as in some of the examples above),
but for all recent designation controls, the Designations Element will always be contained by a Transaction Element.
This applies to both Control Query and Transactions Query:
- Contains the designations for this campaign that was submitted by the member.
- Will contain the ID attribute for holding the Encompass Designation ID.
- Will contain the Amount attribute for holding the amount that was allocated to this designation.
- Will contain the Text attribute for holding the Export Name of the designation.
- May contain the Value attribute for holding the percentage that was allocated for this designation.
- Percentage will only be available if the designations on the campaign are using the advanced display type.
- May contain the Ids element for holding the ID values assigned to this designation by the administrator.
- Holds the Ids for a designation.
- Will contain a Name attribute holding the name of the id. Name is configurable. The same ID Name cannot exist twice in the same designation.
- Will contain a Value attribute holding the value of the id. Value is configurable.
- Scheduled payment recurring transactions include a summary of the designations specified with the first transaction. For example, if the total gift amount is:
- given over 10 payments of $100.00 each
- designated to two designations for $500.00 each
- Perpetual giving recurring transaction include a summary of the designation for each transaction. For example, if the gift amount is:
- given every month
- designated to two designations for $50.00 each
- Scheduled payment recurring transactions include a summary of the designations specified with the first transaction. For example, if the total gift amount is:
Commerce ID Fields
Commerce ID Fields (or LedgerValues) allow for association of a Form, Event, or Campaign with a specific Commerce ID value(s) in a backend database or ERP systems by associating all transactions programmatically with their respective accounting code. Encompass staff will set up the Commerce IDs for the client, which will then be available via dropdown in the advanced options of the Commerce Form, Event or Campaign properties, as shown below. This capability provides clients the ability to direct transactions via the Encompass Reporting / Web Services capabilities to the respective ledger / revenue accounts in their backend systems. Clients are able to input and manage these Commerce IDs via the Form, Event and Campaign building / editing interface, with the Commerce IDs being output in all associated Encompass Reporting and Web Services.
Web Services LedgerValues output (example using Transaction Query):
The following is a sample of the UpdateResults response. This applies to the Update web service method.
Each member updated is represented by an UpdateMemberResult element.
*Note - When an email is updated via a web service update, the "is_email_valid" checkbox (Boolean field) is updated to True. If the update is made but the email address is the same, the "is_email_valid" flag will not be changed. The process currently occurs when using the batch .csv file import tool as well.
- Will contain a Constituent_Id attribute containing the constituent ID of the updated member
- Will contain an Is_New attribute indicating whether or not the member was added as a result of the request.
- May contain one or more UpdateMemberResult elements.
- May contain one or more UpdateColumnResult elements representing the non-instance fields updated.
- May also contain one or more UpdateInstanceResult elements representing the instances updated.
- Will contain an Instance_Id attribute containing the instance ID.
- May also contain an External_Id_Name and External_Id_Value attribute (see External Row Identifiers).
- May also contain one or more UpdateColumnResult elements representing the instance fields updated.
- Will contain a Name attribute which contains the name of the field.
- Will contain a Success attribute which indicates whether or not the field was successfully updated (see Error Syntax).
With regard to error syntax, there are two different types of web service methods in Encompass Web Service 2.0. All web service methods with the exception of Update will return a single error message in the response. Update may return an error message on each element that is being updated.
Single Error Response
The following is an example of a single error response from a web service method. An Error may be included as a child element of the ArrayOfAllControlResults, ArrayOfAllColumnResults, or ArrayOfAllControlResults elements.
- Will contain a Code attribute containing the error code.
- Will contain a Description element containing a description of the error that has occurred. The message will often contain additional information about the error (see Error Codes).
Update Error Response
The following is an example of an error response from an Update request. Error elements may be included as child elements of UpdateResults, UpdateMemberResult, UpdateColumnResult, or UpdateInstanceResult.
COLUMN, CONSITUENT ID, and VALUE are replaced with the relevant values.
In addition to the Query web services outlined above (web services with the “Query” suffix), there are Debug web services (web services with the “Debug” suffix) available to help debug an error code you don’t understand. Debug web services should be used when having problems with parameters or with accessing the correct method when using Query web services. These web services allow all parameters with simple types to be passed in as string values. These values are then converted to the appropriate type.
|2000||Adding constituents without a configured constituent ID column is not allowed.|
|2001||Web services are currently unavailable.||The availability of web services may limited, though they are always available under the current configuration.|
|2002||No rows were found.|
|2003||Invalid date order.|
|2004||The syntax for the specified filter was not valid.|
|2005||The specified credentials are not valid.||Encompass development team is notified when this error occurs.|
|2006||No administrative settings have been configured.||Encompass development team is notified when this error occurs.|
|2007||No data for updating has been defined.|
|2008||The member with constituent ID CONSTITUENT ID could not be found and adding new members set to false.||You can specify whether or not to allow member records to be added. This error is returned when adding members is not allowed and the specified member record is not found.|
|2009||No constituent ID is defined for the defined update data.|
|2010||No instance ID or external row ID is defined for the defined update data.|
|2011||The control ID specified does not exist.|
|2012||This control does not contain instance data.|
|2013||The member with member id ID could not be found and adding new members set to false.|
|2014||Updating constituent id would result in duplicates or duplicates already exist.|
|2015||Only use one of the following identifiers, CONSTITUENTIDFIELD or MEMBERIDFIELD.|
|2100||VALUE is not a valid boolean value.||Only applicable when using the Debug web services.|
|2101||VALUE is not a valid date value.||Only applicable when using the Debug web services.|
|2102||VALUE is not a valid decimal value.||Only applicable when using the Debug web services.|
|2103||VALUE is not a valid integer value.||Only applicable when using the Debug web services.|
|2104||VALUE is not a valid guid value.||This error is applicable for both Query and Debug web services as the login value is passed in as a string in both cases.|
|2105||VALUE is not a valid small integer value.||Only applicable when using the Debug web services.|
|2200||Error attempting to update the column COLUMN which is deleted.|
|2201||The column COLUMN was specified more than once.|
|2202||The column COLUMN was specified more than once.|
|2203||The column COLUMN is not valid.|
|2204||The value specified for column COLUMN exceeds the maximum length.|
|2205||The filter column COLUMN is not valid.|
No columns have been defined.
|No valid columns have been defined for the request.|
|2207||The column COLUMN already contains the specified update value.|
|2208||FIELD was updated online within the specified date range.||Just a warning.|
|2209||Membership data is not allowed when updating an instance.|
|2210||Membership cannot be updated because it has pending scheduled payments.|
|2211||Expiration date is required.|
|2212||Invalid membership level.|
|2213||Invalid membership purchase status.|
|2214||Lifetime memberships cannot have expiration dates.|
|2215||Lifetime Memberships cannot lapse.|
|2216||Membership level, purchase date, expiration date, and status are all required update a membership.|
|2217||Membership level, purchase date, expiration date, and status are all required update a membership.|
|2218||Membership was updated online within the specified date range.|
|2219||Membership cannot be shortened (via expiration date) when it has pending scheduled payments.|
|2220||Membership cannot be shortened (via expiration date) when set to auto renew.|
|2221||Only membership level, purchase date, expiration date, and status can be set via web services.|
|2222||Is registered is not a valid changed column|
|2223||The specified Membership Level is [disabled and is] not accepting new memberships.|
|2300||Error inserting new member with constituent ID CONSTITUENT ID.|
|2301||Error populating column data.|
|2302||General membership error.|
|2303||General membership error.|
|2400||General membership error.|
|2401||The limit of LIMIT concurrent connection has been exceeded.|
|2500||Could not find column FIELD.|
|2501||The member with constituent id CONSTITUENTID could not be found in the specified community|
|2502||The specificed community does not exist.|
|2600||The baseMemberId and mergeMemberId must be different.|
|2601||The baseMemberId is not valid.|
|2602||The mergeMemberId is not valid.|
|2603||The baseMemberId and mergeMemberId are already flagged to be merged.|
|2604||The baseMemberId is already flagged to be merged into another record.|
|2605||The mergeMemberId is already flagged to be merged into another record.|
|3000||Webservices feature is not enabled.|
|4000||The username could not be found in the system.|
|0||An unhandled exception occurred while processing the request. Please contact support for more information.|
The <Message> type will be used in place of the <Error> type when:
- Updating a field with the same exact value. (Success="true" will be returned as an attribute of • <UpdateColumnResult> when this occurs.)
- A field is not updated because of falling in the specified date range of the UpdateKeepChanged date • parameters.
Example of the XML that is returned:
Encompass recommends taking the following things into account when configuring your middleware:
Identify the maximum number of rows of data allowed to be sent (pushed) or received (pulled) in a single set. For example, if there were 5,000 rows of data being sent and the paging threshold was set to 1,000, then there would be 5 sets of data sent, each set containing 1,000 rows.
To accomplish a paging threshold when pulling data, first make a call where only the Constituent ID (client specific primary key) is requested in the “columns” parameter. This will return a list of IDs for all constituent records that have been updated over the specified date range. From here the filter feature can be used to pull back multiple record sets.
Recommend value: 500 constituent records
Web Service Timeout Limit
Identify the maximum allowable time between a request being sent and a response confirming the request was fulfilled.
Recommended value: 3 minutes
Company Web Services utilities are intended to provide bi-directional incremental data updates. This is especially true during peak hours. Because transactions through web services impact the same production database server used for the client’s web site, clients should avoid large web service requests during normal business hours from Monday through Friday from 8:00 AM – 5:00 PM Central Standard US time.
Further, Web Services may experience increased service timeouts or other interruptions from Midnight – 2:00 AM (nightly system back-ups) and 3:30 AM – 7:00 AM (daily batch services) Central Standard US time. We highly encourage designing a system where web services transactions are suspended during these two critical time frames and resumed outside of them. These times are subject to change by Company and will be communicated if adjusted.
Generally speaking, the Company web service handler will spend no more than 90 seconds attempting to complete a transaction. If the transaction cannot be handled within that time frame, the transaction may timeout. The Client’s system is free to retry the transaction following a timeout. As mentioned above, the likelihood of timeouts may increase during time periods discussed.
By default, the web services handler will allow one concurrent request as a guard against any one client saturating the database resulting in reduced service to all clients. As of January 2014, this no longer applies to LoginQuery requests.
Linking to Forms
Web service results can be used to create links to forms. This is accomplished by using some constant values and some data elements returned from web services. This works by using the Encompass content redirect resource. The format for the link is as follows:
The values you need to replace are:
[SITE_URL] - a constant value
[SITE_ID] - a constant value
[GROUP_ID] - a data element from web services results
[FORM_ID] - a data element from web services results