Information Architecture¶

This section contains Information Architecture for the Falcon project. It helps to understand the relationships between entities alongside with their key fields and design choices.

Donations¶

Appeal¶

Appeal is a revisionable node, which represents content for Appeal Landing Page, alongside with settings for the donation form and Thank You Landing Page / Email. Here’s the list of key fields divided into groups on the edit form:

General Appeal Information:
	Title [title] - required textfield determines the Appeal’s title. Uses default Drupal’s node title field. Related Countries [related_countries] - optional entity reference field to Country entity (TODO: Add a link to the entity structure when exists in the doc). Related Key Programme Areas [related_key_areas] - optional entity reference field to Key Programme Area entity (TODO: Add a link to the entity structure when exists in the doc). Path [path] - Fieldable mirror of default Drupal’s URL field built in for decoupled filtering by path via JSON API. Hidden from users on the edit form. Published [status] - Appeal publishing state. Uses default Drupal’s node publish flag.
Appeal Landing Page:
	Body blocks [blocks] - Optional unlimited list of paragraphs. Each paragraph determines visible content block on the appeal landing page. Each appeal comes with several default paragraphs by default for easier and faster appeal creation.
Donation Form:	This section defines behavior of donation form on the appeal’s landing page. Allowed donation types [donation_type] - Required select field with 2 pre-defined options: “Single Donation” and “Recurring Donation”. Allows to select either one or two options. Min donation amount [donation_min_amount] - Required integer field with default value set to 0. Determines minimal amount which a user should be able to donate to the given appeal. Suggested amounts [donation_suggested_amounts] - Optional integer mutiple field with up to 3 values. Each of the values defines the suggested amount to donate on the form next to the donation amount input textfield.
Source Codes:	Note: This section is relevant only when `Falcon ThankQ` integration is enabled. This section uses Inline Entity Form to embed Source Code entity inline as a multiple unlimited field. Each Source code entity has the following set of fields: ThankQ Source Code [source_code] - Required text field which defines source code fetched from ThankQ CRM. Label - Required text field which defines human readable label on the frontend which matches the Source Code. Active on - Optional date range field, which defines when the current source code may be shown on the donation form.
Thank You Landing Page:
	This section defines content which will be shown on the Thank You page after successful donation. Title [thankyou_page_title] - Required text field. Defines page title for the Thank You page. Body blocks [thankyou_page_blocks] - Optional paragraphs list. Defines content blocks for the Thank You landing page.
Thank You Email:
	This section defines content of email which will be send when donation is completed by a donor. Email subject [thankyou_email_subject] - Required text field which allows to use Drupal tokens. This field defines title of thank you email. Email body [thankyou_email_body] - Required rich text field which allows to use Drupal tokens. This field defines content of thank you email.

Commercial part of Donations¶

This section describes IA of Commerce system which supports Donations in Falcon.

Commercial part of Donations is based on Drupal Commerce module. All default commerce entities generated by this module get deleted upon installation of Falcon Commerce module.

Order Item type:
Store:	There is a single General Store available for all commerce operations on the backend.
Order types:	Donations has its own Order type called Donation. Here’s list of fields: Order items [order_items] - Default Commerce reference to the list of order items. UID [uid] - Default Commerce reference to the user account of a donor who has donated. The user account is generated upon donation automatically. Mail [mail] - Default Commerce email field which stores Donor’s email. Billing address [billing_profile] - Default Commerce entity reference to the customer’s profile. Note that the Customer Profile is of a new bundle for the donations feature. State [state] - Default Commerce state field defined by Order Workflow. Note that Order Workflow is custom for the donations feature. Appeal [appeal] - Required Entity Reference to the Appeal which was used to submit the order. Source code [source_code] - Optional text field which defines the source code of a donor who submitted the donation. It is done as text field and not the reference field as we need to capture the source code that was there when the user submitted the form (as source codes are editable and can be changed by editors/managers).
Order workflow:	NOTE: Drupal Commerce doesn’t allow order workflows without draft state and without place transition. The system defines only 1 workflow called Donation with the following states: Draft Completed Canceled
	There is single order item type Donation [donation]. Every Order Item defines the following fields: Purchaised Entity - Default Commmerce field with reference to the donation product. Quantity - Default Commerce field. In relation of Donations feature it always equals 1. Unit price - Default Commerce field which allows to override donation price. This field is used in Donations feature to override the Donations product price by the real donation amount. Donation type - Defines type of donation, either Single Donation [single_donation] or Recurring Donation [recurring_donation].
Product type:	The donation feature implementation defines only 1 product type called Donation with a single product also called Donation with a 0 price. This product is created automatically on Falcon installation and is used for adding to the Order Item with overriding of its price upon order creation. The single donation product has hard-coded product SKU donation which makes the interaction with it easier.
Product variation type:
	The donation feature implementation defines only 1 product type variation called Donation with a single product also called Donation with a 0 price. This product is created automatically on Falcon installation and is used for adding to the Order Item with overriding of its price upon order creation. The single donation product has hard-coded product SKU donation which makes the interaction with it easier.
Payment gateways:
	Default Drupal Commerce’s payment gateways.
Customer Profile:
	Donations implementation in Falcon extends the default Customer Profile type called Customer. This profile type allows for multiple profiles of the same type for the same user. It has the following fields: Address [address] - Default Commerce’s address field. TODO: need clarification on what fields are required here as address is complex field. Phone number [phone] - Phone number field. Allow Contact by Phone [contact_phone] - Optional boolean field which defines if this donor can be contacted via phone by charity’s staff. Allow Contact by SMS [contact_sms] - Optional boolean field which defines if this donor can be contacted via SMS by charity’s staff. Allow Contact by Email [contact_email] - Optional boolean field which defines if this donor can be contacted via Email by charity’s staff. Allow Contact by Post [contact_post] - Optional boolean field which defines if this donor can be contacted via physical post by charity’s staff.

Users¶

This section defines structure of user accounts & profiles within the system.

Email - default Drupal’s user email address.

Account name - default Drupal’s user account name field.

First Name - optional text field with donor’s First Name.

Last Name - optional text field with donor’s Last Name.

Status - default Drupal’s status field. All donors get their own user account, but status is set to 0 to restrict from authentication.