Data Exchange 2 - Fellowship Onedeveloper.fellowshipone.com/downloads/Data_Exchange_2_0.pdf · 1...

Data Exchange 2.0

iii

Table Of Contents Getting Started .................................................................................................................. 1

Fellowship One Data Exchange Overview ........................................................................... 1

Getting Started Tasks ...................................................................................................... 1

Data conversion........................................................................................................... 1

Fellowship One login credentials .................................................................................... 1

Encrypted church code ................................................................................................. 3

Exporting the schemas ................................................................................................. 3

Method groups ............................................................................................................... 5

Method versions ............................................................................................................. 6

Accessing Data Exchange................................................................................................. 7

Security ......................................................................................................................... 7

XML document creation ................................................................................................ 7

XML validation ............................................................................................................. 7

Authentication header .................................................................................................. 8

Method Construct by authentication ............................................................................... 8

Quick Start ..................................................................................................................... 9

Small Group Leader WebLink accounts ......................................................................... 12

Exporting People .............................................................................................................. 17

Method constructs......................................................................................................... 17

Query comparison operators .......................................................................................... 18

Record limits ................................................................................................................ 20

Authentication header ................................................................................................... 21

Excluding information in the result set ............................................................................. 22

GetIndividual ................................................................................................................ 22

Building GetIndividual ................................................................................................ 23

Example: Individual Code ........................................................................................... 23

Example: Individual Source Code ................................................................................. 24

Example: WebLink ID and Password ............................................................................ 24

GetIndividualCollection .................................................................................................. 25

GetIndividualCollection parameters .............................................................................. 25

Building GetIndividualCollection ................................................................................... 31

Example: Individual Attributes ..................................................................................... 31

Example: First Record Date ......................................................................................... 32

Example: Last Name .................................................................................................. 32

Data Exchange 2.0

iv

Example: List of individuals ......................................................................................... 32

GetHousehold ............................................................................................................... 33

GetHousehold parameters........................................................................................... 33

Building GetHousehold ............................................................................................... 34

Example: Encrypted Household Code ........................................................................... 34

Example: Household Source Code (legacy CMS) ............................................................ 35

GetHouseholdCollection ................................................................................................. 35

GetHouseholdCollection parameters ............................................................................. 36

Building GetHouseholdCollection .................................................................................. 38

Example: Last Activity Date ......................................................................................... 39

Example: Last Name (Households)............................................................................... 39

Example: Household First Name .................................................................................. 40

Running the export ....................................................................................................... 40

Data Export through Fellowship One ............................................................................... 42

Data Exchange People Exports .................................................................................... 45

Importing Data ................................................................................................................ 46

Method constructs......................................................................................................... 46

Setting the entityState ................................................................................................... 47

Null fields ..................................................................................................................... 47

Import rules ................................................................................................................. 48

Import results............................................................................................................... 48

Authentication header ................................................................................................... 50

Synchronous processing ................................................................................................ 50

UpdateIndividual ........................................................................................................... 52

Building UpdateIndividual ........................................................................................... 56

UpdateIndividualCollection ............................................................................................. 58

Building UpdateIndividualCollection ................................................................................. 58

UpdateHousehold.......................................................................................................... 60

Building UpdateHousehold .......................................................................................... 61

UpdateHouseholdCollection ............................................................................................ 64

Building UpdateHouseholdCollection............................................................................. 64

Running Data Import ..................................................................................................... 69

Data Import through Fellowship One ............................................................................... 71

Data Exchange Import Grid ............................................................................................ 73

Util Methods .................................................................................................................... 75

GetSchema .................................................................................................................. 75

Table Of Contents

v

GetRequestStatus ......................................................................................................... 75

1

Getting Started

Fellowship One Data Exchange Overview

Fellowship One Data Exchange allows you to import data to and export data from Fellowship One™. The format for data exchange is Extensible Markup Language (XML), which is platform independent and easy to manipulate. The only tools needed are a text editor such as Notepad

and Internet access.

Note: Depending upon how you choose to access Data Exchange, a Fellowship One user ID and

password with rights to Data Exchange are also required. If you choose to access Data Exchange using the Fellowship One interface, the user ID must have Admin security authorization.

Data Exchange allows you to pull information from Fellowship One, manipulate the results in any way necessary and then push the changes back to Fellowship One. Its intent is twofold; to synchronize separate databases (associated with a web site or software program) with Fellowship

One and to provide a tool for mass updates to data.

Getting Started Tasks

A few manual database tasks must be completed prior to using Data Exchange successfully. Gather the following information:

• Data for conversion (if you have not already had your data converted into Fellowship One from your current church management software or database)

• External IP address

• Login credentials (Admin and Data Exchange access needed to use the Data Exchange tool within Fellowship One)

• Encrypted church code for authentication

Data conversion

If your church’s data has not already been converted into Fellowship One, it must be converted before you can go any further with Data Exchange. When your data is converted, the individual and household IDs for your data are inserted into Fellowship One.

Contact your Fellowship Technologies implementation manager or Support Services directly at

866-383-2437 to get started.

Fellowship One login credentials

If Data Exchange is accessed programmatically or via the ASMX web service, the XML string

requires a Fellowship One user ID and password. This user ID must have the Data Exchange security authorization.

Tip!

Some administrators will create a user name/password specifically for Data Exchange especially when it is being accessed programmatically or via the ASMX web service. This practice will allow administrators to differentiate between the data exchange updates done via a program and

those done through the Fellowship One user interface. See an example of this below.

Data Exchange 2.0

2

In the People Import grid below, administrators can see exactly which methods were run through Data Exchange, the time the method was run, and the user name associated with that record.

Accessing Data Exchange through the Fellowship One interface requires a Fellowship One user ID and password with Admin and Data Exchange security authorizations.

Getting Started

3

Encrypted church code

In order for Fellowship One to properly authenticate, the XML string must have your encrypted

church code in its header. Use the following procedure to get this information.

Note: A Fellowship One user with WebLink security authorization is required to perform the following

procedure.

To find the encrypted church code

1. Sign into Fellowship One and click the WebLink tab.

2. Click the Web Integration and Integration Code menu options on the left side of the browser window. The Integration Code Lookup tool appears.

3. Use your mouse to highlight the string in the Church Code field. Right-click and select Copy or use the Ctrl/Command + C keyboard shortcut to copy the information.

4. Paste (Ctrl/Command + V) the encrypted church code into a text editor such as Notepad and save for later use.

Note:

It’s best to use a text editor such as Notepad for saving this information. Desktop publishing software, such as Microsoft Word, reformats text you enter according to spelling errors or grammar rules, which can invalidate your encrypted church code.

Exporting the schemas

Before you begin writing your export and import requests, take a moment to export each of the schemas for the available methods. The schema shows you the exact parameters that can be

used to update records in your XML strings as well as which parameters are required.

Note:

The order in which the parameters appear in the schema is particularly important. Ensure that you do not accidentally shuffle the order of parameters. The Get and Update methods will fail if the parameters are not in the correct order.

To get the schemas, create an XML file as shown below. Change the method to reflect the

schema you need to retrieve. The methods are GetIndividual, GetIndividualCollection, GetHousehold, GetHouseholdCollection (these schemas are available in People Export (step 2 in the procedure below)) , UpdateIndividual, UpdateIndividualCollection, UpdateHousehold, and

UpdateHouseholdCollection (these schemas are available in People Import (step 2 in the procedure below).

Data Exchange 2.0

4

<?xml version="1.0" encoding="UTF-8"?>

<tns:dataRequest xmlns:tns="GetSchema">

<authenticateHeader>

<churchCode>INSERT ENCRYPTED CHURCH CODE</churchCode>

<user>INSERT USER ID</user>

<password>INSERT PASSWORD</password>

<method>GetSchema</method>

<version>1.0</version>

<methodGroup>Util</methodGroup>

</authenticateHeader>

<parameters>

<methodName>INSERT METHOD(Example: UpdateHousehold)</methodName>

</parameters>

</tns:dataRequest>

Note: The version number remains 1.0. Do not update the <version> node at this time.

The following procedure explains how to get the schemas from Fellowship One.

To get the schemas

1. Sign into Fellowship One and click the Admin tab.

2. Click the Data Exchange and People Import (or People Export) menu options on the

left side of Fellowship One. The Import People page appears.

Click here to see the People Import interface

3. Click the Browse button. The Choose File dialog box appears.

Getting Started

5

4. Browse to your GetSchema XML file, select it, and click Open. The file path and name appears in the Import People field.

5. Click Run Import. The schema appears in a new Internet browser window.

Each schema contains the parameters that can be used to update records for the method that matches the schema: individual, individual collections, a household, or household collections.

Method groups

In preparation for the future of Data Exchange, Fellowship Technologies has begun grouping methods in two categories—People and Util. The methodGroup node must appear in each method request. For example, when using the GetHouseholdCollection method, the method

group entry would appear as shown below:




<churchCode>ENCRYPTED CHURCH CODE</churchCode>

<user>USER ID</user>

<password>PASSWORD</password>

<method>GethouseholdCollection</method>


<methodGroup>People</methodGroup>


Each method groups contain the following methods:

• People

• GetHousehold(v1.0, v2.0)

• GetHouseholdCollection(v1.0, v2.0)

• GetIndividual(v1.0, v2.0)

• GetIndividualCollection(v1.0, v2.0)

Data Exchange 2.0

6

• UpdateHousehold(v1.0, v2.0)

• UpdateHouseholdCollection(v1.0, v2.0)

• UpdateIndividual(v1.0, v2.0)

• UpdateIndividualCollection(v1.0, v2.0)

• Util

• GetSchema

• GetRequestStatus

Method versions

Fellowship Technologies is committed to moving forward with Data Exchange; however, as new versions of each method are released full support will still be available for previous versions. This means that new releases will have no impact on any programs you have developed against

earlier versions of Data Exchange methods.

The method node can contain either 1.0 or 2.0 as shown in the code below.







<method>GethouseholdCollection</method>




The Data Exchange interface in Fellowship One has been enhanced to record not just the method requested, but the version of the method as well. The image below shows the People Export grid. Notice that the version requested appears after the method name.

Getting Started

7

Accessing Data Exchange

There are multiple ways to access the Import and Export features of Data Exchange.

1. Consume the Data Exchange Web service programmatically.

a. Use any programming language that allows string transport over HTTPS.

b. Send a string of XML to the web service. The string must contain the Authentication Header and the parameters that match the method being

accessed.

2. Directly through the ASMX web service by sending a string of XML through the Web service’s exposed Web interface:

https://services.fellowshipone.com/DataExchange/v1/DataRequest.asmx?op=Request

3. Upload a file through the Data Exchange interface in Fellowship One.

a. Create an XML file that contains an Authentication Header and parameters.

b. Upload the file through the Data Exchange menu option on the Admin tab in Fellowship One.

c. For Data Export, a job is scheduled and when completed, results are posted back in an XML file containing the results of the parameters in your query. For Data

Import, a Save file dialog box appears to save the XML file generated from the query.

Note:

For Data Import, the XML file’s status remains “In Queue” until the scheduled job is processed.

Security

There are five layers of security within Data Exchange: XML document creation, XML validation, Authentication Header, and Method Construct by authentication. The layers are explained in the following sections.

XML document creation

When Data Exchange begins to create an XML document from an incoming XML string, it checks the validity of the XML string. The string sent into Data Exchange always resolves to XML. If the XML document cannot be generated the process fails.

XML validation

Data Exchange checks the Authentication Header and checks to see if a parameters collection exists. If the XML sent into Data Exchange does not match the XML Schema Definition (XSD) for

the Namespace provided then validation fails.

Note: The parameters collection can be empty; however, this will be rare.

Data Exchange 2.0

8

Authentication header

The Authentication Header drives authentication and provides the structure expected in the string by stating the method to run. The header is checked redundantly and if satisfactory, an

Authentication Header node is created.

The number of nodes in the collection are checked. There should always be six (6) or more: Encrypted Church Code, User, Password, Method, Version, and Method Group. Next, an attempt

is made to decode the encrypted church code.

If everything passes, the Authentication Header values are stored in an Authentication Header entity.

Method Construct by authentication

A Method Construct is created only if the credentials provided are successfully authenticated; otherwise, the method returns an error message advising that the authentication failed. Credentials include the following:

• Encrypted church code

• User ID

• Password

• Method

• Version

• Method Group

Getting Started

9

Quick Start

For those too impatient to read all the documentation, the following is a quick list of steps to export and import your first data exchange transactions.

1. Ensure you have read and completed all Getting Started Tasks beginning on page 1. These are essential especially if Data Exchange is being accessed via an external program.

2. Construct your export method. In this example, let's find all people who were entered via the Fellowship One Check-in kiosks. Once all the people have been located, you can update the records to a more meaningful status like "Visitor" or "Event Prospect".

Note: Always perform an export first. Never try to import updates without first exporting. This ensures the latest information is captured in the export and essential data is not

accidentally updated. The exception to this rule is when you are adding new households/individuals via Data Exchange.

a. Create the authentication header with your user name, password, and encrypted church code.

b. Use the GetIndividualCollection method to find all individuals that were new from Check-in. You could also use the GetHouseholdCollection method for this export. The version node should display 2.0 and the method group is "People".

c. Determine how many pages and records to pull back in this export. The limit is 250 records per page. See Record limits on page 20 for more information.

d. Use the status parameter to find all people with "New Checkin" status.

The export will appear as follows:


<tns:dataRequest xmlns:tns="GetIndividualCollection">



<user>USER NAME</user>


<method>GetIndividualCollection</method>




<parameters>

<configuration>

<page>1</page>

<numberOfRecords>50</numberOfRecords>

</configuration>

<status>New Checkin</status>

</parameters>

</tns:dataRequest>

3. Click Data Exchange and People Export in the menu options on the Admin tab to

display the Data Exchange People Exports interface. Click Browse to locate your XML file. Select the file and click Run Export to upload it. The requested export will launch in

a new browser window. Save this file. 4. Open the file in an XML editor. It's time to update the statuses to something more

meaningful like "Event Prospect".

Data Exchange 2.0

10

Note: The results that appear from People Export are not formatted properly for an Import

action. The file must be edited prior to uploading.

a. Create the authentication header with your user name, password, and encrypted church.

b. Use the UpdateIndividualCollection method to update all records with the new status. This entails finding all "UnChanged" entity states and changing them to "Modified" as well as finding all "New Checkin" statuses and changing them to

"Event Prospect".

c. Additional information like addresses, household member types, gender, and marital status can also be modified in this example. Check-in does not allow for much data entry as its main purpose is to quickly get people assigned to a room

and to keep the line moving. Data Exchange along with a programmed interface can help quickly update these records.

Note:

The best way to perform import actions is via some kind of program that can automatically do something with the data such as change the marital status to "Child/Yth" if the individual is less than 18 years old, remove “Mr.” or “Miss” in the "title" field for children,

and so on.

The import will appear as follows:

<?xml version='1.0' encoding='UTF-8'?>

<tns:dataRequest xmlns:tns='UpdateIndividualCollection'>





<method>UpdateIndividualCollection</method>


<methodGroup>People</methodGroup)


<data>

<individuals>

<individual entityState="Modified" individualSourceCode=""

individualCode="h/20hJ0h23NUzJHIPxsJvw==">

<title />

<salutation />

<prefix />

<firstName>Cameron</firstName>

<lastName>Morton</lastName>

<suffix />

<middleName />

<goesByName />

<formerName />

<gender />

<dateOfBirth>2000-12-29T00:00:00</dateOfBirth>

<maritalStatus />

<householdMemberType>Visitor</householdMemberType>

<occupation />

<occupationDescription />

<employer />

<school />

<formerChurch />

<status>Visitor</status>

<statusDate>2006-01-12T10:45:44</statusDate>

<statusComment />

<barCode />

Getting Started

11

<memberEnvelopeCode />

<defaultTagComment />

<solicit />

<thank>true</thank>

<firstRecord>2006-01-12T10:45:44</firstRecord>

<lastMatchDate />

<createdDate>2006-01-12T10:45:44</createdDate>

<lastUpdatedDate>2006-01-12T10:45:44</lastUpdatedDate>

<weblink entityState="UnChanged">

<userId />

<password />

<passwordHint />

<passwordAnswer />

</weblink>

<attributes />

<addresses />

<communications />

</individual>


individualCode="T+QiPxjm2W4w0fKJbCDfjg==">

<title />

<salutation />

<prefix />

<firstName>Jane</firstName>

<lastName>Smith</lastName>

<suffix />

<middleName />

<goesByName />

<formerName />

<gender />

<dateOfBirth />

<maritalStatus />

<householdMemberType>Head</householdMemberType>

<occupation />


<employer />

<school />

<formerChurch />

<status>Visitor</status>

<statusDate />

<statusComment />

<barCode />



<solicit />

<thank>true</thank>


<lastMatchDate>2006-01-05T17:03:00</lastMatchDate>




<userId />

<password />

<passwordHint />

<passwordAnswer />

</weblink>

<attributes />

<addresses />

<communications />

</individual>

</individuals>

</data>

</tns:dataRequest>

Data Exchange 2.0

12

5. Click Data Exchange and People Import on the Admin tab to display the Data Exchange People Import grid. Click Browse to locate and select your XML file. Click Run

Import. A new browser window opens and displays a message regarding the formatting of the XML file. If the authentication header is present and the remainder of the file is properly formatted, the file is uploaded.

6. Click Refresh on the Data Exchange People Import grid until the status changes to Complete.

7. Type the partial name of one of the individuals that was just updated in the People Search field and click Go. Click on his or her name in the search results to view the

individual record. Look to see that all of the modified fields were updated correctly.

You have just completed your first Data Exchange project! Check out Small Group Leader WebLink accounts below for more data exchange ideas.

Small Group Leader WebLink accounts

Are you planning to implement Fellowship One WebLink™ for your Small Groups ministry? If so, the task for creating a web site user account for small group leaders and directors can be done through Data Exchange.

Note: Data Exchange does not include support for Participant and Staffing Assignments at this time.

Look for this feature in a future release of Data Exchange. In this example, all small group leaders and directors had been assigned an individual attribute—either small group leader or small group director.

The benefit of using Data Exchange to create web site accounts is that you can eliminate the

need for finding and matching duplicate records that are created when a new account is created through the church web site. When you have your initial kick-off meeting to introduce your small group leaders to WebLink, their account information will be created and they will be able to sign

in immediately.

1. Ensure you have read and completed all Getting Started Tasks beginning on page 1. These are essential especially if Data Exchange is being accessed via an external program.

2. Construct your export method.

a. Create the GetIndividualCollection authentication header with your user name, password, and encrypted church code.

b. Use the method to find all individuals who have the individual attribute "Small Group Leader" or "Small Group Director". To find this group, use the attributeGroupName element.

c. Determine how many pages and records to pull back in this export. The limit is 250 records per page. See Record limits on page 20 for more information.

d. Use the attributeGroupName parameter to find all people who have either the “Small Group Leader” or “Small Group Director” individual attributes.

The export will appear as follows:


<tns:dataRequest xmlns:tns="GetHouseholdCollection">




Getting Started

13


<method>GetHouseholdCollection</method>




<parameters>

<configuration>

<page>1</page>


</configuration>

<attribute>

<attributeGroupName>Small Groups</attributeGroupName>

</attribute>

</parameters>

</tns:dataRequest>

3. Click Data Exchange and People Export in the menu options on the Admin tab to

display the Data Exchange People Exports interface. Click Browse to locate your XML file. Select the file and click Run Export to upload it. The requested export will launch in a new browser window. Save this file.

4. Open the file in an XML editor. It's time to update the WebLink user account information.

Note: The results that appear from People Export are not formatted properly for an Import action. The file must be edited prior to uploading.

a. Create the authentication header with your user name, password, and encrypted church.

b. Use the UpdateIndividualCollection method to update all records with the new status. This entails finding all "UnChanged" entity states for each individual and changing them to "Modified" as well as updating the "WebLink" node and adding a user name and password.

Note:

Take care when finding/replacing entity states. The "UnChanged" state appears for an individual's information and also for communication and address values. Make sure you do

not modify something accidentally.

c. Additional information like addresses, household member types, gender, and marital status can also be modified in this example.

Note:

The best way to perform import actions is via some kind of program that can automatically do something with the data such as change the marital status to "Child/Yth" if the

individual is less than 18 years old.

The import will appear as follows (download the example file here):


<tns:dataRequest xmlns:tns='UpdateIndividualCollection'>









<data>

<individuals>

Data Exchange 2.0

14

<individual entityState="Modified"

individualSourceCode="1319956"

individualCode="iHt+K34BKhXt89egwqpOSg==">

<title />

<salutation />

<prefix>Mr.</prefix>

<firstName>Art</firstName>

<lastName>Baker</lastName>

<suffix />

<middleName />

<goesByName />

<formerName />

<gender>Male</gender>


<maritalStatus>Married</maritalStatus>


<occupation>Sales</occupation>

<occupationDescription>Sales</occupationDescription>

<employer>Phillips Sales</employer>

<school />

<formerChurch />

<status>Member</status>


<statusComment />

<barCode />



<solicit />

<thank>true</thank>


<lastMatchDate />

<createdDate />

<lastUpdatedDate>2004-03-

14T13:27:21</lastUpdatedDate>

<weblink entityState="Modified">

<userId>artbaker</userId>

<password>artbaker</password>

<passwordHint />

<passwordAnswer />

</weblink>

<attributes />

<addresses />

<communications />

</individual>



individualCode="mYmGhCbbh6VPb3fO+PlewA==">

<title />

<salutation />

<prefix>Mrs.</prefix>

<firstName>Dorothy</firstName>

<lastName>Benton</lastName>

<suffix />

<middleName />

<goesByName />

<formerName />

<gender>Female</gender>



<householdMemberType>Spouse</householdMemberType>

<occupation />

<occupationDescription>Stenographer</occupationDescr

iption>

Getting Started

15

<employer>Dallas County</employer>

<school />

<formerChurch>1st AoG Chandler TX</formerChurch>



<statusComment />

<barCode />



<solicit />

<thank>true</thank>


<lastMatchDate />

<createdDate />




<userId>dorothybenton</userId>

<password>dorothybenton</password>

<passwordHint />

<passwordAnswer />

</weblink>

<attributes />

<addresses />

<communications />

</individual>



individualCode="XuXkPVtLrIWRruk5M0eALw==">

<title />

<salutation />


<firstName>Hal</firstName>


<suffix />

<middleName />

<goesByName />

<formerName />





<occupation />


<employer />

<school />

<formerChurch />



<statusComment />

<barCode />



<solicit />

<thank>true</thank>


<lastMatchDate />

<createdDate />




<userId>halbenton</userId>

<password>halbenton</password>

Data Exchange 2.0

16

<passwordHint />

<passwordAnswer />

</weblink>

<attributes />

<addresses />

<communications />

</individual>

</individuals>

</data>

</tns:dataRequest>

5. Click Data Exchange and People Import on the Admin tab to display the Data Exchange People Import grid. Click Browse to locate and select your XML file. Click Run Import. A new browser window opens and displays a message regarding the formatting

of the XML file. If the authentication header is present and the remainder of the file is properly formatted, the file is uploaded.

6. Click Refresh on the Data Exchange People Import grid until the status changes to Complete.

7. Type the partial name of one of the individuals that was just updated in the People Search field and click Go. Click on his or her name in the search results to view the individual record. Click the Basic tab and check to see if the Web User ID field contains

the user name created for this individual.

You have just completed a Data Exchange project!

17

Exporting People

People Export allows you to retrieve records from Fellowship One. Through People Export, the following items can be exported:

• Single individuals

• Individual collections

• Single households and every individual within the household

• Household collections and every individual within each household

The export includes individual information, address and communication values for both individuals and households. Individual attributes, Fellowship One WebLink™ account information, merge history (individualHistory) and contribution "Thank" information is also returned with individuals. For household collections every individual associated with the households that meet

the query parameters is also returned.

The data exported depends upon the parameters you include within your XML string. Accepted parameters are described within the specific method topics as follows:

• GetIndividual

• GetIndividualCollection

• GetHousehold

• GetHouseholdCollection

Method constructs

XML strings contain methods to determine the results to be returned. There are four methods that return single results or a collection of results based on the method. The following table displays the methods and a description of what the method returns.

Method Constructs

Method Description

GetIndividual Query the database for a specific individual by individualCode, individualSourceCode, or WebLink user ID/password. The individual that matches your query is returned.

GetIndividualCollection Query the database for a collection of individuals that match the

parameters you supply in your query. Query by any piece of Basic information, contribution "Thank" settings, Individual Attributes, WebLink userID/password, address, or communication values. All

individual records matching your request are returned.

GetHousehold Query the database for a specific household by householdCode, hosueholdSourceCode, individualCode, individualSourceCode, or WebLink userID/password. The household that matches your query is returned.

Data Exchange 2.0

18

Method Description

GetHouseholdCollection Query the database for a collection of households that match the parameters you supply in your query. Query by household name, first created date, last updated date, address, or communication

values. All households matching your request are returned.

Query comparison operators

When creating Export queries, several operators can be used to obtain the information requested. The following table displays the operators and where they can be used.

Query Comparison Operators

Operator Data Exchange Name Usable On

= EqualTo All fields (excluding ID fields)

> GreaterThan DateTime, numeric

< LessThan DateTime, numeric

>= GreaterThanOrEqualTo DateTime, numeric

<= LessThanOrEqualTo DateTime, numeric

<> NotEqualTo All fields (excluding ID fields)

BETWEEN Between DateTime, numeric

IS NOT NULL IsNotNull All fields (excluding ID fields)

IS NULL IsNull All fields (excluding ID fields)

BEGINS WITH (‘%string’) BeginsWith All fields (excluding ID fields)

ENDS WITH (‘string%’) EndsWith All fields (excluding ID fields)

LIKE(‘%string%’)* Like* All fields (excluding ID fields)

CONTAINS('%string%') Contains All fields (excluding ID fields)

*LIKE has been replaced with CONTAINS in version 2.0 but will still be supported in v 1.0

People Methods

19

Note: Date queries are very specific down to the millisecond to support batch applications consuming

Data Exchange. If you need to return individuals or households based on dates (first record, date of birth, etc.) use an operator like BETWEEN or any other operator other than equalTo.

The Comparison Operator Examples below shows examples of queries using the comparison

operators in Query Comparison Operators above.

Comparison Operator Examples

Data Exchange Operator

Example

EqualTo*

<dateOfBirth operator=’EqualTo’

value=’5/27/1970’></dateOfBirth> or <dateOfBirth>5/27/1970</dateOfBirth>

GreaterThan <dateOfBirth operator=’GreaterThan’

value=’5/27/1970’></dateOfBirth>

LessThan <dateOfBirth operator=’LessThan’ value-

’5/27/1970’></dateOfBirth>

GreaterThanOrEqualTo <dateOfBirth operator=’GreaterThanOrEqualTo’


LessThanOrEqualTo <dateOfBirth operator=’LessThanOrEqualTo’


NotEqualTo <lastName operator=’NotEqualTo’ value=’Floyd’>

Between <dateOfBirth operator=’Between’ value=’5/27/1970’

valueToCompare=’5/27/2004’></dateOfBirth>

IsNotNull <dateOfBirth operator=’IsNotNull’

value=’NULL’></dateOfBirth>

IsNull <dateOfBirth operator=’IsNull’ value=”></dateOfBirth>

BeginsWith <lastName operator=’BeginsWith’ value=’Fl’>

EndsWith <lastName operator=’EndsWith’ value=’yd’>

Like <lastName operator=’Like’ value=’son’> (replaced by

Contains in v. 2.0)

Contains <lastName operator='Contains' value='loy'>

Data Exchange 2.0

20

*EqualTo is the default operator on all fields, no extra syntax is required if this is the desired comparison.

Record limits

250 records is the page threshold for GetIndividualCollection and GetHouseholdCollection. The following elements have been added to the configuration entity for each of these query types to reduce the risk of potentially harmful queries and to provide a way to avoid long running queries

that might time out:

Collections Nodes

Data Exchange Node for

Collections

Purpose

<page> The <page> node is required and tells Data Exchange which page to begin the query against. For example, if the query will return 150 records and the <numberOfRecords> to return is set to 50, there will be a total of 3 pages. The first request appears as shown below:

<page>1</page>

<numberOfRecords> The <numberOfRecords> node is optional and tells Data Exchange the number of records to return per page with each query. If the

number specified in this node exceeds 250, the number of records returned per page defaults to 250. For example, if the query has <numberOfRecords>275</numberOfRecords>, 250 records will be

returned.

People Methods

21

The following table displays the attributes returned by Data Exchange in the event multiple pages are available.

Data Exchange Paging Attributes

Data Exchange Paging Data for Collections

Purpose

pageNumber Identifier used to indicate which page was requested. If the request was sent <page>1</page>, then the value for the pageNumber attribute is 1.

additionalPages Boolean used to display if there are additional pages remaining in the query.

exportedCount Count that represents the total records returned.


You must provide an authentication header in your XML file or string. The authentication header contains your encrypted church code, your Fellowship One user ID, password, method to run,

and version. An example Authentication Header is shown below.

See Fellowship One login credentials for information on security authorizations required for Data Exchange.




<password>PASSWORD </password>

<method>METHOD NAME</method>



Data Exchange 2.0

22


Excluding information in the result set

A configuration node is available to exclude information from the results that are returned from a People Export. Basic individual information cannot be excluded from the results. One or more of the following entities can be excluded for each "Get" method:

• householdIndividual—excludes the individuals entity and thus all individual information in the results for GetHousehold and GetHouseholdCollection. The household information is the only entity that displays.

• householdAddress—excludes address in the household entity in the GetHousehold and GetHouseholdCollection methods. All individual addresses display in the result set.

• householdCommunication—excludes communication in the household entity in the GetHousehold and GetHouseholdCollection methods. All individual communication values display in the result set.

• individualAddress—excludes address in the individual entity. The household address displays in the result set if the method called is GetHousehold or GetHouseholdCollection.

• individualCommunication—excludes communication in the individual entity. The household communication values display in the result set if the method called is GetHousehold or GetHouseholdCollection.

• individualAttributes—excludes the attributes entity.

• individualHistory—excludes the merge record history from the result set.

Adding the entityExclusion node

entityExclusion can be added to the People Export methods in the <configuration> entity. The

following example shows the GetHouseholdCollection method excluding th

GetIndividual

The GetIndividual method returns the individual that matches the individualSourceCode,

individualCode, or WebLink information supplied. Ensure that you refer to the GetIndividual schema (see Export the schemas) for parameter information.

• individualSourceCode—the record number from the legacy church management

system (CMS) in Fellowship One. This number is available in your legacy system.

Note: This number is only available for Data Export if your data has been converted from your

legacy church management system or if you have previously uploaded the numbers through Data Exchange.

• individualCode—the encrypted Fellowship One ID for an individual. The encrypted

number is available from the results of a GetIndividualCollection query.

• weblink—the Fellowship One WebLink user name and password for an individual.

People Methods

23

• userId—the ID assigned to an individual to access his or her account on the church web site via Fellowship One WebLink. Must be used in conjunction with

the password.

• password—the password assigned to an individual to access his or her account

on the church web site. Must be used in conjunction with the userId. Example: <weblink>

<userId>love2sing</userId>

<password>all4jesus</password>

</weblink>

Building GetIndividual

GetIndividual requires the Authentication Header and a single parameter to find the individual.

<?xml version="1.0" ?>

<tns:dataRequest xmlns:tns="GetIndividual">


<churchCode>INSERT ENCRYPTED CHURCH CODE</church code>


<password>INSERT PASSWORD</password

<method>GetIndividual</method>




<parameters>

<configuration>

<entityExclusion> (OPTIONAL)

<entity>ENTITY TO EXCLUDE</entity>

</entityExclusion>

</configuration>

<individualSourceCode>INSERT CODE FROM LEGACY

CMS</individualSourceCode>

OR

<individualCode>INSERT THE ENCRYPTED ID CODE HERE</individualCode>

OR

<weblink>

<userId>INSERT USER ID HERE<userId>

<password>INSERT THE PASSWORD HERE<password>

</weblink>

</parameters>

</tns:dataRequest>

Example: Individual Code

In the following example, the XML string requests the individual whose individualCode is 2hnic7KZKN88r+OkceQEWg==.

<?xml version=”1.0” ?>

<tns:dataRequest xmlns:tns=”GetIndividual”>







Data Exchange 2.0

24



<parameters>

<individualCode>2hnic7KZKN88r+OkceQEWg==</individualCode>

</parameters>

</tns:dataRequest>

The results returned when you upload the example above is the individual record that matches the individual code. The XML results appear in a new Internet browser window.

Example: Individual Source Code

In the example below, the XML string requests the individual whose individualSourceCode is equal to 635086. The individualSourceCode is the code associated with the individual from the church's legacy church management system.

Note: The individualSourceCode is only available if the individual record was converted from your previous church management system into Fellowship One. individualSourceCodes can also be

uploaded through Data Exchange.











<parameters>

<individualSourceCode>635086</individualSourceCode>

</parameters>

</tns:dataRequest>

Example: WebLink ID and Password

In the example below, the XML string requests the individual whose Fellowship One WebLink™ user ID is janie123 and password is John3:16. When requesting individuals by WebLink ID, the password must also be included. The GetIndividual using WebLink ID request was developed for

use with your church web site. You can program your own Login module that uses Data Exchange to retrieve information about the user who logs in. This information can be used to display custom information to the user. For example, if the user is a woman, display activities and events for women.











<parameters>

<weblink>

People Methods

25

<userId>janie123</userId>

<password>John3:16</password>

</weblink>

</parameters>

</tns:dataRequest>

GetIndividualCollection

GetIndividualCollection returns all individuals that match the parameters included in the query. Remember that the threshold or cap to the number of records returned is 250 per page. Consider this number when you construct your query. Parameters like the following will very likely return more than 250 records. It's possible that you will have to rerun your query requesting a new

page to display the remaining results.

<lastName operator=’Like’ value=’sm’>

This parameter will return every last name that has the letters “sm” anywhere within the last name - so all Smiths, Smalls, etc. will be returned.

There are two nodes available to help you manage the number of records returned:

• page—tells data exchange which page to begin the query against.

• numberOfRecords—lets you specify the number of records to return with each query.

For example, if the parameter <numberOfRecords>50</numberOfRecords> is used in a

query that returns 150 records, three pages are available to be viewed.

Each page must be retrieved individually. In the example above, to see all 150 records, send in

three GetIndividualCollection XML strings. Change the <page> parameter in each of the strings.

<page>1</page>

<page>2</page>

<page>3</page>

GetIndividualCollection parameters

When sending in the XML file, individual collections can be queried based on the following parameters. Any of the parameters can be used, but they must be used in a hierarchical order.

Ensure that you refer to the GetIndividualCollection schema (see Export the schemas for more information) for the exact order of parameters.

• entityExclusion—a node in the configuration entity used to exclude parts of individual

records. For example, if you want to see only address information, you can choose to exclude all information other than the address information. See Excluding information in the result set for more information.

• entity—the parts of the individual record to exclude. IndividualAddress, individualCommunication, individualAttributes, and individualHistory can be

excluded. The basic, individual information is always returned and cannot be excluded.

• individualSourceCode—the record number from the legacy church management

system (CMS) in Fellowship One. This number is available in your legacy system. You can pass in one or more (comma delimited) individualSourceCode numbers.

• householdSourceCode—the record number for the household from the legacy CMS in

Fellowship One. This number, if available, exists in your legacy system.

Data Exchange 2.0

26

Note: individualSourceCode and householdSourceCode numbers are only available for Data Export if

your data has been converted from your legacy church management system.


number is available from the results of a GetIndividualCollection query. You can pass in one or more (comma delimited) individualCodes.

• householdCode—encrypted Fellowship One household ID. This number is available

from the results of a GetHouseholdCollection query.

• title—Sir, Lady, Honorable, Sgt. Major, and so on. Example: <title>Lt. Colonel</title>

• salutation—a field for communication use when "Dear Mr. Jones" is not a proper salutation. For example, it's proper to address a judge as "To the Honorable" in letters.

• prefix—Mr., Mrs., Dr., and so on. Example: <prefix>Mrs.</prefix>

• lastName—the last name of the individuals to query.

Example: <lastName operator=’Like’ value=’bro’></lastname>

• firstName—the first name of the individuals to query.

Example: <firstName operator=’BeginsWith’ operator=’Ca’></firstName>

• middleName—the middle name of the individuals to query.

Example: <middleName>James</middleName>

• formerName—the former (or maiden) name of the individuals to query.

Example: <formerName operator=’EndsWith’ value=’son’></formerName>

• goesBy—the nickname or shortened name of the individuals to query.

Example: <goesBy>Charlie</goesBy>

• suffix—Jr., Sr., III, and so on.

Example: <suffix>Jr.</suffix>

• gender—male or female. Example: <gender>male</gender>

• dateOfBirth—the birthday of the individuals to return. This parameter should be used with any operator other than EqualTo.

Example: <dateOfBirth operator=’Between’ value=’1/1/1996’ valueToCompare=’12/31/1997’ </dateOfBirth>

• maritalStatus—Fellowship One marital statuses: Child/Yth, Divorced, Separated, Married, Single, Widow, Widower. Example: <maritalStatus>Single</maritalStatus>

• firstRecord—the date the record was first added to Fellowship One. This parameter should be used with operators other than EqualTo.

Example: <firstRecord operator=’GreaterThan’ value=’4/1/2005’></firstRecord>

• occupationDescription—text field used to describe an individual’s occupation.

Example: <occupationDescription>CEO</occupationDescription>

• status—an individual’s status in Fellowship One (such as Attendee, Member, etc.).

Example: <status>New Checkin</status>

People Methods

27

• employer—text field used to record an individual’s employer.

Example: <employer operator=’Contains’ value=’Fellowship Tech’></employer>

• formerChurch—text field used to record an individual’s previous church.

Example: <formerChurch operator=’BeginsWith’ value=’First’></formerChurch>

• defaultTagComment—text field used to record special information to print on a participant’s name tag (such as “Allergic to peanuts”).

Example: <defaultTagComment operator=’Like’ value=’Allergic’></defaultTagComment>

• createdDate—the date the record was created. This parameter should be used with

operators other than EqualTo. Example: <createdDate operator='Before' value='12/31/2005'></createdDate>

• lastUpdate—the date the record was last updated. This parameter should be used with

operators other than EqualTo. Example: <lastUpdate operator=’Between’ value=’4/1/2005’ valueToCompare=’4/15/2005’></lastUpdate>

• lastMatchDate—the date the record was last updated using Duplicate Finder, moved or split. This parameter should be used with operators other than EqualTo.

Example: <lastMatchDate operator=’LessThanOrEqualTo’ value=’4/15/2005’></lastMatchDate>

• barcode—the bar code number associated with an individual for use in Fellowship One Check-in.

Example: <barCode operator=’Contains’ value=’182’></barCode>

• memberEnvelopeCode—a member or envelope number associated with an individual. This number is entered and updated on the "Basic" tab in the individual's record.

Example: <memberEnvelopeCode>4589</memberEnvelopeCode>

• solicit—a true/false setting indicating whether or not the individual wishes to receive

non-essential email or mail from the church. Example: <solicit>true</solicit>

• thank—a true/false setting indicating whether or not the individual wishes to be thanked

when he or she makes a contribution to the church. Example: <thank>false</thank>

• weblink—the user ID/password, password hint, or hint answer used to log into the church web site through Fellowship One WebLink.

• userId—the user ID used to log into the church web site through Fellowship

One WebLink. Used in conjunction with the password. Example: <weblink> <userId>frank</userId>

</weblink>

• passwordHint—the hint question used when the user name or password needs to be reset on the church web site through Fellowship One WebLink. Example: <weblink> <passwordHint operator='Contains' value='What was the name

of'></passwordHint>

</weblink>

• hintAnswer—the answer used to set the password hint. This answer is required

when requesting help with user names and passwords on the church web site through Fellowship One WebLink. <weblink>

Data Exchange 2.0

28

<hintAnswer operator='beginsWith' value='Ab'></hintAnswer>

</weblink>

• attribute—an individual attribute associated with an individual’s record (such as Baptism, Dedication, etc.).

• attributeName—the name of the attribute associated with the individual's record (i.e., Baptism, Dedication, etc.). Example: <attribute>

<attributeName>Baptism</attributeName>

</attribute>

• attributeGroupName—the group under which the attribute resides (i.e., Experiences, Skills/Talents, Favorites, etc.). Example: <attribute>

<attributeGroupName>Talents</attributeGroupName>

</attribute>

• comment—any comment associated with the attribute. Depending upon how

the Individual Attribute was configured, the Comment field may or may not be visible. Example: <attribute>

<comment operator='Contains' value='wood'></comment>

</attribute>

• startDate—a date associated with an individual attribute indicating when the attribute went into effect. Depending upon how the attribute was configured, the

Start Date field may or may not be visible. Example: <attribute>

<startDate operator='Between' value='1/1/2005'

valueToCompare='12/31/2005'></startDate>

</attribute>

• endDate—a date associated with an individual attribute indicating when the attribute expired. Depending upon how the attribute was configured, the End

Date field may or may not be available. Example: <attribute>

<endDate operator='greaterThan' value='1/12/2004'></endDate>

</attribute>

• createdDate—a system date associated with the entry date of the individual

attribute. This indicates when the attribute was associated with the individual. Example: <attribute>

<createdDate operator='Before' value='5/30/2005'></createdDate>

</attribute>

• lastUpdatedDate—a system date associated with any update made to an individual attribute. This date is assigned when any attribute is edited. Example: <attribute>

<lastUpdatedDate operator='lessThan'

value='2/1/2006'></lastUpdatedDate>

</attribute>

• address—addresses associated with the individual or his/her household.

• addressType—the address type. Types are assigned to an address when they are entered in the Communication tab of an individual's record. The available

types are: Business, College, Mail Returned/Incorrect, Org, Previous, Secondary, Statement, Vacation, Primary. Example: <address> <addressType>Primary</addressType>

</address>

People Methods

29

• address1—line one of the address (typically contains the street number and name). Example: <address> <address1 operator='beginsWith' value='123'></address1>

</address>

• address2—line two of the address (typically contains the suite or apartment

number). Example: <address> <address2 operator='Contains' value='#'></address2>

</address>

• address3—line three of the address (typically used for international addresses

that may contain a city region or other mail directive). Example: <address> <address3>Recoleta</address3>

</address>

• city—the city, town, or village for the address. Example: <address>

<city>Buenos Aires</city>

</address>

• postalCode—the zip or mail code for the address. Example: <address>

<postalCode operator='beginsWith' value='75'></postalCode>

</address>

• country—the country for the address. Example: <address>

<country>South America</country>

</address>

• stProvince—the state or province for the address. Example: <address>

<stProvince operator='Contains' value='ex'></stProvince>

</address>

• createdDate—a system date associated with the address. This date is assigned

when the address is initially entered. Example: <address>

<createdDate operator='Between' value='1/1/2005'

valueToCompare='5/31/2005'></createdDate>

</address>

• lastUpdatedDate—a system date associated with any update made to the

address. This date is assigned when the address is edited. Example: <address>

<lastUpdatedDate operator='greaterThanOrEqualTo'


</address>

• communication—the phone numbers, email addresses, web sites, instant messenger clients, blogs, and so on for an individual.

• communicationType—the type of communication value. The available types are: Alternate Email, Alternate Phone, Mobile, Children Phone, Email, Emergency Phone, Fax, Home Phone, IM Address, Pager, Previous Phone, School Email,

School Phone, Vacation Phone, Web Address, Work Email, Work Phone. Example: <communication> <communicationType>Email</communicationType>

</communication>

Data Exchange 2.0

30

• communicationValue—the number or email/web address. Example: <communication>

<communicationValue operator='contains'

value='@gmail.com'></communicationValue>

</communication>

• listed—a true/false flag indicating whether or not the value is a private or public

value. Example: <communication>

<listed>True</listed>

</communication>

• createdDate—a system date associated with the communication value. This date is assigned with the value is initially entered. Example: <communication>

<createdDate>4/22/2005</createdDate>

</communication>

• lastUpdatedDate—a system date associated with any update made to the communication value. This date is assigned when the value is edited. Example: <communication>

<lastUpdatedDate>2/14/2006</lastUpdatedDate>

</communication>

People Methods

31

Building GetIndividualCollection

GetIndividualCollection requires the Authentication Header as well as the parameters to use to

query the database. The <page> node is required in this XML string query; however, the <numberOfRecords> node is optional.






<password>INSERT PASSWORD</password>





<parameters>

<configuration>



</entityExclusion>

<page>INSERT PAGE NUMBER</page>

<numberOfRecords>INSERT # OF RECORDS (optional - defaults to 250 per

page)</numberOfRecords>

</configuration>

<INSERT PARAMETER operator=’INSERT OPERATOR’ value=’VALUE’>

</PARAMETER>

</parameters>

</tns:dataRequest>

Example: Individual Attributes

The following example returns page 1 of all individuals that have the individual attribute Baptism and where the last name is equal to Coulson. Each page contains 50 records.











<parameters>

<page>1</page>


<lastName>Coulson</lastName>

<attribute>

<attributeName operator='Contains'

value='Baptism'></attributeName>

</attribute>

</parameters>

</tns:dataRequest>

Data Exchange 2.0

32

Example: First Record Date

The following example returns page 1 of all individuals that had records created after 4/25/2005. Each page contains 50 records.











<parameters>

<page>1</page>


<firstRecord operator='GreaterThan'

value='4/25/2005'></firstRecord>

</parameters>

</tns:dataRequest>

Example: Last Name

The following example returns page 2 of all individuals that have the last name “Floyd”. Only 5 records appear on each page.











<parameters>

<page>2</page>


<lastName operator='BeginsWith' value='Flo'></lastName>

</parameters>

</tns:dataRequest>

Example: List of individuals

The following example returns all individuals that match the individual codes passed in the method.











<parameters>

People Methods

33

<individualCode>XuXkPVtLrIWRruk5M0eALw==, mYmGhCbbh6VPb3fO+PlewA==,

iHt+K34BKhXt89egwqpOSg==</individualCode>

</parameters>

</tns:dataRequest>

GetHousehold

GetHousehold returns a single household based upon one of four parameters. Get household returns all individuals associated with the requested household. All household and individual

address and communication values are also returned. Additionally, basic information for each individual appears in the results.

GetHousehold parameters

When sending in the XML file, a household can be queried based on the following parameters. Ensure that you refer to the GetHousehold schema (see Exporting the schemas on page 3 for more information) for the exact order of parameters.

• individualSourceCode—the record number from the legacy church management system (CMS) in Fellowship One. This number, if available, is in your legacy system. You can pass in one or more individualSourceCode numbers (from the same household).

Note: This parameter returns the household with only individual records that match the individualSourceCode. It must be used in addition to householdCode or

householdSourceCode.

• householdSourceCode—the record number for the household from the legacy CMS in Fellowship One. This number, if available, exists in your legacy system.

Note: individualSourceCode and householdSourceCode numbers are only available for Data Export if

your data has been converted from your legacy church management system or if you have previously uploaded this data using Data Exchange.


number is available from the results of a GetIndividualCollection query. You can pass in one or more individualCodes from the same household. As with the individualSourceCode, if you pass in individualCodes only individuals that match the indivdidualCode are returned. Also, this parameter must be used in addition to

householdCode or householdSourceCode.


from the results of a GetHouseholdCollection query.

Data Exchange 2.0

34

Building GetHousehold

GetHousehold requires the Authentication Header as well as the parameters to use to query the

database.


<tns:dataRequest xmlns:tns="GetHousehold">


<churchCode>INSERT ENCRYPTED CHURCH CODE</churchCode>



<method>GetHousehold</method>




<parameters>

<configuration>



</entityExclusion>

</configuration>

<householdCode>INSERT ENCRYPTED CODE</householdCode>

OR

<householdSourceCode>INSERT LEGACY CODE</householdSourceCode>

AND*

<individualCode>INSERT ENCRYPTED CODE</individualCode>

OR*

<individualSourceCode>INSERT LEGACY CODE</individualSourceCode>

</parameters>

</tns:dataRequest>

* Note:

individualCode and individualSourceCode must be used in addition to householdCode and householdSourceCode.

Example: Encrypted Household Code

The following example returns the household associated with the encrypted householdCode N0IRcrLTAva/KZwJ62zlfg==.











<parameters>

<householdCode>N0IRcrLTAva/KZwJ62zlfg==</householdCode>

</parameters>

</tns:dataRequest>

People Methods

35

Example: Household Source Code (legacy CMS)

The following example returns the household associated with the householdSourceCode (from the legacy CMS) 1539006.











<parameters>

<householdSourceCode>1539006</householdSourceCode>

</parameters>

</tns:dataRequest>

GetHouseholdCollection

GetHouseholdCollection returns all households and all individuals within the households that match the parameters included in the query. This is the most complete export query and can take some time to run depending upon the criteria entered.

Remember that the threshold or cap to the number of records returned is 250 per page. Consider

this number when you construct your query. Parameter’s like the following will very likely return more than 250 records.

<householdName operator=’Contains’ value=’an’></householdName>

This parameter will return every household that has the letters “an” anywhere within the any of the names that make up the household name.

There are two configuration nodes available to help you manage the number of records returned:

• page—tells data exchange which page to begin the query against.

• numberOfRecords—lets you specify the number of records to return with each query.

For example, if <numberOfRecords>50</numberOfRecords> in a query that returns 150 records,

three pages are available to be viewed.

Each page must be retrieved individually. In the example above, to see all 150 records, send in

three GetHouseholdCollection XML strings. Change the <page> parameter in each of the strings.

<page>1</page>

<page>2</page>

<page>3</page>

Data Exchange 2.0

36

GetHouseholdCollection parameters

When sending in the XML file, households can be queried based on the parameters listed below.

You can use any number of the parameters within your XML string; however, parameters must be in hierarchical order. Ensure that you refer to the GetHouseholdCollection schema (see Exporting the schemas on page 3 for more information) for the exact order of parameters.

• individualSourceCode—the record number from the legacy church management system (CMS) in Fellowship One. This number, if available, is in your legacy system. You can pass one or a comma delimited list of individualSourceCode numbers.

Note: Using this parameter returns households with only the individuals that match the individualSourceCode.

• householdSourceCode—the record number for the household from the legacy CMS in Fellowship One. This number, if available, exists in your legacy system. You can pass one or a comma delimited list of householdSourceCode numbers.

Note: individualSourceCode and householdSourceCode numbers are only available for Data Export if your data has been converted from your legacy church management system.

• individualCode—the encrypted Fellowship One ID for an individual. The encrypted number is available from the results of a GetIndividualCollection query. You can pass one code or a comma delimited list of individualCodes. As with individualSourceCode, using

this parameter returns households with only the individuals that match the individual code passed.


from the results of a GetHouseholdCollection query. You can pass one code or a comma delimited list of householdCodes.

• householdName—the name of the household (such as John and Jane Smith). In

Fellowship One household names are made up of the individuals with “Head” and

“Spouse” household member types. Example: <householdName operator=’Like’ value=’Smith’> </householdName>

• householdFirstName—the first names of the household name (see householdName

above). Example: <householdFirstName operator=’BeginsWith’ value=’Ja’> </householdFirstName>

• householdSortName—the last name of the household name (see householdName

above). Example: <householdSortName operator=’EndsWith’ value=’ith’> </householdSortName>

• lastActivityDate—the last date any individual within a household attended an activity

(attendance recorded through Fellowship One Check-in or via Post Attendance) or gave a contribution. Use an operator with this parameter other than EqualTo. Example: <lastActivityDate operator=’GreaterThanOrEqualTo’

value=’4/10/2005’></lastActivityDate>

Note: The Post Attendance date and contribution Received Date update the lastActivityDate field based

on a process that runs nightly. Use GetHouseholdCollection with this parameter the day after either of these processes run.

People Methods

37

• lastUpdatedDate—a system date that is recorded when the household is edited. Use an operator with this parameter unless you know the date a household was modified.


• addressType—the address type. Types are assigned to an address when they

are entered in the Communication tab of an individual's record. The available types are: Business, College, Mail Returned/Incorrect, Org, Previous, Secondary, Statement, Vacation, Primary. Example: <address>

<addressType>Primary</addressType> </address>

• address1—line one of the address (typically contains the street number and name). Example: <address>

<address1 operator='beginsWith' value='123'></address1> </address>


number). Example: <address>

<address2 operator='Contains' value='#'></address2> </address>

• address3—line three of the address (typically used for international addresses that may contain a city region or other mail directive). Example: <address>

<address3>Recoleta</address3> </address>


<city>Buenos Aires</city> </address>

• postalCode—the zip or mail code for the address. Example: <address> <postalCode operator='beginsWith' value='75'></postalCode>

</address>

• country—the country for the address. Example: <address> <country>South America</country>

</address>

• stProvince—the state or province for the address. Example: <address> <stProvince operator='Contains' value='ex'></stProvince>

</address>

• createdDate—a system date associated with the address. This date is assigned when the address is initially entered. Example: <address> <createdDate operator='Between' value='1/1/2005'

valueToCompare='5/31/2005'></createdDate>

</address>

• lastUpdatedDate—a system date associated with any update made to the address. This date is assigned when the address is edited. Example: <address> <lastUpdatedDate operator='greaterThanOrEqualTo'

Data Exchange 2.0

38


</address>


• communicationType—the type of communication value. The available types are: Alternate Email, Alternate Phone, Mobile, Children Phone, Email, Emergency

Phone, Fax, Home Phone, IM Address, Pager, Previous Phone, School Email, School Phone, Vacation Phone, Web Address, Work Email, Work Phone. Example: <communication>

<communicationType>Email</communicationType> </communication>


<communicationValue operator='contains'

value='@gmail.com'></communicationValue>

</communication>

• listed—a true/false flag indicating whether or not the value is a private or public value. Example: <communication>


</communication>

• createdDate—a system date associated with the communication value. This date is assigned with the value is initially entered. Example: <communication>


</communication>


communication value. This date is assigned when the value is edited. Example: <communication>


</communication>

Building GetHouseholdCollection

GetHouseholdCollection requires the Authentication Header as well as the parameters to use to

query the database. The <page> node is required in this XML string query; however, the

<numberOfRecords> node is optional.











<parameters>

<configuration>

<page>PAGE NUMBER</page>

<numberOfRecords>NUMBER OF RECORDS PER PAGE</numberOfRecords>

<entityExclusion>(OPTIONAL)


People Methods

39

</entityExclusion>

<PARAMETER operator='OPERATOR' value='VALUE'></PARAMETER>

</parameters>

</tns:dataRequest>

Example: Last Activity Date

The following example returns all households that had any activity recorded between 4/1/2005

and 4/15/2005. lastActivityDate is updated by three things:

• Attendance recorded by Fellowship One Check-in (immediate update)

• Attendance recorded through Post Attendance (updates with a nightly database process)

• Contributions received date (updates with a nightly database process











<parameters>

<configuration>


<entity>individualHistory</entity>

</entityExclusion>

<page>1</page>


</configuration>

<lastActivityDate operator='Between' value='4/1/2005'

valueToCompare='4/15/2005'></lastActivityDate>

</parameters>

</tns:dataRequest>

Example: Last Name (Households)

The following example returns all households and the individual household members with

“Coulson” anywhere within the household name. Remember that household name is made up of the first names of both the “Head” and “Spouse” member type as well as the household last name.











<parameters>

<configuration>


<entity>householdAddress</entity>

Data Exchange 2.0

40

<entity>householdCommunication</entity>

</entityExclusion>

<page>1</page>

</configuration>

<householdName operator='Like' value='Coulson'></householdName>

</parameters>

</tns:dataRequest>

Example: Household First Name

The following example returns all households and the individual household members with “uar” anywhere within the household first names.











<parameters>

<configuration>


<entity>householdIndividual</entity>

</entityExclusion>

<page>1</page>


</configuration>

<householdFirstName operator='Like'

value='uar'></householdFirstName>

</parameters>

</tns:dataRequest>

Running the export

There are three ways you can request the export (or get an export method schema):

• Consume the Data Exchange Web service programmatically. The following simplified

example shows the XML string embedded within a function in a Web application written on the .NET platform.

private void Page_Load(object sender, System.EventArgs e)

{

if(IsPostBack){

string sXML;

sXML=@”<tns:dataRequest

xmlns:tns=’GetHouseholdCollection’><authenticateHeader>


<user>USER NAME</user><password>PASSWORD</password>


<version>2.0</version><methodGroup>People</methodGroup>

</authenticateHeader><parameters><configuration>

<page>1</page><numberOfRecords>100</numberOfRecords>

</configuration><householdName operator=’BeginsWith’

value=’Ni’>

</householdName></parameters></tns:dataRequeset>

People Methods

41

DataRequest.DataRequest dr=new DataRequest.DataRequest();

Object oDoc = new Object();

XmlDocument xDoc - new XmlDocument();

XmlNode xNode;

oDoc = dr.Request(sXML);

xNode = (XmlNode)oDoc;

xDoc.LoadXml(xNode.OuterXml);

Response.Write(xNode.OuterXml);

}

}

• Accessing the Data Exchange - Export via the ASMX web service:


Data Exchange 2.0

42

• Accessing Data Exchange - Export People through Fellowship One. (Admin tab, Data Exchange and People Export menu options).

Data Export through Fellowship One

The People Export feature in Fellowship One allows you to upload your export request XML file directly to Fellowship One. Once uploaded, the file is immediately read and executed.

If an error occurs, a new browser window opens to display an error message.

If the request is executed successfully, the results display and the Data Exchange People Export table can be refreshed to show the request details.

People Methods

43

Data Exchange 2.0

44

To request an export via Fellowship One


2. Click Data Exchange and People Export in the menu options. The Export People page appears.

3. Click Browse. The Choose File dialog box appears.

4. Browse to and select the XML file to upload and click Open. The path and file name appear in the Data Export field.

5. Click Run Export. A new Internet browser window opens with the results of your method and query parameters.

6. Close or save the results.

7. Click Refresh to review details about your request.

People Methods

45

Data Exchange People Exports

The Data Exchange People Exports table includes information about every export requested and

executed as shown below:

The information available is detailed in the following table.

Data Exchange People Export

Item Description

Run Export Click to run the export. Results appear in a new browser window.

View Request Click to view the original XML request. The XML file appears in a new browser window.

Export Method Click to view the schema associated with the method. The

schema appears in a new browser window

Date Executed The time stamp associated with the last run of the export.

Portal User The user ID included in the XML file

Number of Items

Exported

The number of items included in the XML result file. GetIndividual and GetHousehold always display 1; however,

GetIndividualCollection and GetHouseholdCollection display the number of results returned from the query parameters.

Data Exchange 2.0

46

Importing Data

Data Import allows you to modify results from a Data Export and import them back into Fellowship One. Additionally, new households and new individuals can also be added.

Data Import can be used in programming to mass update household and individual records in Fellowship One. In particular, Fellowship One WebLink user information, Individual Attributes or Statuses are easy to update or add through Data Import.

The following items can be imported and updated:

• Single individual

• Individual collections

• Single household

• Household collections

The parameters available for update depend upon the method used. The parameters are described later in this chapter.

Warning!

Be careful when performing mass updates. There is no undo from Fellowship One.

Method constructs

XML strings contain methods to determine the results to be updated. There are four methods that can be used. The following table displays the methods and a description of what the method

updates.

Method Constructs

Method Description

UpdateIndividual Updates information about an individual. Address, communication values, statuses, WebLink user

information and attributes can be updated.

UpdateIndividualCollection Updates information on a collection of individuals. Address, communication values, statuses, WebLink user information and attributes can be updated.

UpdateHousehold Updates information about a particular household and the individuals associated with the household. Use this

method to add new individuals to an existing household

UpdateHouseholdCollection

Updates information on a collection of households and the individuals associated with each household. Use this

method to add new individuals to existing households or completely new households/individuals.

People Methods

47

Setting the entityState

When preparing your XML strings for import, it is essential that you set the entityState parameter. When an exported file is returned, all entityState parameters are set to UnChanged.

Note:

Any entityState that is set to UnChanged causes Data Exchange to ignore the parameter during the import.

To update records, you must change the entityState parameter to one of the following:

• Modified—the item already exists but is changing with the update. In the following example, the email communication value has been modified. When the file is uploaded,

the new email address is saved.

<communication entityState="Modified">

<communicationType>Email</communicationType>

<communicationValue>[email protected]</communicationValue>

<listed>true</listed>

</communication>

Note:

The exception is the WebLink entity. Every individual record in Fellowship One has a placeholder for WebLink user information whether an account has been created or not. Use Modified to add a new user name and password.

• Added—the item does not exist and is added with the update. You can add address and communication values as well as attributes to any individual within any of the method constructs. The following example shows a new attribute Baptism, which will save in the

individual’s record after the update.

<attributes>

<attribute entityState="Added">

<attributeName>Baptism</attributeName>

</attribute>

</attributes>

Note:

When adding a new individual, use UpdateHousehold or UpdateHouseholdCollection. When adding a new household, use UpdateHouseholdCollection.

Null fields

Data Exchange v2.0 provides support for null fields. This feature allows mass updated to data to correct unneeded data. For example, if you want to export all children who are between 0 - 17 and delete the "Mr." or "Miss" in the <prefix> node, you can do so. Use GetIndividualCollection

and save the results. Change each individual's entityState to Modified and then change the prefix node to <prefix />. Use the UpdateIndividualCollection method to import your changes.

Data Exchange 2.0

48

Import rules

There are a few rules to remember when working with Data Import.

• Update the entityState to the correct value (Modified or Added) depending upon the

action needed. Any entityState that is set to UnChanged causes Data Exchange to ignore the parameter during the import.

• A parent entityState overrides a child entityState. For example, if the household entityState=’Added’ and the individual entityState=’Modified’ or ‘UnChanged’, the individual entityState is changed to ‘Added’.

• Any parameter that is not correct fails. For example, if the parameter <status> is updated to “First Time Visitor” but the value that exists in Fellowship One is “1st Time Visitor”, the value is not updated. The Data Exchange People Import grid will show

the number of items that failed to update.

• If at least one of the code parameters—householdCode, individualCode, householdSourceCode, or individualSourceCode—do not exist in the update parameters,

the individual or household is treated as a new item and will be added to Fellowship One as a new household or new individual.

• householdCode or householdSourceCode is required if adding a new individual to an

existing household. If at least one of these parameters is not provided, the individual is treated as new and added to Fellowship One in his or her own household.

• If multiple people need to be inserted into a new household, the import must be

constructed as a new household with new individuals within it. This ensures that each individual is assigned the same new householdCode by Fellowship One.

Import results

If any item in the XML file fails to update for any reason, it does not stop the import from running. At the end of the import, an XML string is returned that displays the status of each item within the original update.

People Methods

49

The following table explains the codes that are returned in the in the message and what each

represents.

Note: These attributes only display on collection results not on single household or individual update results.

Import result statuses and counts

Statuses and Counts

Purpose

Sucess

Each entity and child node contains a success flag. The flag

indicates whether the update for the node was successful. For example, if an update to an individual with an invalid communication type by everything else about the individual is properly updated, the communication notde is flagged as

Sucess=false and the individual node is flagged as Success=true

CompleteCount The number of parent nodes in the collection that were successfully updated

IncompleteCount The number of parent nodes in the collection that were at least partially successfully updated

FailedCount The number of parent nodes in the collection that totally failed during the update

Data Exchange 2.0

50

Statuses and Counts

Purpose

Status

Possible values are: In Queue, Complete, Incomplete, or Failed. Most collections are either Complete or Incomplete. The status is

set based on the following rules:

• Complete—all items in the update complete without any problems (the count also reflects this)

• Incomplete—one (1) or more items fails or is incomplete

• Failed—all items in the collection failed or there was a critical system error


Data Import requires an authentication header in the XML string to be imported. The

authentication header contains your encrypted church code, your Fellowship One user ID, password, method name, and version. An example Authentication Header is shown below.


<churchCode>CHURCH CODE</churchCode>



<method>METHOD NAME</method>




Synchronous processing

A utility method called RequestProcessType is available in the configuration entity in UpdateIndividual or UpdateHousehold methods. RequestProcessType allows you to request

synchronous processing of your update.

Note: All Data Exchange processing is done asynchronously unless synchronous processing is

specifically requested in these two methods.

When accessing Data Exchange programmatically through your church web site, it is sometimes beneficial to update data immediately. For example, you could build your own “My Account” tool

that allows people to manage their WebLink account and update their online profile. The information could be pushed into Fellowship One via Data Exchange synchronously as the user makes updates.

In the following Update example, the RequestProcessType node has been included in the UpdateIndividual request.

<tns:dataRequest xmlns:tns="UpdateIndividual">





<method>UpdateIndividual</method>

People Methods

51




<configuration>

<requestProcessType>Synchronous</requestProcessType>

</configuration>

<data>


individualCode="/cR4gs9myzeVRNHZ+lUzDw==">

<title/>

<salutation/>


<firstName>Susan</firstName>

<lastName>Harris</lastName>

<suffix/>

<middleName/>

<goesByName/>

<formerName/>



<maritalStatus/>


<occupation/>

<occupationDescription/>

<employer/>

<school/>

<formerChurch/>


<statusDate/>

<statusComment/>

<barCode/>

<memberEnvelopeCode/>

<defaultTagComment/>

<solicit/>

<thank/>


<lastMatchDate>2005-08-18T00:46:02</lastMatchDate>



<individualHistory />


<userId/>

<password/>

<passwordHint/>

<passwordAnswer/>

</weblink>

<attributes/>

<addresses/>

<communications/>

</individual>

</data>

</tns:dataRequest>

Data Exchange 2.0

52

UpdateIndividual

Use UpdateIndividual to update an existing record. The fields that can be updated are as follows:

• title—the person's title such as Lt. Colonel, Judge, Reverend, Bishop, Lord, Lady, and so

on.

• salutation—a field to be used when "Dear Mr. Jones" is not a proper salutation for

letters or email. For example, when addressing a letter to a judge it is proper to begin the salutation with "To the Honorable".

• prefix—Mr., Mrs., etc.

• firstName—the first or “proper” name of the individual

• lastName—the last or family name of the individual

• suffix—Jr., Sr., III, and so on.

• middleName—the middle name of the individual

• goesByName—the nickname or shortened name of the individual

• formerName—the previous or maiden name of the individual

• gender—male or female

• dateOfBirth—captures the time down to the millisecond if desired. The format can be

YYYY-MM-DD or MM-DD-YYYY

• maritalStatus—the available marital statuses are Child/Yth, Divorced, Separated,

Married, Single, Widow, and Widower

• householdMemberType—the available household member types are Head, Spouse, Child, Visitor, and Other

• occupation—the occupation must be set to one of the occupations that currently exists for the church. Check the Occupation drop-down list on the Basic tab for an individual to see available occupations. If the occupation within the UpdateIndividual XML is not

correct, an error message displays when the update is finished.

Note:

Occupations are static as of this release. Look for updateable occupations in a future relase of Fellowship One.

• occupationDescription—text field used to describe an individual’s occupation.

• employer—text field used to record an individual’s employer.

• school—text field used to record the individual's school or college.

• status—four (4) of the global statuses included with Fellowship One: Attendee, Member, Deceased, and Inactive can be updated. Any other statuses are configured by the church in the Admin tab Database Values and Status menu options and can also be

updated.

• statusDate—date a status was assigned to an individual.

• statusComment—text field used to record any comments about the individual's status.

• barcode—text field used to record a barcode number for use in Fellowship One Check-in.

People Methods

53

• memberEnvelopeCode—text field used to record a member number or envelope number.

• defaultTagComment—text field used to record a comment that will print on the individual's name tag in Fellowship One Check-in. This field is typically used to inform

care givers of a child's allergies or medical conditions.

• solicit—true/false field used to determine whether or not the individual prefers to receive email or mail communications from the church.

• thank—true/false field used to determine whether or not the individual wishes to be thanked for contributions given to the church.

• firstRecord—the date the record was first added to Fellowship One. This parameter

should be used with operators other than EqualTo.

• lastMatchDate—a system date that indicates the last time the individual's record was

matched in Merge Individual or Duplicate Finder.

• createdDate—a system date that is saved when the individual record is created.

• lastUpdatedDate—a system date that is saved when the individual's record is modified. (Cannot be updated.)

• individualHistory—system dates listing merge information about the individual's

record. (Cannot be updated.)

• weblink—the user ID/password, password hint, or hint answer used to log into the

church web site through Fellowship One WebLink.

• userId—the user ID used to log into the church web site through Fellowship One WebLink. Used in conjunction with the password. Example: <weblink>

<userId>frank</userId>

</weblink>

• password—the password to log into the church web site through Fellowship

One WebLink. Example: <weblink>

<userId>frank</userId>

</weblink>

• passwordHint—the hint question used when the user name or password needs

to be reset on the church web site through Fellowship One WebLink. Example: <weblink>

<passwordHint>What was the color of your first car?</passwordHint>

</weblink>

• hintAnswer—the answer used to set the password hint. This answer is required when requesting help with user names and passwords on the church web site through Fellowship One WebLink. <weblink>

<hintAnswer>Red</hintAnswer>

</weblink>

• attribute—an individual attribute associated with an individual’s record (such as

Baptism, Dedication, etc.).

• attributeName—the name of the attribute associated with the individual's record (i.e., Baptism, Dedication, etc.). Example: <attribute>

<attributeName>Carpentry</attributeName>

</attribute>

Data Exchange 2.0

54

• attributeGroupName—the group under which the attribute resides (i.e., Experiences, Skills/Talents, Favorites, etc.). Example: <attribute>

<attributeGroupName>Talents</attributeGroupName>

</attribute>

• comment—any comment associated with the attribute. Depending upon how

the Individual Attribute was configured, the Comment field may or may not be visible. Example: <attribute>

<comment>Carpentry expert</comment>

</attribute>

• startDate—a date associated with an individual attribute indicating when the attribute went into effect. Depending upon how the attribute was configured, the

Start Date field may or may not be visible. Example: <attribute>

<startDate>1/1/2005</startDate>

</attribute>

• endDate—a date associated with an individual attribute indicating when the

attribute expired. Depending upon how the attribute was configured, the End Date field may or may not be available. Example: <attribute>

<endDate>1/12/2004</endDate>

</attribute>

• createdDate—a system date associated with the entry date of the individual attribute. This indicates when the attribute was associated with the individual.

Example: <attribute>


</attribute>

• lastUpdatedDate—a system date associated with any update made to an

individual attribute. This date is assigned when any attribute is edited. Example: <attribute>


</attribute>


• addressType—the address type. Types are assigned to an address when they

are entered in the Communication tab of an individual's record. The available types are: Business, College, Mail Returned/Incorrect, Org, Previous, Secondary, Statement, Vacation, Primary. Example: <address>

<addressType>Primary</addressType>

</address>

• address1—line one of the address (typically contains the street number and name). Example: <address>

<address1>123 Main Street</address1>

</address>


number). Example: <address>

<address2># 3B</address2>

</address>

People Methods

55

• address3—line three of the address (typically used for international addresses that may contain a city region or other mail directive). Example: <address>

<address3>Recoleta</address3>

</address>


<city>Buenos Aires</city>

</address>

• postalCode—the zip or mail code for the address. Example: <address>

<postalCode>75038</postalCode>

</address>

• country—the country for the address. Example: <address>

<country>United Kingdom</country>

</address>

• stProvince—the state or province for the address. Example: <address>

<stProvince>Texas</stProvince>

</address>

• uspsVerified—true/false flag used to indicate whether or not the address has been verified by the United States Postal Service. Example: <address>

<uspsVerified>True</uspsVerified>

</address>

• createdDate—a system date associated with the address. This date is assigned

when the address is initially entered and can be set through data import. Example: <address>


</address>

• lastUpdatedDate—a system date associated with any update made to the address. This date is assigned when the address is edited and like the

createdDate, can be entered through the data import.


• communicationType—the type of communication value. The available types are: Alternate Email, Alternate Phone, Mobile, Children Phone, Email, Emergency Phone, Fax, Home Phone, IM Address, Pager, Previous Phone, School Email,

School Phone, Vacation Phone, Web Address, Work Email, Work Phone. Example: <communication>


</communication>



</communication>

• listed—a true/false flag indicating whether or not the value is a private or public value. Example: <communication>

Data Exchange 2.0

56


</communication>

• createdDate—a system date associated with the communication value. This date is assigned with the value is initially entered and can be set through the

data import. Example: <communication>


</communication>


communication value. This date is assigned when the value is edited and can be updated through data import. Example: <communication>


</communication>

• individualCode—the encrypted code added when a new individual is added to

Fellowship One.

Building UpdateIndividual

The UpdateIndividual method has the following requirements:

• Use UpdateIndividual to update an individual’s record. First, query for the individual using

GetIndividual in Data Export (you will need the encrypted individualCode)

• Change the entityState(s) to Modified or Added as appropriate. Any entityState set to

UnChanged is ignored in the update

• Include the authentication header in the XML string


<tns:dataRequest xmlns:tns="UpdateIndividual">








<data>



individualCode="Be8abqy/mn5OJuS+m/ViHA==">

<title />

<salutation />


<firstName>Marcus</firstName>

<lastName>Abbott</lastName>

<suffix />

<middleName />

<goesByName />

<formerName />





<occupation>Doctor</occupation>


<employer />

<school />

People Methods

57

<formerChurch />



<statusComment />

<barCode />



<solicit />

<thank>true</thank>


<lastMatchDate />

<createdDate />



<userId>marcusabbott</userId>

<password>marcusabbott</password>

<passwordHint />

<passwordAnswer />

</weblink>

<attributes>

<attribute entityState="UnChanged">

<attributeName>Newcomers -

Completed</attributeName>

<attributeGroupName>Experiences</attributeGrou

pName>

<comment />

<startDate>2003-10-04T00:00:00</startDate>

<endDate />

<createdDate />

<lastUpdatedDate />

</attribute>


<attributeName>Small Group

Director</attributeName>

<attributeGroupName>Small

Groups</attributeGroupName>

<comment />

<startDate />

<endDate />


<lastUpdatedDate />

</attribute>

</attributes>

<addresses />

<communications>

<communication entityState="UnChanged">


<communicationValue>[email protected]</communic

ationValue>

<listed>true</listed>

<createdDate />



</communication>

</communications>

</individual>

</data>

</tns:dataRequest>

Data Exchange 2.0

58

UpdateIndividualCollection

Use UpdateIndividualCollection to update information for many individuals. The parameters that can be updated are exactly the same as those within UpdateIndividual. See UpdateIndividual for a list of available parameters.

Building UpdateIndividualCollection

The UpdateIndividualCollection method has the following requirements:

• Use UpdateIndividualCollection to update individual records. First, query for the

individuals using GetIndividualCollection in Data Export (you will need the individualCode for each individual you wish to update)





<tns:dataRequest xmlns:tns="UpdateIndividualCollection">









<data>

<individuals>



individualCode="iHt+K34BKhXt89egwqpOSg==">

<title />

<salutation />


<firstName>Art</firstName>

<lastName>Baker</lastName>

<suffix />

<middleName />

<goesByName />

<formerName />







<employer>Phillips Sales</employer>

<school />

<formerChurch />



<statusComment />

<barCode />



<solicit />

<thank>true</thank>


People Methods

59

<lastMatchDate />

<createdDate />




<userId>artbaker</userId>

<password>artbaker</password>

<passwordHint />

<passwordAnswer />

</weblink>

<attributes>



Leader</attributeName>



<comment />

<startDate />

<endDate />

<createdDate>2006-02-

27T10:13:11</createdDate>

<lastUpdatedDate />

</attribute>

</attributes>

<addresses />

<communications />

</individual>



individualCode="mYmGhCbbh6VPb3fO+PlewA==">

<title />

<salutation />


<firstName>Dorothy</firstName>


<suffix />

<middleName />

<goesByName />

<formerName />





<occupation />

<occupationDescription>Stenographer</occupationDescr

iption>

<employer>Dallas County</employer>

<school />

<formerChurch>1st AoG Chandler TX</formerChurch>



<statusComment />

<barCode />



<solicit />

<thank>true</thank>


<lastMatchDate />

<createdDate />




Data Exchange 2.0

60

<userId>dorothybenton</userId>

<password>dorothybenton</password>

<passwordHint />

<passwordAnswer />

</weblink>

<attributes />

<addresses />

<communications />

</individual>

</individuals>

</data>

</tns:dataRequest>

UpdateHousehold

Use UpdateHousehold to update a household and all the individuals within the household. Addtionally, add new household members the household. The parameters available are as

follows:

• householdName—the first and last names of the “Head” and “Spouse” household member types. For example, “John and Jane Smith”

• householdFirstName—the first names of the “Head” and “Spouse” household member types. For example, “John and Jane”

• householdSortName—the last name of the “Head” household member type. For

example, “Smith”

• Household Addresses (addresses)

• addressType—available types are as follows: Primary, Secondary, College, Vacation, Business, Org, Previous, Statement, and Mail Returned/Incorrect

Note:

There can be only one “Primary” address type per household. You can add as many household addresses as needed

• address1—the street address for the household

• address2—an apartment or suite number for the household

• address3—typically used in international addresses

• city—the city for the household

• postalCode—the zip code for the household

• country—the country of the household address

• stProvince—the two letter abbreviated state or province code. For example, “TX”, “CA”, etc.

• uspsVerified—true/false flag used to indicate whether or not the address has

been verified by the United States Postal Service.

• Household Communications (communications)

• communicationType—available types are as follows: Home Phone, Work Phone, Mobile, Email, Alternate Email, Vacation Phone, Pager, Children Phone, Fax, Web Address, Previous Phone, IM Address, and Alternate Phone

• communicationValue—for example, the phone number, email address, IM address, etc.

People Methods

61

• listed—is the communication type publicly listed? True or false

• individuals—the individuals that belongs within the household

• individual—each individual within the household. Use “Modified” to change existing information. Use “Added” to add a new individual to the household

See UpdateIndividual for all the possible individual parameters

Building UpdateHousehold

When building UpdateHousehold, remember that you need to provide a householdCode or

householdSourceCode to update an existing household (use GetHouseholdCollection to find this information). Additionally, do the following:

• First, query for the individuals using GetHouseholdCollection in Data Export (you will

need the encrypted householdCode for household you wish to update)





<tns:dataRequest xmlns:tns='UpdateHousehold'>





<method>UpdateHousehold</method>




<data>

<household entityState="Modified" householdSourceCode=''

householdCode='tRGMM19OWl/GCT4QmS1q0w=='>

<householdName>Jeff and Tara Coulson</householdName>

<householdFirstName>Jeff and Tara</householdFirstName>

<householdSortName>Coulson</householdSortName>

<addresses>

<address entityState="UnChanged">


<address1>1234 Deer Horn Dr.</address1>

<address2 />

<address3 />

<city>Plano</city>


<country>USA</country>

<stProvince>TX</stProvince>

<uspsVerified>False</uspsVerified>



</address>

</addresses>

<communications>


<communicationType>Home Phone</communicationType>

<communicationValue>972-555-1212</communicationValue>

<listed>false</listed>

</communication>

</communications>

<individuals>

Data Exchange 2.0

62


individualCode="NY4BZLTmaL07/7gqy8hRWw==">

<title />

<salutation />


<firstName>Jeffrey</firstName>


<suffix />

<middleName />

<goesByName>Jeff</goesByName>

<formerName />







<employer>Navini Networks</employer>

<school />

<formerChurch>Richardson Church of the

Nazarene</formerChurch>



<statusComment />

<barCode />



<solicit />

<thank>true</thank>


<lastMatchDate />

<createdDate />




<userId>JefeD</userId>

<password>howGreatisOurGod</password>

<passwordHint />

<passwordAnswer />

</weblink>

<attributes>






<comment />

<startDate />

<endDate />



<lastUpdatedDate />

</attribute>

</attributes>

<addresses />

<communications />

</individual>


individualCode="jfVB7w0OgmUj21ejqtL19A==">

<title />

<salutation />


<firstName>Tara</firstName>

People Methods

63


<suffix />

<middleName />

<goesByName />

<formerName />





<occupation />


<employer>Fellowship Technologies</employer>

<school />





<statusComment />

<barCode />



<solicit />

<thank>true</thank>


<lastMatchDate />

<createdDate />




<userId>TaraC</userId>

<password>howGreatThouArt</password>

<passwordHint />

<passwordAnswer />

</weblink>

<attributes>






<comment />

<startDate />

<endDate />



<lastUpdatedDate />

</attribute>

</attributes>

<addresses />

<communications />

</individual>

</individuals>

</household>

</data>

</tns:dataRequest>

Data Exchange 2.0

64

UpdateHouseholdCollection

Use UpdateHouseholdCollection to update several households and the individuals within these households at once. The parameters are exactly the same as those found in UpdateHousehold

with the added entity of <households>.

Building UpdateHouseholdCollection

UpdateHouseholdCollection is a good update to run the day after an event. For example, if you

have several families who visited for the first time on the previous day, you may have several individuals with the status “New checkin”.

Note:

The “New checkin” status is automatically assigned when an individual is added through Fellowship One Check-in.

You can first use GetHouseholdCollection to return all households with the lastActivityDate of

the prior day. Next, modify all individuals within the return results to update their status to something more appropriate like “Visitor” or whatever status you use for first time visitors.

To build UpdateHouseholdCollection, use the following in your method:

• Remember to first query for the households using GetHouseholdCollection. You will need the householdCode or householdSourceCode for each household you want to modify. Any household that does not have one of these numbers is treated as “New” by

Fellowship One

• Change all UnChanged entityStates to “Modified” or “Added” as appropriate. Any entityState equal to UnChanged is ignored during the update

• Add your authentication header to the beginning of your XML string


<tns:dataRequest xmlns:tns='UpdateHousehold'>





<method>UpdateHousehold</method>




<data>

<households>


householdCode='h/20hJ0h23NUzJHIPxsJvw=='>

<householdName>James and Deborah Jones</householdName>

<householdFirstName>James and Deborah</householdFirstName>

<householdSortName>Jones</householdSortName>

<addresses>

<address entityState="Modified">


<address1>11756 Dallas Dr.</address1>

<address2>#4C</address2>

<address3 />

<city>Dallas</city>



People Methods

65


<uspsVerified>True</uspsVerified>



</address>

</addresses>

<communications>





</communication>

</communications>

<individuals>



<title />

<salutation />


<firstName>James</firstName>

<lastName>Jones</lastName>

<suffix />

<middleName />

<goesByName>Jimmy</goesByName>

<formerName />





<occupation>Architect</occupation>


<employer />

<school />

<formerChurch />

<status>Attendee</status>


<statusComment />

<barCode />



<solicit />

<thank>true</thank>


<lastMatchDate />

<createdDate />




<userId />

<password />

<passwordHint />

<passwordAnswer />

</weblink>

<attributes />

<addresses />

<communications />

</individual>



<title />

<salutation />


<firstName>Deborah</firstName>

Data Exchange 2.0

66

<lastName>Jones</lastName>

<suffix />

<middleName />

<goesByName />

<formerName>Gardner</formerName





<occupation />


<employer />

<school />

<formerChurch />

<status>Attendee</status>


<statusComment />

<barCode />



<solicit />

<thank>true</thank>


<lastMatchDate />

<createdDate />




<userId>DebbieJ</userId>

<password>PTL456</password>

<passwordHint />

<passwordAnswer />

</weblink>

<attributes />

<addresses />

<communications />

</individual>

</individuals>

</household>


householdCode='tRGMM19OWl/GCT4QmS1q0w=='>

<householdName>Jeff and Tara Coulson</householdName>

<householdFirstName>Jeff and Tara</householdFirstName>

<householdSortName>Coulson</householdSortName>

<addresses>

<address entityState="Modified">


<address1>1234 Deer Horn Dr.</address1>

<address2 />

<address3 />

<city>Plano</city>




<uspsVerified>False</uspsVerified>



</address>

</addresses>

<communications>




People Methods

67


</communication>

</communications>

<individuals>



<title />

<salutation />


<firstName>Jeffrey</firstName>


<suffix />

<middleName />

<goesByName>Jeff</goesByName>

<formerName />







<employer>Navini Networks</employer>

<school />





<statusComment />

<barCode />



<solicit />

<thank>true</thank>


<lastMatchDate />

<createdDate />




<userId>JefeD</userId>

<password>howGreatisOurGod</password>

<passwordHint />

<passwordAnswer />

</weblink>

<attributes>






<comment />

<startDate />

<endDate />



<lastUpdatedDate />

</attribute>

</attributes>

<addresses />

<communications />

</individual>



Data Exchange 2.0

68

<title />

<salutation />


<firstName>Tara</firstName>


<suffix />

<middleName />

<goesByName />

<formerName />





<occupation />


<employer>Fellowship Technologies</employer>

<school />





<statusComment />

<barCode />



<solicit />

<thank>true</thank>


<lastMatchDate />

<createdDate />




<userId>TaraC</userId>

<password>howGreatThouArt</password>

<passwordHint />

<passwordAnswer />

</weblink>

<attributes>






<comment />

<startDate />

<endDate />



<lastUpdatedDate />

</attribute>

</attributes>

<addresses />

<communications />

</individual>

</individuals>

</household>

</households>

</data>

</tns:dataRequest>

People Methods

69

Running Data Import

When you have built your XML strings you are ready to use Data Import, there are three ways you can access Data Import:

• Consume the Data Exchange Web service programmatically. The following example

shows the XML string embedded within a function in a Web application written on the .NET platform.

private void Page_Load(object sender, System.EventArgs e)

{

if(IsPostBack){

string sXML;

sXML=@”<tns:dataRequest

xmlns:tns=’UpdateIndividual’><authenticateHeader>

<churchCode>**3nZBBhep7s1NOASDEmig==</churchCode>

<user>tcoulson</user><password>******</password>


<version>2.0</version><methodGroup>People</methodGroup></authenticateH

eader><data>

<individual entityState='Modified' individualSourceCode=''

individualCode='+S3R2JpQbDoiKeBZAVUF7g=='> <prefix>Mr.</pre

fix>

<firstName>Kenneth</firstName> <lastName>Ukoha</lastName

>

<middleName>James</middleName><goesByName>Ken</goesByName>

<formerName></formerName><gender>Male</gender>

<dateOfBirth>1997-01-23T00:00:00.0000000-06:00</dateOfBirth>

<maritalStatus>Child/Yth</maritalStatus>

<householdMemberType>Child</householdMemberType>

<occupation></occupation><status>Member</status>

<attributes><attribute entityState='Added'>

<attributeName>Baptism</attributeName></attribute>

</attributes><addresses><address entityState=’Added’>

<addressType>College</addressType><address1>123 College

Way</address1><address2></address2><city>University</city>

<postalCode>11125</postalCode><country>USA</country>

<stProvince>TX</stProvince></address></addresses>

<communications><communication entityState='Added'>



<listed>true</listed></communication></communications>

</individual></data></tns:dataRequeset>

DataRequest.DataRequest dr=new DataRequest.DataRequest();

Object oDoc = new Object();

XmlDocument xDoc - new XmlDocument();

XmlNode xNode;

oDoc = dr.Request(sXML);

xNode = (XmlNode)oDoc;

xDoc.LoadXml(xNode.OuterXml);

Response.Write(xNode.OuterXml);

}

}

Data Exchange 2.0

70

• Access Data Exchange - Import directly through ASMX:


• Accessing Data Exchange - Import People through Fellowship One. (Admin tab, Data Exchange and Data Import menu options).

People Methods

71

Data Import through Fellowship One

The Import People feature in Fellowship One allows you to upload your import request XML string directly to Fellowship One. Once uploaded, the file status is changed to “In Queue” and is

executed in “first in first out” (FIFO) order.

Your results are displayed in a new browser window as shown below:

If the import fails, a message appears in the browser window describing what failed in the import.

Data Exchange 2.0

72

To request an import via Fellowship One


2. Click Data Exchange and Data Import in the menu options. The Data Import page appears.

3. Click Browse. The Choose File dialog box appears.

4. Browse to and select the XML file to upload and click Open. The path and file name appear in the Data Import field.

People Methods

73

5. Click Run Import. A new Internet browser window opens with the results of your method and query parameters.

6. Close the results.

7. Click Refresh to review the details of your request.

Data Exchange Import Grid

The Data Exchange People Imports grid (as shown below) includes information about every

import requested and executed.

The following table details the different aspects of the People Imports table.

Data Exchange People Import

Item Description

Run Export Click to run the export. Results appear in a new browser window

View Request Click to view the original XML request. The XML file appears in a new browser window

View Results Click to view the results of the XML request. The file appears in a new browser window.

Import Method Name Click to view the schema associated with the method. The schema appears in a new browser window

Date Executed The timestamp associated with the last run of the import

request

Portal User The user ID included in the XML file.

Data Exchange 2.0

74

Item Description

Status

The status of the import request:

• In Queue—the request is waiting to be processed.

• Complete—the request has been completed and all

items completed with no errors

• Incomplete—one or more items failed the import request

• Failed—all items in the collection failed

# Complete The number of items that completed

# Incomplete The number of items that did not complete the import request

# Failed The number of items that failed the import request

75

Util Methods

Two utility methods are included with Data Exchange—GetSchema and GetRequestStatus. GetSchema is the method that is run to export the schema for a Get or Update method while

GetRequestStatus is typically used by a program to fetch the status of an update request.

GetSchema

The GetSchema method is used to export the schemas for all of the Data Exchange methods. It is important to export the schemas for two reasons. First, the schema describes all the entities

and nodes available in each method as well as which can be queried by and which are view only. Next, it gives the correct hierarchical order for the XML file.

See Export the schemas for step-by-step instructions for exporting.

GetRequestStatus

The GetRequestStatus method is used by sophisticated programs to retrieve the status of an Update request. When using the Fellowship One interface, this method is not necessary as the status can be viewed in the People Import grid. The results of the Update request can be

displayed by clicking the View Results link.

When programming, the GetRequestStatus method can also be used as an event handler to catch exceptions if any occur during the Update request. As shown in the file below, the exceptions can be caught and handled programmatically.

GetRequestStatus can be accessed using the string shown in the following example:


<tns:dataRequest xmlns:tns="GetRequestStatus">





<method>GetRequestStatus</method>


<methodGroup>Util</methodGroup>


<parameters>

<methodName>GetHouseholdCollection</methodName>

</parameters>

</tns:dataRequest>

Data Exchange 2 - Fellowship Onedeveloper.fellowshipone.com/downloads/Data_Exchange_2_0.pdf · 1...

Documents

Transcript of Data Exchange 2 - Fellowship Onedeveloper.fellowshipone.com/downloads/Data_Exchange_2_0.pdf · 1...