systopia/de.systopia.mutualaid

Fight Corona by organising mutual aid in your neighbourhood with this CiviCRM Extension!

de.systopia.mutualaid - Corona Aid Extension for CiviCRM

Fight Corona by organising mutual aid in your neighbourhood with this CiviCRM Extension!

Introduction

Corona crisis protection measures like social distancing and quarantine are hitting everyone hard and it's time to step up and help those in need. CiviCRM is the perfect tool to organize help and connect those in need with volunteers who are able to support them.

You can find a video on the concept HERE and a more detailed walkthrough and discussion HERE. Both are recordings from CiviCRM's COVID-19 Response LIVE Event.

Scope and Features

This CiviCRM extension enables organisations to connect people in need with local volunteers who are able to help. It provides configurable online forms for people in need and volunteers as well as a matching mechanism to connect individuals based on proximity and other attributes. It's main features are:

• two configurable online forms for people in need and volunteers
• a configurable confirmation email for people who fill out the form
• uses CiviCRM's built in geocoding feature
• a matching algorithm that connects people in need with volunteers via a relationship
• pre-configured reports to find and review matched contacts
• advanced contact matching using the Extended Contact Matcher Extension extension incl. a preconfigured profile
• Drupal only: 3 permissions: request for help, offer help for others, and administer MutualAid.

Installation and Prerequisites

You need a current CiviCRM instance and have admin privileges. Add the extension to CiviCRM via the UI or the regular extension installation routine described here. The extension has a dependency with the Extended Contact Matcher Extension which should be installed automatically when you install the Corona Aid Extension for CiviCRM.

You need to have geocoding in CiviCRM set up - information on how to do that can be found here. You should also have the CiviReport component enabled (/civicrm/admin/setting/component?reset=1). Any of your staff that is supposed to work with the features in CiviCRM needs appropriate permissions for viewing & editing contacts, accessing reports etc.

Configuration

1. Visit the configuration Page (Navigation-Menu >Mutual Aid >Configure), configure the fields you would like to use in the forms as well as if they should be mandatory and default values
2. If you want the forms to send out emails, set up an email template
3. Enter a text for the privacy agreement to be shown on your forms
4. Link to your forms from anywhere by using the static URLs for the "require assistance form" and the "offer assistance form"
5. Activate / configure the cronjob that triggers the matching mechanism
6. Drupal only: visit the permissions settings page and assign the MutualAid permissions to roles, i.e. 'request for help' for anonymous, "offer help' to authenticated users, and 'administer for MutualAid' to administrators.

• [Optional] If you want to provide help categories for your forms, configure these in the according option group ...
• [Optional] Create a landing page
• [Optional] Adapt the matching rules of XCM
• [Optional] adapt the reports created by the extension

Description & Usage

Whenever the matching algorithm is triggered by the cronjob or manually it will find the best match for each individual in the database which is looking for help and create a relationship of the type "Mutual Aid" between the two individuals. The matches are made based on proximity to each other and the number of matching help categories and (if applicable) spoken languages. If help categories and/or languages are used there needs to be at least one match for each.

The relationship will have the status "needs review" (custom field). Each time the algorithm is executed it may replace relationships with the status "needs review" with better matches (but not relationships with other status').

You can find individuals in need and/or their matches using CiviCRM's built in search features or the preconfigured reports created by the extension. After reviewing the match (which may include contacting the individuals by phone or other means), you should set the relationship status to "confirmed", "communicated" or "cancelled". Once a relationship needs to be ended. you should set an end date to the relationship and change it's status to inactive (those are CiviCRM core features).

You can always create relationships and/or contacts manually if you need to.

Individuals with addresses that cannot be geocoded automatically either need manual geocoding (simply edit the address and add coordinates) or manual creation of a relationship with a matching individual.

The matching algorithm runs automatically according to your settings and/or can be triggered manually from the menu.

Remarks and Planned Features

If you think that we should add a feature to this extension, please create a detailed issue. Please be aware that we will try to keep this extension as straight forward as possible for the time beeing so we will only consider feature suggestions that seem to be of general interest. Of course, feel free to clone this repository and adapt it to your own needs if required or approach us if you want individual customizations.

Custom Forms

We used CiviCRM native forms to make the extension as accessible as possible. In case you want to create your own form you can do so and submit all the information to CiviCRM via it's REST API. All actions such as form submissions and running the matching algorithm are available via the API.

Automated communication

Currently, you will manually need to review relationships, change their status and communicate with the individuals. In case you want to automate this process (e.g. send out an email to helpers including contact details of their match) you could probably do so by using CiviRules or other CiviCRM features / extensions.

de.systopia.mutualaid's Issues

If a record is both offering and requesting help it creates an error in Match Now

Testing on 35 records - a couple were both offering and requesting and running Match Now created the error:

"CiviCRM_API3_Exception: "Matching failed: Duplicate Relationship".

If the only new records are coming through the forms then this probably isn't an issue as there's no way to create both a request and an offer together in the same record (only via import or adminastrator config).

But am guessing longer term there may be scenarios where the same person is both offering and requesting things.

Matching does not consider Maximum helpers per requesting person setting

According to @bjendres, this is not yet implemented, although the configuration setting exists.

Match Now gives a database error.

Have submitted a request for, and offer of, help – both records appear in the dbse with the correct custom fields. But when I click Match Now get the following error (am using Mutual Aid 1.1-alpha1, OCM 1.7-beta3 , Google Mapping/Geocoding):

CiviCRM_API3_Exception: "Matching failed: DB Error: unknown error"

#0 /Applications/MAMP/htdocs/drupal-7.69-civicrm/sites/default/files/civicrm/ext/de.systopia.mutualaid-1.1-alpha1/CRM/Mutualaid/Page/MatchNow.php(26): civicrm_api3("MutualAid", "match", (Array:1))
#1 /Applications/MAMP/htdocs/drupal-7.69-civicrm/sites/all/modules/civicrm/CRM/Core/Invoke.php(268): CRM_Mutualaid_Page_MatchNow->run((Array:3), NULL)
#2 /Applications/MAMP/htdocs/drupal-7.69-civicrm/sites/all/modules/civicrm/CRM/Core/Invoke.php(68): CRM_Core_Invoke::runItem((Array:13))
#3 /Applications/MAMP/htdocs/drupal-7.69-civicrm/sites/all/modules/civicrm/CRM/Core/Invoke.php(36): CRM_Core_Invoke::_invoke((Array:3))
#4 /Applications/MAMP/htdocs/drupal-7.69-civicrm/sites/all/modules/civicrm/drupal/civicrm.module(456): CRM_Core_Invoke::invoke((Array:3))
#5 /Applications/MAMP/htdocs/drupal-7.69-civicrm/includes/menu.inc(527): civicrm_invoke("mutualaid", "matchnow")
#6 /Applications/MAMP/htdocs/drupal-7.69-civicrm/index.php(21): menu_execute_active_handler()
#7 {main}

Sorry, due to an error, we are unable to fulfill your request at the moment. You may want to contact your administrator or service provider with more details about what action you were performing when this occurred.
Matching failed: DB Error: unknown error

Unknown column 'offers_help_3' in 'where clause'

As reported in #8, this error would come up, when certain help types are offered/present, but not enabled (any more).

Mutiple help types

If you want to use multiple help types you will have to use a 1.1 version, see e.g. here https://github.com/systopia/de.systopia.mutualaid/releases/tag/1.1-alpha1

Assign requests by waiting time or similar

Currently, the list of open help requests (people still needing help) for the matching is generated without any particular order. Especially if the help demand massively outweighs the supply (offers), it might be sensible introduce some kind of order, e.g.

• oldest requests first (that would require a new custom field)
• oldest contacts first (simply order by contact_id), but this has some drawbacks
• ...

Personal Contact Possible

"Personal Contact Possible" is a field in a help request. It is supposed to indicate whether a close contact is possible, which wouldn't be the case if the person in need is tested positive.

Since there has been some confusion about this, I'll rename it to "Physical Contact Possible"

Fields vanish on the config screen in some situations

Sorry this bug isn't more detailed - this is a behaviour I experienced once - and you can currently see it on the demo at: https://corona.civicrm.jaapjansma.nl/. Here it's the fields from Prefix until Lattitude (including address & name) that are missing ->

.pot file is out of date after new permissions

Commit #9 has introduced few new l10n strings, used in permissions mechanisms.

New .pot file and updated translation files are required to avoid authentication failures when MutualAid is running in one of the supported l10n languages.

Matching failed: Duplicate Relationship

@nicol reports:

"CiviCRM_API3_Exception: "Matching failed: Duplicate Relationship".

If the only new records are coming through the forms then this probably isn't an issue as there's no way to create both a request and an offer together in the same record (only via import or adminastrator config).
But am guessing longer term there may be scenarios where the same person is both offering and requesting things.

Zero help radius should not be allowed

Currently you can enter a help radius of 0.

Beta test help type matching

The first user of the extension was only using the general help type, so the matching for individual help types has not been properly tested yet.

Please get in contact if you do want to use this feature.

Class 'CRM_Xcm_Matcher_FirstNameAddressMatcher' not found

nicol reported here that there might be an install issue:

Error: Class 'CRM_Xcm_Matcher_FirstNameAddressMatcher' not found in CRM_Xcm_MatchingEngine->getMatchingRules() (line 182 of /files/civicrm/ext/de.systopia.xcm/CRM/Xcm/MatchingEngine.php

Create Cron-Job upon installation

add basic permissions

Add few permissions to:

• use request form
• use helper form
• administer mutualaid

Thx for the extension!

Create MKDocs documentation

This should also mention which fields are available and that adjusting Individual and Address fields on civicrm/admin/setting/preferences/display requires a cache clear before the configuration page is up to date. See #20

Issues with CiviCRM 5.27+

Unfortunately, CiviCRM 5.27 and following broke the compatibility of the CustomField API(3), see XCM-68 and CORE-1996.

If you're using CiviCRM 5.27 and up you will have to upgrade to XCM-1.8-alpha2 or higher to avoid the issue.

Report problematic cases

There should be a custom report to find the contacts that have a help request / help offfer, but

• aren't geocoded
• have a radius of 0
• have a maximum number of helpees of 0
• have only help requests/offers that are disabled

possible integration with civicase?

wondering what your thoughts are on integration this with civicase so each request can be tracked through a process until completion. local mutal aid folks have a very complex process that I'd like to replace with civicrm but it needs more ability to have someone check on the request; contact the person that made the request; pass that on to a volunteer that can fulfill the request, and then sometimes to another to deliver food or something, and then finally marked as complete.

before I start digging into your code, I wanted your feedback on this set of issues. how possible will it be within the methodology you have built?

Feature suggestion: Free HTML regions for quick UI/UX - dashboard, landing page & header

There's three features here, but depending how they were implemented perhaps they fit together (or perhaps they should be unique extensions). Two are more specifically for standalone installs not using any of the CMS they're installed within, like Spark, to let the user customise basic landing page & header. The other is a general admin dashlet that doesn't need to be end-user configurable. Maybe all three could for now maybe be rich text editor-generated regions?

1. Admin dashboard / dashlet - listing key links - not just within the extension but that may be of use within Civi, such as bulk email, as well as reference to help docs, community support, etc. Potentially, one day (v2!) could also summarise stats, like signups or matched/unmatched listings.

2. Landing page (standalone orientated) - provide a rich text editor to creaste a simple front-page for Mutual Aid Groups whose current web presence is either just a Facebook or Whats App group - and are using something like Spark to get forms & CRM up quickly. Could be free for the end-user to configure however they wish - contact info, code of conduct, useful links, update notices - could also have some set fields - ie name of group to ensure key info like group name and location is crawler-friendly.

3. Header/nav (standalone orientated) - a way to add a group name or logo in the header of each page, and for end users to add key links as a simple one-tier nav, ie pointing to forms or terms of service.

Improve matcher performance

Currently, the matcher deletes all "help provided" relationships in status "assigned" before generating new ones. It would be a lot more efficient to somehow use/amend the ones that are already there, and only delete the ones that are obsolete after the matching process.

Make Unconfirmed Matches report easier to find after clicking 'Match Now'? #enhancement

The Unconfirmed Matches report (ie /civicrm/civicrm/report/instance/38?force=1&reset=1) is within Reports which might be hard to find for a new comer.

To help with workflow, could it either be:

• added to the Mututal Aid menu?
• auto-redirected on clicking 'Match Now'

Matching should consider languages

There was the idea to not only to match people by help type offered/requested, but also by the languages they speak. Although there is some of that in the code, it's not properly implemented yet.

If somebody wants to use the feature, please get in contact with us.

Customising the forms

This might be something very trivial I am missing but I am not finding how to edit some fields in the forms that are not on the settings page. For instance it is now showing 'Supplemental address 1, 2, 3' as obligatory.
Where could I edit this? The only way I found was to deselect those in the general civicrm address options.

Required select fields accept "- None -" etc. as valid option

This produces errors like '0' is not a valid option for field county_id.

This applies to those fields:

• prefix_id
• suffix_id
• county_id
• state_province_id
• country_id

The extension uses 0 as value for those "- None -" or "- Select -" options. Instead, the empty string '' should be used.