diff --git a/README.md b/README.md index 635fef7..60025fa 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,84 @@ -# de.forumzfd.twinglecampaign +# Twingle Campaign -![Screenshot](/images/screenshot.png) +![Screenshot](images/screenshot.png) -(*FIXME: In one or two paragraphs, describe what the extension does and why one would download it. *) +This extension allows you: + +- to manage [Twingle](https://www.twingle.de/) projects and events as campaigns in CiviCRM (including almost all + donation form settings) +- to automatically assign donations that arrive via Twingle donation forms to the corresponding campaign +- to track the origin of your donations The extension is licensed under [AGPL-3.0](LICENSE.txt). ## Requirements -* PHP v7.0+ -* CiviCRM (*FIXME: Version number*) +* PHP v7.2+ +* CiviCRM 5.14+ +* Extension: [Twingle API](https://github.com/systopia/de.systopia.twingle) +* Extension: [Campaign Manager](https://github.com/systopia/de.systopia.campaign) +* Extension: [Extended Contact Matcher (XCM)](https://github.com/systopia/de.systopia.xcm) -## Installation (Web UI) +The **[Twingle API](https://github.com/systopia/de.systopia.twingle)** allows you to receive API calls from Twingle to +create donations. The **Twingle Campaign** extension enhances this functionality by automatically creating campaigns for +each donation form (project) and peer-to-peer event and assigning the incoming donations to them. While you can use +the **Twingle API** extension on its own, there is no point in using the **Twingle Campaign** extension without the +other. -This extension has not yet been published for installation via the web UI. +The **[Campaign Manager](https://github.com/systopia/de.systopia.campaign)** is required to visualize the projects and +events within the campaign tree as parent and child campaigns. -## Installation (CLI, Zip) +The **[XCM](https://github.com/systopia/de.systopia.xcm)** is needed to match or create contacts for people which start +a peer-to-peer event. -Sysadmins and developers may download the `.zip` file for this extension and -install it with the command-line tool [cv](https://github.com/civicrm/cv). +## Concept -```bash -cd -cv dl de.forumzfd.twinglecampaign@https://github.com/FIXME/de.forumzfd.twinglecampaign/archive/master.zip -``` +The idea of the **Twingle Campaign** extension is to represent Twingle donation forms (projects) and peer-to-peer events +as campaigns in CiviCRM. Therefore, the extension creates new campaign types: -## Installation (CLI, Git) +- [Twingle Project](docs/Twingle_Project.md) +- [Twingle Event](docs/Twingle_Event.md) -Sysadmins and developers may clone the [Git](https://en.wikipedia.org/wiki/Git) repo for this extension and -install it with the command-line tool [cv](https://github.com/civicrm/cv). +There is another campaign type: [Twingle Campaign](docs/Twingle_Campaign.md) +Please don't get confused: this campaign type is named after this extension because it's a really clever thing that +allows you to track the origin a donation. -```bash -git clone https://github.com/FIXME/de.forumzfd.twinglecampaign.git -cv en twinglecampaign -``` +![Concept](images/Concept.png) -## Usage +Together with normal campaigns, the three Twingle campaign types can be used to build complex campaign trees. This +allows you to keep track of the performance of every single donation form, peer-to-peer event and newsletter (with +TwingleCampaign cid link) while it sums up all donations in the parent campaigns. -(* FIXME: Where would a new user navigate to get started? What changes would they see? *) +![Campaign Trees](images/Campaign_Trees.png) + +To assign the incoming donations to the corresponding campaigns, the *Twingle Campaign* extension uses +an [API Wrapper](docs/API_Wrapper.md) that extends the function of the **Twingle API** (extension). + +## Configuration + +Bevore you can synchronize your Twingle projects and events, you have to enter your Twingle API key on the Twingle +Campaign Configuration page. + +![Extension Settings](images/extension_settings.png) + +If you would like to match or create contacts for event initiators (people who start their own peer-to-peer event) via +the XCM, make sure to create a [new XCM configuration](docs/Example Settings/XCM_profile.md) for this purpose. + +On default, this extension will synchronize all Twingle projects and events once every hour. You can increase or +decrease this interval by changing the configuration of the scheduled job named *TwingleSync*. + +![Scheduled Job](images/scheduled_job.png) + +Furthermore, the synchronization may get triggered also if a donation for an unknown event arrives via the Twingle API +extension. ## Known Issues -(* FIXME *) +- The **Campaign Manager** displays a *«Campaign XY has been saved»* message even if the input validation failed and the + campaign was **not saved or sent** to Twingle. + +## To Do's + +- [ ] Make the Twingle Event Settings for contact matching, case creation and creation of soft credits an individual + setting in each project +- [ ] Make more payment methods available \ No newline at end of file diff --git a/docs/API_Wrapper.md b/docs/API_Wrapper.md new file mode 100644 index 0000000..735dc9d --- /dev/null +++ b/docs/API_Wrapper.md @@ -0,0 +1,15 @@ +# API Wrapper + +The **Twingle API** extension uses profiles to process every incoming donation. When Twingle calls the +*TwingleDonation.submit* API, provided by the **Twingle API** extension, the API assigns the donation to the +corresponding profile by looking up the project id which comes with the call. The profile settings then specifies how +the donation should be treated. + +![TwingleDonation.submit](../images/TwingleDonation.submit.png) + +The **Twingle Campaign** extension puts an API wrapper around the *TwingleDonation.submit* API. This first it searches +the call for either a project id, an event id or a campaign id and depending on the result, it searches CiviCRM for the + +![API Wrapper](../images/API_Wrapper.png) + +Furthermore, the API wrapper enables you to create soft credits for peer-to-peer event initiators. \ No newline at end of file diff --git a/docs/Example Settings/XCM_profile.md b/docs/Example Settings/XCM_profile.md new file mode 100644 index 0000000..77cbbf2 --- /dev/null +++ b/docs/Example Settings/XCM_profile.md @@ -0,0 +1,13 @@ +# XCM example settings +The contact information that Twingle provides about the peer-to-peer event initiators are: +- First Name +- Last Name +- Email + +So make sure you set only these fields as rules for matching. + +![XCM Settings](../../images/XCM_settings.png) + + + + diff --git a/docs/Twingle_Campaign.md b/docs/Twingle_Campaign.md new file mode 100644 index 0000000..77aaaa5 --- /dev/null +++ b/docs/Twingle_Campaign.md @@ -0,0 +1,15 @@ +# Twingle Campaign + +The *Twingle Campaign* campaign type does, unlike the other campaign types (*Twingle Project* & *Twingle Event*), not +represent an entity on the Twingle side. + +The *Twingle Campaign* is can be used to track the origin of a donation. In order to achieve this, it takes the URL of +it's *Twingle Project* parent campaign and adds a `cid` parameter to its end that will be sent to Twingle and back. With +the `cid` coming back from Twingle via API call to *TwingleDonation.submit* (provided by the **Twingle API** extension) +the donation can get assigned to the originally *Twingle Campaign*. + +**Attention:** The *Twingle Campaign* must always be the child (or grandchild) of a *Twingle Project*. + +You can use the *Twingle Campaign* url for example for newsletters or social media posts. The url will lead the users to +the Twingle donation form of the parent *Twingle Project* but thanks to the `cid`, the donation will be assigned to +the *Twingle Campaign*. \ No newline at end of file diff --git a/docs/Twingle_Event.md b/docs/Twingle_Event.md new file mode 100644 index 0000000..8780308 --- /dev/null +++ b/docs/Twingle_Event.md @@ -0,0 +1,9 @@ +# Twingle Event + +The *Twingle Event* campaign type represents peer-to-peer events created by users. The campaigns get synchronized +between Twingle and CiviCRM in only one direction: from Twingle to CiviCRM. There is no need to synchronize them through +the other direction, because usually it is not necessary to change their values. *Twingle Events* are created by users +through a *Twingle Project* of type event. + +You can activate the creation of soft credits for event initiators. In this case a donation by person A will be linked +as soft credit to person B which is the event initiator. \ No newline at end of file diff --git a/docs/UML/Campaigns.png b/docs/UML/Campaigns.png new file mode 100644 index 0000000..e4761ff Binary files /dev/null and b/docs/UML/Campaigns.png differ diff --git a/docs/UML/Campaigns.uml b/docs/UML/Campaigns.uml new file mode 100644 index 0000000..59cad08 --- /dev/null +++ b/docs/UML/Campaigns.uml @@ -0,0 +1,36 @@ + + + PHP + \CRM_TwingleCampaign_BAO_Campaign + + \CRM_TwingleCampaign_BAO_TwingleCampaign + \CRM_TwingleCampaign_BAO_TwingleEvent + \CRM_TwingleCampaign_BAO_TwingleProject + \CRM_TwingleCampaign_BAO_Campaign + + + + + + + + + + + + + + + + + + + \CRM_TwingleCampaign_BAO_Campaign + + + Fields + Methods + + private + + diff --git a/docs/UML/Custom_Data.png b/docs/UML/Custom_Data.png new file mode 100644 index 0000000..ba6be0c Binary files /dev/null and b/docs/UML/Custom_Data.png differ diff --git a/docs/UML/Custom_Data.uml b/docs/UML/Custom_Data.uml new file mode 100644 index 0000000..72bc3fe --- /dev/null +++ b/docs/UML/Custom_Data.uml @@ -0,0 +1,20 @@ + + + PHP + \CRM_TwingleCampaign_BAO_CampaignType + + \CRM_TwingleCampaign_BAO_CampaignType + \CRM_TwingleCampaign_BAO_CustomField + \CRM_TwingleCampaign_BAO_OptionValue + + + + + + + Fields + Methods + + private + + diff --git a/images/API_Wrapper.png b/images/API_Wrapper.png new file mode 100644 index 0000000..0f7e80c Binary files /dev/null and b/images/API_Wrapper.png differ diff --git a/images/Campaign_Trees.png b/images/Campaign_Trees.png new file mode 100644 index 0000000..d9c9bd5 Binary files /dev/null and b/images/Campaign_Trees.png differ diff --git a/images/Concept.png b/images/Concept.png new file mode 100644 index 0000000..1f97e9e Binary files /dev/null and b/images/Concept.png differ diff --git a/images/TwingleDonation.submit.png b/images/TwingleDonation.submit.png new file mode 100644 index 0000000..a9aeb16 Binary files /dev/null and b/images/TwingleDonation.submit.png differ diff --git a/images/Twingle_API_Extension.png b/images/Twingle_API_Extension.png new file mode 100644 index 0000000..462a2a4 Binary files /dev/null and b/images/Twingle_API_Extension.png differ diff --git a/images/Twingle_Campaign_Wrapper.png b/images/Twingle_Campaign_Wrapper.png new file mode 100644 index 0000000..2006c69 Binary files /dev/null and b/images/Twingle_Campaign_Wrapper.png differ diff --git a/images/XCM_settings.png b/images/XCM_settings.png new file mode 100644 index 0000000..1042e0c Binary files /dev/null and b/images/XCM_settings.png differ diff --git a/images/extension_settings.png b/images/extension_settings.png new file mode 100644 index 0000000..cc7cae8 Binary files /dev/null and b/images/extension_settings.png differ diff --git a/images/scheduled_job.png b/images/scheduled_job.png new file mode 100644 index 0000000..7532a5e Binary files /dev/null and b/images/scheduled_job.png differ diff --git a/images/screenshot.png b/images/screenshot.png index 6765b69..12c0c96 100644 Binary files a/images/screenshot.png and b/images/screenshot.png differ