Person Element

Minimum Person Data

A basic Person element has the following structure:

<Person uuid="" primary="true">
    <Organization uuid="xxx" />
    <FirstName>Bob</FirstName>
    <LastName>Smith</LastName>
    <Gender>male</Gender>
</Person> 

The "primary" attribute indicates whether this person should be considered the primary household member (sometimes referred to as the Head of Household). Only one person should be set as the primary member. For individuals this should be set to true.

Person UUID

Generally speaking all Person elements must have a UUID generated via the guidelines detailed at UUID Requirements and Format.

However if your data meets the following criteria:

• You have been given permission by Link2Feed, and
• If there are no relationships to be defined, and
• If there are no Activities to be recorded, and
• Updating records is not needed

The UUID may be left out.

Optional Person Elements

There are many optional elements for a Person element. The main ones intended for external users are:

• MiddleName
• NickName
• FirstFoodBankVisit
• ReferredBy
• ReferredByOther
• ContactInfo

The following are reserved for Link2Feed and should not be used:

• LastProfileReview
• NextProfileReview
• NextProfileReviewReason

FirstFoodBankVisit

This optional element is used to record when the Person first received food bank assistance in their lifetime - it is not the first time they received assistance from your Network, but when the first used any food banks services. It is used for reporting purposes and tracking new users vs repeat users.

ReferredBy / ReferredByOther

These fields are used to track how the Person came to the Organization specified in the Organization element. The ReferredBy value is defined in the XSD and is controlled by the Network settings. If "Other" is supported, ReferredByOther can be used to detail information about the initial referral. It should be a short text label of no more than 255 characters.

If ReferredBy is not tracked by your Network, you should not use this option.

Contact Information

The contact information section allows multiple contact methods to be specified for each Person. This can include email addresses and phone numbers. An example follows:

<ContactInfo>
    <PhoneNumbers>
        <PhoneNumber type="home" primary="true">
            <SubscriberNumber>1234567890</SubscriberNumber>
            <!-- Optional extension -->
            <Extension>1234</Extension>
        </PhoneNumber>
        <PhoneNumber type="work" primary="false">
            <AreaCode>123</AreaCode>
            <Exchange>456</Exchange>
            <Suffix>7890</Suffix>
            <!-- Optional extension -->
            <Extension>0123</Extension>
        </PhoneNumber>
    </PhoneNumbers>
    <EmailAddresses>
        <EmailAddress type="personal" primary="false">bob@example.com</EmailAddress>
    </EmailAddresses>
</ContactInfo> 

ContactInfo is split into PhoneNumbers and EmailAddresses. For each section one record can be set as the primary contact type. The type attribute on both indicates whether the phone number or email address is work, home, personal etc.

Phone Numbers

Phone numbers can be defined in two formats:

1. As a subscriber number
2. Broken down in components

The extension is optional and allowed in both formats. Extension should only include the numbers 0-9.

Subscriber Number

The SubscriberNumber should contain a fully qualified phone number without any form of markup e.g. North American phone numbers are usually written using some form of:

• 1 (XXX) YYY-ZZZZ

This should be entered as:

• 1XXXYYYZZZZ

Generally there should only be the numbers 0-9 and + (plus). Fully international numbers are allowed e.g.: +1519YYYZZZZ.

Components

Most phone numbers can be expressed as a combination of:

• An area code
• Local exchange
• The local line number / suffix

For North American numbers and using the same conventions used in Subscriber Number, this would be:

• XXX - Area code e.g. 888
• YYY - local exchange e.g. 123
• ZZZZ - local number

For countries that do not separate numbers in this format, use the SubscriberNumber element.

Income and Social Program Information

An individuals income can be hinted or specified together with any social programs that they are actively claiming - if these have been enabled on the Network.

Income Sources

Multiple income sources can be defined, along with the value of each of these sources. While the same type of income can be used multiple times, it is generally recommended to only use each type once. The income sources has the following structure:

<IncomeSources>
    <Income type="full_time_employment" primary="true">
        <Value currency="USD">0.00</Value>
    </Income>
    <Income type="other" primary="false">
        <Value currency="USD">0.00</Value>
        <OtherDescription>Some other income type</OtherDescription>
    </Income>
</IncomeSources>

The "type" attribute is set by the Network and is defined in the XSD. Only the values listed in the XSD should be used for the type. If there is an "other" type, then the element OtherDescription can be added with a description of the income source. This covers any sources that are not actively being tracked by the Network.

One of the income types can be flagged as primary="true", this indicates it is the primary income source for this Person. Only one item should be marked as primary.

The Value element is required even if there is no value. This should include the currency attribute and, if no income amount is tracked, entered as 0.00. This is still required even if the type is "no_income". The currency is the ISO code, and is defined in the XSD.

Social Programs

The social programs is simply a list of all social programs that the Person currently receives. The social program type is defined in the XSD and is set by the Network. If there are no SocialProgramTypes defined in the XSD it should not be added. The social program element is:

<SocialPrograms>
    <SocialProgram>commodity_supplemental_food_program_csfp</SocialProgram>
    <SocialProgram>medicaid</SocialProgram>
</SocialPrograms>

Defining Relationships Between People

The relationships between household members, if recorded, can be added to the Person records. For this to work your Person elements MUST use valid UUIDs.

These are then defined by adding a Relationships element with the appropriate relationship with the Person specified. The basic form is as follows:

<Relationships>
    <Relationship type="child" person="UUID"/>
</Relationships>

There are two attributes, both are required:

• type: the type of the relationship, is this person a child, parent, etc of the current person
• person: the UUID of the person the relationship is with.

When relationships are created, the reciprocal is automatically created. For example: if you have a Household with 3 people where the primary is the parent and the other two are children, you only need to set the parent->child on the main person as the children will automatically get the inverse child->parent created as the XML is processed. If you know the relationship between the children this could be added to one of the children as a sibling.

The following simplified code fragment demonstrates this:

<Household uuid="00001">
    <HouseholdMembers>
        <Person uuid="123" primary="true">
            <FirstName>Bob</FirstName>
            <Relationships>
                <Relationship type="child" person="456"/>
                <Relationship type="child" person="789"/>
            </Relationships>
        </Person>
        <Person uuid="456" primary="false">
            <FirstName>Sally</FirstName>
            <Relationships>
                <Relationship type="sibling" person="789"/>
            </Relationships>
        </Person>
        <Person uuid="789" primary="false">
            <FirstName>Sue</FirstName>
        </Person>
    </HouseholdMembers>
</Household> 

Demographic Information

Demographic information is for recording a range of information about a Persons ethnicity, self identity etc. There are a number of options with a full demographic element looking like:

 <DemographicData>
    <Citizenship>american</Citizenship>
    <Education>
        <HighestLevel>associate_degree</HighestLevel>
        <Country>USA</Country>
    </Education>
    <EmploymentStatus>full_time</EmploymentStatus>
    <Ethnicities>
        <!-- Ethnicity defined in XSD, multiple allowed -->
        <Ethnicity>aleut_or_eskimo</Ethnicity>
    </Ethnicities>
    <Languages>
        <!-- Spoken languages, defined in XSD -->
        <Language>English</Language>
    </Languages>
    <SelfIdentifiesAs>
        <!-- Self identifies as, defined in XSD -->
        <SelfIdentity>none</SelfIdentity>
    </SelfIdentifiesAs>
</DemographicData>

All elements within demographic information are optional and depending on Network settings. All allowed values for each section are defined in the XSD.

Multiple items are allowed for:

• Ethnicity
• SelfIdentity
• Language

There can only be a single Citizenship, Education and Employment elements.

Education

Education records two aspects: the highest level of education achieved / completed and optionally the country this was completed in. Both of these are Network tracking options and may not be in use.

The HighestLevel of education values may not translate directly to your countries standard levels. If in doubt please contact Link2Feed for guidance, or consult the following table that gives an approximate usage. The XSD Value is what you must supply, and the columns indicate what will be displayed on the Intake pages and in reporting.

~ means not used.