Answer: 

How to Query Organizations with Emails in netFORUM Enterprise xWeb with an Audience

This document explains how an xWeb integrator can return information about organizations and individuals through an Audience in the Fundraising module.

What is an Audience?

An Audience is a way to stack a collection of one or more netFORUM queries. The Audience acts as a Venn diagram assembler of queries. The results of the Audience may be the common intersection of two or more queries, or the sum of two or more queries, or the exclusion of any particular query. See Audience for more.
netFORUM xWeb contains web methods to get the list of Audiences in netFORUM, to get the schema of a particular Audience in order to determine any ask-at-runtime parameters of any of the component queries, and to get the results of an Audience.

What is a Constituent?

A fundraising constituent is an actual donor, or a prospect donor. A fundraising constituent can also be an individual, organization, or household.  Be aware that while every fundraising constituent must also be an individual, organization or household, the converse is true: not every individual, organization or household is guaranteed to be a constituent in every netFORUM instance.  netFORUM will create a constituent whenever one of these three customers types makes a donation. There is a netFORUM system option called CreateConstituentOnIndOrOrgAdd​. If this system option is true, then netFORUM automatically creates a constituent for every individual or organization. Most netFORUM customers who are primarily fundraising organizations have this system option set to true.

Requirements and Prerequisites

  • Requires netFORUM client to be running netFORUM 2014.1 or later in order to use the GetAudience web methods which were released in netFORUM 2014.1.
  • Assumes that any individuals and organizations you want to query exist as Constituents in the Fundraising module

Fundraising Constituent Query

Create a query in Fundraising Constituent group item.  Include any necessary columns in the Query Conditions and Columns.
Sample Query Name: “Constituents (any customer type) with a donation greater than $5000”

Query Conditions


Depending on the capabilities of the integrating application, you might be able to include ask-at-runtime parameters, such as the example of Address:State/Territory query condition illustrated above.

Query Columns

Warnings

Take care NOT to select any columns from Individual, as doing so will implicitly filter out Organizations (and vice versa). Include only columns and conditions that apply to any customer type (individual, organization, chapter, household).


Fundraising Constituent Audience

Next, create an Audience in the Fundraising Constituent group item and include this query. You may include other Fundraising Constituent queries as well.

xWeb GetAudience Web Methods

In xWeb, this Audience will appear in the GetAudienceList web method, and you can get the schema of the particular Audience with the GetAudienceDefinition method, and and you will be able to get the results of the Audience by calling GetAudience.

Sample GetAudience Request

Note the ask-at-runtime parameter node. The parameter name (a guid value) can be determined from the GetAudienceDefinition web method.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.avectra.com/2005/">
  <soapenv:Header>
    <ns:AuthorizationToken>
      <ns:Token>********************</ns:Token>
    </ns:AuthorizationToken>
  </soapenv:Header>
  <soapenv:Body>
    <ns:GetAudience>
      <ns:qrh_key>a4579f5e-fbd1-4070-af6b-47e5a16369ee</ns:qrh_key>
      <ns:Parameters>
        <!-- ask-at-runtime parameter for Address::State/Territory: -->
        <ns:Parameter>
          <ns:Name>4611bfb8-29da-48ef-8246-76c8f9762428_1</ns:Name>
          <ns:Value>VA</ns:Value>
        </ns:Parameter>
      </ns:Parameters>
    </ns:GetAudience>
  </soapenv:Body>
</soapenv:Envelope>

Sample GetAudience Response

Observe that there are a variety of customer types as shown in the <cst_type> element, but each type has an email address (cst_eml_address_dn) and a Customer Key (dnr_cst_key).
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <AuthorizationToken xmlns="http://www.avectra.com/2005/">
      <Token>****************************</Token>
    </AuthorizationToken>
  </soap:Header>
  <soap:Body>
    <GetAudienceResponse xmlns="http://www.avectra.com/2005/">
      <GetAudienceResult>
        <Results recordReturn="33">
          <Result>
            <dnr_cst_key>a06eeb66-bcd5-400d-982d-c172bbf08000</dnr_cst_key>
            <cst_eml_address_dn>tbadfutcher@avectra.com</cst_eml_address_dn>
            <cst_id>000088577I</cst_id>
            <cst_type>Individual</cst_type>
            <cst_name_cp>Ms Tammy Jones</cst_name_cp>
            <adr_city_state_code>Centreville, VA  20120</adr_city_state_code>
          </Result>
          <Result>
            <dnr_cst_key>0876ff61-d036-4e07-bfd6-9a5af25a1de1</dnr_cst_key>
            <cst_eml_address_dn>sprint11-2@test2.com</cst_eml_address_dn>
            <cst_id>000134216I</cst_id>
            <cst_type>Individual</cst_type>
            <cst_name_cp>Mr Bob Individual</cst_name_cp>
            <adr_city_state_code>state, VA  13245</adr_city_state_code>
          </Result>
          <Result>
            <dnr_cst_key>5172d67a-d465-4273-88fd-2e1aa61de023</dnr_cst_key>
            <cst_eml_address_dn>williamsfoundation@cox.com</cst_eml_address_dn>
            <cst_id>000088494O</cst_id>
            <cst_type>Organization</cst_type>
            <cst_name_cp>The Williams Foundation</cst_name_cp>
            <adr_city_state_code>vienna, VA  22102</adr_city_state_code>
          </Result>
          <Result>
            <dnr_cst_key>fd224551-30cf-411e-966a-f2e3888714a9</dnr_cst_key>
            <cst_eml_address_dn>smiths@cox.com</cst_eml_address_dn>
            <cst_eml_address_dn/>
            <cst_id>000088300I</cst_id>
            <cst_type>Household</cst_type>
            <cst_name_cp>The Smith Family</cst_name_cp>
            <adr_city_state_code>Arlington, VA  22102</adr_city_state_code>
          </Result>
          <Result>
            <dnr_cst_key>fd224551-30cf-411e-966a-f2e3888714a9</dnr_cst_key>
            <cst_eml_address_dn>smiths@cox.com</cst_eml_address_dn>
            <cst_eml_address_dn/>
            <cst_id>000028500I</cst_id>
            <cst_type>Chapter/Affiliate</cst_type>
            <cst_name_cp>The Arlington Chapter</cst_name_cp>
            <adr_city_state_code>Arlington, VA  22102</adr_city_state_code>
          </Result>
        </Results>
      </GetAudienceResult>
    </GetAudienceResponse>
  </soap:Body>
</soap:Envelope>
 

Next Steps in xWeb

Based on the results of the GetAudience, you can use the Customer Key property (dnr_cst_key) to retrieve more information about each constituent. If you need to retrieve information specifically about an individual or an organization, then you may need a combination of separate queries into each Object type using GetQuery and specifying different object names (Organization, Individual, etc.).

FAQ


Q. Can you create an Audience with Organization queries?

A. No. The Audience is available for Individuals, Household and Constituents. The focus on this article is how to use the Constituent Audience as a backdoor way of querying organizations, given the caveat that depending on the netFORUM instance, not every organization will necessarily be a constituent as well.

Required Tags:

Article Type: 
Product Info
Product Line: 
netFORUM Enterprise
Product Module/Feature: 
-None-
Product Version: 
2014.1
Ranking: 
0
No votes yet