diff --git a/README.md b/README.md index 9b4fec0..a24d097 100644 --- a/README.md +++ b/README.md @@ -1,160 +1,42 @@ # Twingle API -Extension to connect to the Twingle fundraising service via its API. +Twingle is a payment service provider that makes it possible to create donation +forms with various payment options and embed them on websites or integrate them +into your homepage. Interested parties can donate via known payment options ( +e.g. credit card, PayPal). The procedure is also set up and optimised for mobile +devices. If you want to use the Twingle fundraising service, you have to set up +a corresponding online account. -* [About Twingle](https://www.twingle.de/) +For further information about Twingle fundraising +see the [Twingle website](https://www.twingle.de/). -The extension is licensed under -[AGPL-3.0](https://github.com/systopia/de.systopia.twingle/blob/master/LICENSE.txt). +Twingle as fundraising service can be connected to CiviCRM via its API with the +extension **Twingle API**. + +## Features + +* Donations from Twingle can be automatically created as contributions in + CiviCRM and assigned to existing or new contacts and administered in CiviCRM. +* Supporters and contacts of donations can be managed in CiviCRM. +* Donations can be submitted with different payment statuses depending on the + payment type +* SEPA mandates can be created for one-off and recurring payments. +* Donors can be added into groups for receiving newsletters, mailings and + donation receipts. +* A memberships can be set up for a donor. +* Data can be entered in user-defined fields ## Configuration -### Configure Twingle +Following the successful installation of the Twingle API extension, there is +some configuration work to do in order to set up the smooth connection between +CiviCRM and Twingle fundraising service. -Please refer to the -[Twingle FAQ on using Twingle with CiviCRM](https://support.twingle.de/faq/de-de/9/46) -(currently only available in German). +You have to carry out the following configuration steps: -### Configure Extended Contact Matcher (XCM) - -Make sure you use an XCM profile with the option *Match contacts by contact ID* -enabled. - -Be careful when enabling the *"Change Primary Detail?"* option. While it might -appear useful to update even primary contact details, this might lead to a -loss of contact information due to the fact that along with a submission that -contains e.g. a PayPal donation the `user_country` is transmitted as the only -address detail. The `user_country` then will be treated by the XCM as a whole -new address. So the contact may end up with a new address that contains only -the country. - -### Configure CiviCRM - -- Go to the Administration console at `/civicrm/admin` -- Open "Twingle API Configuration" at `/civicrm/admin/settings/twingle` - -#### Configure CiviSEPA integration - -Open "Configure extension settings" at -`/civicrm/admin/settings/twingle/settings` and configure whether to integrate -with the [CiviSEPA](https://github.com/project60/org.project60.sepa) extension. - -This enables you to map incoming donations from Twingle with a specific payment -method (e.g. *debit_manual*) to be processed with CiviSEPA, that is, creating a -SEPA mandate and managing recurring payments. - -#### Configure profiles - -Open "Configure profiles" at `/civicrm/admin/settings/twingle/profiles`. - -The *default* profile is used whenever the plugin cannot match the Twingle -project ID from any other profile. Therefore the default profile will be used -for all newly created Twingle projects. - -| Label | Description | -|---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Profile name | Internal name, used inside the extension. | -| Project IDs | Twingle project IDs. Separate multiple IDs with commas. | -| Location type | Specify how the address data sent by the form should be categorised in CiviCRM. The list is based on your CiviCRM configuration. | -| Location type for organisations | Specify how the address data sent by the form should be categorised in CiviCRM for organisational donations. The list is based on your CiviCRM configuration. | -| Financial type | Specify which financial type incoming one-time donations should be recorded with in CiviCRM. The list is based on your CiviCRM configuration. | -| Financial type (recurring) | Specify which financial type incoming recurring donations should be recorded with in CiviCRM. The list is based on your CiviCRM configuration. | -| CiviSEPA creditor | When enabled to integrate with CiviSEPA, specify the CiviSEPA creditor to use. | -| Gender options | Specify which CiviCRM gender option the incoming Twingle gender value should be mapped to. The list is based on your CiviCRM configuration. | -| Record *Payment method* as | Specifiy the payment methods mapping for incoming donations for each Twingle payment method. | -| Double Opt-In | Let CiviCRM handle the double opt-in. Group memberships for newsletter mailing lists stay pending until the subscription gets confirmed. Note that this only works for public mailing lists. Any non-public mailing list will be ignored. Do not forget to disable Twingle's double opt-in option in the Twingle Manager. | -| Sign up for groups | Whenever the donor checked the newsletter/postal mailing/donation receipt checkbox on the Twingle form, the contact will be added to the groups listed here. | -| Assign donation to campaign | The donation will be assigned to the selected campaign. If a campaign ID is being submitted using the `campaign_id` parameter, this setting will be overridden with the submitted value. | -| Create membership of type | A membership of the selected type will be created for the Individual contact for incoming one-time donations. If no membership type is selected, no membership will be created. | -| Create membership of type (recurring) | A membership of the selected type will be created for the Individual contact for incoming recurring donations. If no membership type is selected, no membership will be created. | -| Contribution source | The configured value will be set as the "Source" field for the contribution. | -| Custom field mapping | Additional field values may be set to CiviCRM custom fields using a mapping. See the option's help text for the exact format. | - - -## API documentation - -The extension provides a new CiviCRM API entity `TwingleDonation` with API -actions to record a new donation, end a previously submitted recurring donation -and cancel previously submitted donation. - -### Submit donation - -This API action processes submitted Twingle donations and donor information. - -- Entity: `TwingleDonation` -- Action: `Submit` - -The action accepts the following parameters: - -| Parameter | Type | Description | Values/Format | Required | -|----------------------------------------|---------|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| -| `project_id` | String | The Twingle project ID | | Yes | -| `trx_id` | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes | -| `confirmed_at` | String | The date when the donation was issued | A string representing a date in the format `YmdHis` | Yes | -| `purpose` | String | The purpose of the donation | | | -| `amount` | Integer | The donation amount in minor currency unit | | Yes | -| `currency` | String | The ISO-4217 currency code of the donation | A valid ISO-4217 currency code | Yes | -| `newsletter` | Boolean | Whether to subscribe the contact to the newsletter group defined in the profile | | | -| `postinfo` | Boolean | Whether to subscribe the contact to the postal mailing group defined in the profile | | | -| `donation_receipt` | Boolean | Whether the contact requested a donation receipt | | | -| `payment_method` | String | The Twingle payment method used for the donation | One of:
| Yes | -| `donation_rhythm` | String | The interval which the donation is recurring in | One of:
| Yes | -| `debit_iban` | String | The IBAN for SEPA Direct Debit payments | A valid ISO 13616-1:2007 IBAN | Yes, if `payment_method` is `debit_manual` and CiviSEPA is used | -| `debit_bic` | String | The BIC for SEPA Direct Debit payments | A valid ISO 9362 BIC | Yes, if `payment_method` is `debit_manual` and CiviSEPA is used | -| `debit_mandate_reference` | String | The mandate reference for SEPA Direct Debit payments | | | -| `debit_account_holder` | String | The account holder for SEPA Direct Debit payments | | | -| `is_anonymous` | Boolean | Whether the donation is submitted anonymously | | | -| `user_gender` | String | The gender of the contact | | | -| `user_birthdate` | String | The date of birth of the contact | A string representing a date in the format `Ymd` | | -| `user_title` | String | The formal title of the contact | | | -| `user_email` | String | The e-mail address of the contact | A valid e-mail address | | -| `user_firstname` | String | The first name of the contact | | | -| `user_lastname` | String | The last name of the contact | | | -| `user_street` | String | The street address of the contact | | | -| `user_postal_code` | String | The postal code of the contact | | | -| `user_city` | String | The city of the contact | | | -| `user_country` | String | The country of the contact | A [ISO 3166-1 Alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) | | -| `user_telephone` | String | The telephone number of the contact | | | -| `user_company` | String | The company of the contact | | | -| `user_extrafield` | String | Additional information of the contact | | | -| `user_language` | String | The preferred language of the contact. | A [ISO-639-1 2-digit language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) | | -| `campaign_id` | Integer | The CiviCRM ID of a campaign to assign the contribution | A valid CiviCRM Campaign ID. This overrides the campaign ID configured within the profile. | | - -You may also refer to -[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Submit.php) -for more insight into this API action. - -### End recurring donation - -- Entity: `TwingleDonation` -- Action: `Endrecurring` - -The action accepts the following parameters: - -| Parameter | Type | Description | Values/Format | Required | -|---------------------------|---------|------------------------------------------------|-------------------------------------------------------|----------| -| `project_id` | String | The Twingle project ID | | Yes | -| `trx_id` | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes | -| `ended_at` | Integer | The date when the recurring donation was ended | A string representing a date in the format `YmdHis` | Yes | - -You may also refer to -[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Endrecurring.php) -for more insight into this API action. - -### Cancel donation - -- Entity: `TwingleDonation` -- Action: `Cancel` - -The action accepts the following parameters: - -| Parameter | Type | Description | Values/Format | Required | -|------------------------------|--------|----------------------------------------------------|-------------------------------------------------------|----------| -| `project_id` | String | The Twingle project ID | | Yes | -| `trx_id` | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes | -| `cancelled_at` | String | The date when the recurring donation was cancelled | A string representing a date in the format `YmdHis` | Yes | -| `cancel_reason` | String | The reason for the donation being cancelled | | Yes | - -You may also refer to -[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Cancel.php) -for more insight into this API action. \ No newline at end of file +* Creating a Twingle user and a user role in your CMS (Drupal, Wordpress, etc.) +* Configuring the *Extended Contact Matcher (XCM)* in CiviCRM +* Creating a Twingle User and an API key in CiviCRM +* Activating the SEPA connection in CiviCRM (optional) +* Configuring the Twingle profile in CiviCRM +* Configuring your Twingle Account on the Twingle website diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..4165d29 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,87 @@ +# API documentation + +The extension provides a new CiviCRM API 3 entity `TwingleDonation` with API +actions to record a new donation, end a previously submitted recurring donation +and cancel previously submitted donation. + +### Submit donation + +This API action processes submitted Twingle donations and donor information. + +- Entity: `TwingleDonation` +- Action: `Submit` + +The action accepts the following parameters: + +| Parameter | Type | Description | Values/Format | Required | +| -------------------------------------- | ------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | +| `project_id` | String | The Twingle project ID | | Yes | +| `trx_id` | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes | +| `confirmed_at` | String | The date when the donation was issued | A string representing a date in the format `YmdHis` | Yes | +| `purpose` | String | The purpose of the donation | | | +| `amount` | Integer | The donation amount in minor currency unit | | Yes | +| `currency` | String | The ISO-4217 currency code of the donation | A valid ISO-4217 currency code | Yes | +| `newsletter` | Boolean | Whether to subscribe the contact to the newsletter group defined in the profile | | | +| `postinfo` | Boolean | Whether to subscribe the contact to the postal mailing group defined in the profile | | | +| `donation_receipt` | Boolean | Whether the contact requested a donation receipt | | | +| `payment_method` | String | The Twingle payment method used for the donation | One of:
| Yes | +| `donation_rhythm` | String | The interval which the donation is recurring in | One of:
| Yes | +| `debit_iban` | String | The IBAN for SEPA Direct Debit payments | A valid ISO 13616-1:2007 IBAN | Yes, if `payment_method` is `debit_manual` and CiviSEPA is used | +| `debit_bic` | String | The BIC for SEPA Direct Debit payments | A valid ISO 9362 BIC | Yes, if `payment_method` is `debit_manual` and CiviSEPA is used | +| `debit_mandate_reference` | String | The mandate reference for SEPA Direct Debit payments | | | +| `debit_account_holder` | String | The account holder for SEPA Direct Debit payments | | | +| `is_anonymous` | Boolean | Whether the donation is submitted anonymously | | | +| `user_gender` | String | The gender of the contact | | | +| `user_birthdate` | String | The date of birth of the contact | A string representing a date in the format `Ymd` | | +| `user_title` | String | The formal title of the contact | | | +| `user_email` | String | The e-mail address of the contact | A valid e-mail address | | +| `user_firstname` | String | The first name of the contact | | | +| `user_lastname` | String | The last name of the contact | | | +| `user_street` | String | The street address of the contact | | | +| `user_postal_code` | String | The postal code of the contact | | | +| `user_city` | String | The city of the contact | | | +| `user_country` | String | The country of the contact | A [ISO 3166-1 Alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) | | +| `user_telephone` | String | The telephone number of the contact | | | +| `user_company` | String | The company of the contact | | | +| `user_extrafield` | String | Additional information of the contact | | | +| `user_language` | String | The preferred language of the contact. | A [ISO-639-1 2-digit language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) | | +| `campaign_id` | Integer | The CiviCRM ID of a campaign to assign the contribution | A valid CiviCRM Campaign ID. This overrides the campaign ID configured within the profile. | | + +You may also refer to +[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Submit.php) +for more insight into this API action. + +### End recurring donation + +- Entity: `TwingleDonation` +- Action: `Endrecurring` + +The action accepts the following parameters: + +| Parameter | Type | Description | Values/Format | Required | +| ------------------------- | ------- | ---------------------------------------------- | --------------------------------------------------- | -------- | +| `project_id` | String | The Twingle project ID | | Yes | +| `trx_id` | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes | +| `ended_at` | Integer | The date when the recurring donation was ended | A string representing a date in the format `YmdHis` | Yes | + +You may also refer to +[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Endrecurring.php) +for more insight into this API action. + +### Cancel donation + +- Entity: `TwingleDonation` +- Action: `Cancel` + +The action accepts the following parameters: + +| Parameter | Type | Description | Values/Format | Required | +| ---------------------------- | ------ | -------------------------------------------------- | --------------------------------------------------- | -------- | +| `project_id` | String | The Twingle project ID | | Yes | +| `trx_id` | String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes | +| `cancelled_at` | String | The date when the recurring donation was cancelled | A string representing a date in the format `YmdHis` | Yes | +| `cancel_reason` | String | The reason for the donation being cancelled | | Yes | + +You may also refer to +[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Cancel.php) +for more insight into this API action. diff --git a/docs/configuration/account.md b/docs/configuration/account.md new file mode 100644 index 0000000..c141036 --- /dev/null +++ b/docs/configuration/account.md @@ -0,0 +1,27 @@ +# Twingle account settings on the Twingle website + +The use of the Twingle API extension requires that you already have a Twingle +account and that you make some settings in this account for the connection. + +You will have to provide the following settings in your Twingle account settings +in order to send donations to CiviCRM: + +1. API key from your Twingle user +2. Site key +3. URL + +Important: The URL must always be the complete URL to the CiviCRM REST API +endpoint. +Examples: + +- Drupal (with the *AuthX* extension): https://example.org/civicrm/ajax/rest +- Drupal (legacy + method): https://example.org/sites/all/modules/civicrm/extern/rest.php +- Wordpress (with CiviCRM < + 5.25): https://example.org/wp-content/plugins/civicrm/civicrm/extern/rest.php +- Wordpress (with CiviCRM + 5.25+): https://example.org/wp-json/civicrm/v3/rest + +For detailled information, please see +the [Twingle documentation](https://support.twingle.de/faq/de-de/9-anbindung-externer-systeme/46-wie-kann-ich-civicrm-mit-twingle-nutzen) ( +in German language only). diff --git a/docs/configuration/civisepa.md b/docs/configuration/civisepa.md new file mode 100644 index 0000000..28dbef2 --- /dev/null +++ b/docs/configuration/civisepa.md @@ -0,0 +1,32 @@ +# Activating CiviSEPA integration + +The Twingle API extension provides integration with the [ +*CiviSEPA*](https://civicrm.org/extensions/civisepa-sepa-direct-debit-extension) +extension. This allows for managing SEPA mandates and collections with +*CiviSEPA* for donations being initiated via a *Twingle* form. + +1. In CiviCRM, go to **Administer**. +2. Choose **Twingle API configuration**. + ![](../img/Konso.jpg) + +3. Then click on **Configure extension settings**. + ![](../img/SepaKon.jpg) + +4. Tick the boxes **Use CiviSEPA** and **Use CiviSEPA generated reference**. + These options can only be activated if CiviSEPA is installed and used. If it + is not activated, the administration of SEPA mandates will have to take place + in Twingle, which is subject to configuration of your available payment + methods. +5. Write **TW-** in the **Twingle ID Prefix** field. + To avoid overlaps when assigning CiviCRM IDs and Twingle transaction IDs, a + prefix should be assigned here, e.g. "TWNGL" or "Twingle" or similar. + Attention: The prefix should not be changed later, otherwise problems may + occur. +6. In the **Protect Recurring Contributions** field select **No**. + If you choose Yes, all recurring donations created by Twingle can no longer + be changed in CiviCRM, but must then be changed accordingly in Twingle. If no + recurring payments are processed via Twingle, but only one-off donations, + then this does not need to be activated. Otherwise, we strongly recommend + setting the button here to **Yes** so that there are no discrepancies between + CiviCRM and Twingle. + ![](../img/Sepa.jpg) diff --git a/docs/configuration/profiles.md b/docs/configuration/profiles.md new file mode 100644 index 0000000..34612c1 --- /dev/null +++ b/docs/configuration/profiles.md @@ -0,0 +1,30 @@ +# Configuring the Twingle Profile in CiviCRM + +The Twingle API extension is being configured through configuration profiles. +This allows you to have different sets of configuration, as you might want to +handle donation submissions differently, depending on which form was used. +Each profile can react to one ore more form IDs being submitted along with +donation data. + +1. In CiviCRM, go to **Administer**. +2. Choose **Twingle API configuration**. + ![](../img/Konso.jpg) + +3. Then click on **Configure profiles**. + ![](../img/SepaKon.jpg) + +4. The Twingle configuration is always done with the help of a profile. Please + use the Twingle default profile and click on **Edit**. + ![](../img/Prof.jpg) + +5. Then you will identify the Twingle API profile window. Start by entering the + corresponding information in the **General settings** section. + ![](../img/GenSet.jpg) + +6. Define the different payment methods in the Payments section. + ![](../img/twpay.jpg) + +7. Make the settings for the groups. + ![](../img/Twgrou.jpg) + +8. When you have made all the settings, please press the **Save** button. diff --git a/docs/configuration/user_permissions.md b/docs/configuration/user_permissions.md new file mode 100644 index 0000000..68e81ef --- /dev/null +++ b/docs/configuration/user_permissions.md @@ -0,0 +1,82 @@ +# User, permissions, and API authentication + +After the installation of the Twingle API extension, various configuration steps +must be carried out so that the connection functions smoothly. Among other +things, certain configurations must be made on the CMS platform CiviCRM is +implemented on. + +Connecting to the Twingle API via CiviCRM's REST interface requires a user with +appropriate permissions in your CMS-system. + +You might want to create a specific user role to assign permissions necessary +for calling the Twingle API only. This section describes how to accomplish this +in *Drupal* and *Wordpress*: + +## New User Role in Drupal + +1. In Drupal, go to **Administration/People/Permissions/Roles**. +2. Type Twingle API in the text box and select **Add role**. To the right of + your role there will be a *edit role* function and an *edit permissions* + button. The *edit permissions* selection will show only the permission + selections for the individual role. +3. As Permission you only have to select the following entry: **Twingle API: + Access Twingle API**. + +## New User Role in Wordpress + +1. In CiviCRM, go to **Administer/User and Permissions (Access Control)**. +2. Then select the **WordPress Access Control** link. + Here you can adjust the CiviCRM settings for each of the predefined User + Roles from WordPress. +3. Scroll down. As Permission you only have to select the following entry: * + *Twingle API: Access Twingle API**. + +![](../img/Twin_per.png) + +## New User in Drupal + +1. In Drupal, go to **Administration/People**. +2. Then select **Add user**. +3. In user name field enter something like **Twingle API** +5. In Roles select **Twingle API**. + +## Take over user + +The Twingle API only works correctly if a contact connected to the permissioned +user exists in CiviCRM. + +Here, the corresponding steps are described by way of example when using Drupal. + +1. In CiviCRM, go to **Administer**. +2. In the **Users and Permissions** section, choose **Synchronize Users to + Contacts**. + +![](../img/Kon_syn.jpg) + +This function checks each user record in Drupal for a contact record in CiviCRM. +If there is no corresponding contact record for a user, a new one will be +generated. Check this in your CiviCRM contact management. + +![](../img/civiuser_tw.jpg) + +## Assign API key for the Twingle API user + +The Twingle API contact in CiviCRM needs their own API key for authenticating +against CiviCRM's REST API endpoint. The API key is assigned with the help of +the API Explorer in CiviCRM. + +1. Select the Twingle API contact in CiviCRM. +2. Look for the corresponding **CiviCRM ID** and remember the ID. +3. Go to **Support/Developper/API Explorer v4**. +4. Enter **Contact** in the entity field, **create** in action field and the + **ID** of the Twingle User in the **index** field. +5. In the values field, select **api_key**. +6. Enter the API key for the Twingle API user in the **add value** field. +7. Click on **Execute**. + +![](../img/apikey.jpg) + +!!!note + You can also create API keys for contacts by using the [*API + Key*](https://civicrm.org/extensions/api-key) extension or with administrator + tools like *cv* or *drush*. diff --git a/docs/configuration/xcm.md b/docs/configuration/xcm.md new file mode 100644 index 0000000..87d36e5 --- /dev/null +++ b/docs/configuration/xcm.md @@ -0,0 +1,75 @@ +# Configuring the Extended Contact Manager extension (XCM) + +After the installation of the Twingle API extension, various configuration steps +must be carried out so that the connection functions smoothly. Twingle API +depends on the *Extended Contact Manager (XCM)* extension. + +Taking over contact data using the Twingle API means that they may produce +duplicates in your CiviCRM contact management. Before contacts are added or +updated in CiviCRM a data check should take place to avoid this problem. This +data check is handled by the *Extended Contact Manager (XCM)* extension. This +extension must be configured accordingly for use with Twingle by defining a +corresponding profile. + +## Creating an XCM Profile + +Your first task regarding the Extended Contact Manager extension (XCM) +configuration will be to create an XCM profile to be used for the Twingle API. +This works best if you copy the *Default* profile. + +1. In CiviCRM, go to **Administer**. + +2. Select **Xtended Contact Matcher (XCM) Configuration** in the **System + Settings** section. + +![](../img/XCMAdmin.jpg) + +3. Click on **Copy** in the **Default** profile. + +4. Rename the new profile with **Twingle** in the **Profile name** field. + +![](../img/ProNam.jpg) + +5. Click **Save** at the bottom of this window. In the Profiles overview you can + find your new Twingle profile. + +![](../img/XCM_Profile.jpg) + +## Set up the Extended Contact Manager extension + +After you have created the XCM profile, you must enter the configuration +settings for the Twingle connection to CiviCRM in this profile. Generally, you +will find a description of all the settings in +the [Extended Contact Manager (XCM) documentation](https://docs.civicrm.org/xcm/en/latest/configuration/). + +Here you will find as support screenshots of the various sections of the +Extended Contact Manager extension (XCM). The settings are only an example. +Please adapt the settings to your individual requirements or environnement. + +#### General section + +![](../img/XCMGen.jpg) + +#### Update section + +![](../img/XCMUpda.jpg) + +#### Assignment rules section + +![](../img/XCMReg.jpg) + +#### Identified contacts section + +![](../img/XCMIde.jpg) + +#### New contact section + +![](../img/XCMNeu.jpg) + +#### Duplicate section + +![](../img/XCMDup.jpg) + +#### Difference Handling section + +![](../img/xcmdif.jpg) diff --git a/docs/img/GenSet.jpg b/docs/img/GenSet.jpg new file mode 100644 index 0000000..072f50f Binary files /dev/null and b/docs/img/GenSet.jpg differ diff --git a/docs/img/Kon_syn.jpg b/docs/img/Kon_syn.jpg new file mode 100644 index 0000000..c9ba9d5 Binary files /dev/null and b/docs/img/Kon_syn.jpg differ diff --git a/docs/img/Konso.jpg b/docs/img/Konso.jpg new file mode 100644 index 0000000..5dfb07e Binary files /dev/null and b/docs/img/Konso.jpg differ diff --git a/docs/img/NewUser_Tw.jpg b/docs/img/NewUser_Tw.jpg new file mode 100644 index 0000000..c0857d7 Binary files /dev/null and b/docs/img/NewUser_Tw.jpg differ diff --git a/docs/img/ProNam.jpg b/docs/img/ProNam.jpg new file mode 100644 index 0000000..bf5e906 Binary files /dev/null and b/docs/img/ProNam.jpg differ diff --git a/docs/img/Prof.jpg b/docs/img/Prof.jpg new file mode 100644 index 0000000..d8246b4 Binary files /dev/null and b/docs/img/Prof.jpg differ diff --git a/docs/img/Role_Twingle.jpg b/docs/img/Role_Twingle.jpg new file mode 100644 index 0000000..b686527 Binary files /dev/null and b/docs/img/Role_Twingle.jpg differ diff --git a/docs/img/Sepa.jpg b/docs/img/Sepa.jpg new file mode 100644 index 0000000..4a6474b Binary files /dev/null and b/docs/img/Sepa.jpg differ diff --git a/docs/img/SepaKon.jpg b/docs/img/SepaKon.jpg new file mode 100644 index 0000000..9b8793e Binary files /dev/null and b/docs/img/SepaKon.jpg differ diff --git a/docs/img/Twgrou.jpg b/docs/img/Twgrou.jpg new file mode 100644 index 0000000..20f05c7 Binary files /dev/null and b/docs/img/Twgrou.jpg differ diff --git a/docs/img/Twin_per.png b/docs/img/Twin_per.png new file mode 100644 index 0000000..1ea0e10 Binary files /dev/null and b/docs/img/Twin_per.png differ diff --git a/docs/img/XCMAdmin.jpg b/docs/img/XCMAdmin.jpg new file mode 100644 index 0000000..1ad6f92 Binary files /dev/null and b/docs/img/XCMAdmin.jpg differ diff --git a/docs/img/XCMAkt.jpg b/docs/img/XCMAkt.jpg new file mode 100644 index 0000000..027975a Binary files /dev/null and b/docs/img/XCMAkt.jpg differ diff --git a/docs/img/XCMDup.jpg b/docs/img/XCMDup.jpg new file mode 100644 index 0000000..da2036a Binary files /dev/null and b/docs/img/XCMDup.jpg differ diff --git a/docs/img/XCMGen.jpg b/docs/img/XCMGen.jpg new file mode 100644 index 0000000..a35c50f Binary files /dev/null and b/docs/img/XCMGen.jpg differ diff --git a/docs/img/XCMIde.jpg b/docs/img/XCMIde.jpg new file mode 100644 index 0000000..e3bec85 Binary files /dev/null and b/docs/img/XCMIde.jpg differ diff --git a/docs/img/XCMNeu.jpg b/docs/img/XCMNeu.jpg new file mode 100644 index 0000000..53d481f Binary files /dev/null and b/docs/img/XCMNeu.jpg differ diff --git a/docs/img/XCMPro.jpg b/docs/img/XCMPro.jpg new file mode 100644 index 0000000..52cb39a Binary files /dev/null and b/docs/img/XCMPro.jpg differ diff --git a/docs/img/XCMReg.jpg b/docs/img/XCMReg.jpg new file mode 100644 index 0000000..9f7a455 Binary files /dev/null and b/docs/img/XCMReg.jpg differ diff --git a/docs/img/XCMUpda.jpg b/docs/img/XCMUpda.jpg new file mode 100644 index 0000000..054f9bc Binary files /dev/null and b/docs/img/XCMUpda.jpg differ diff --git a/docs/img/XCM_Profile.jpg b/docs/img/XCM_Profile.jpg new file mode 100644 index 0000000..741d29d Binary files /dev/null and b/docs/img/XCM_Profile.jpg differ diff --git a/docs/img/apikey.jpg b/docs/img/apikey.jpg new file mode 100644 index 0000000..12387a0 Binary files /dev/null and b/docs/img/apikey.jpg differ diff --git a/docs/img/civiuser_tw.jpg b/docs/img/civiuser_tw.jpg new file mode 100644 index 0000000..9a560b8 Binary files /dev/null and b/docs/img/civiuser_tw.jpg differ diff --git a/docs/img/twpay.jpg b/docs/img/twpay.jpg new file mode 100644 index 0000000..6a48197 Binary files /dev/null and b/docs/img/twpay.jpg differ diff --git a/docs/img/xcmdif.jpg b/docs/img/xcmdif.jpg new file mode 100644 index 0000000..8f76b12 Binary files /dev/null and b/docs/img/xcmdif.jpg differ diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..352a50f --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,19 @@ +# Installation + +You can find an official release archive from +the [release page](https://github.com/systopia/de.systopia.twingle). + +1. First, download and then unpack the archive and move the directory into your + CiviCRM extensions folder (e.g.,`.../civicrm/ext/`. + If you don't know where your extensions folder is, just have a look in your + CiviCRM settings ( **Administer**/**System Settings**/**Directories**)). +2. Next, open the extensions page in the CiviCRM settings (**Administer**/* + *System Settings**/**Extensions**). +3. Find the extension Twingle API in the*Extensions*tab and click on**Install**. + The extension will be set up. + +## Extended Contact Matcher (XCM) + +Please note that for the correct working of Twingle API you still need to +install the extension Extended Contact Matcher (XCM), see +the [documentation](https://docs.civicrm.org/xcm). diff --git a/mkdocs.yml b/mkdocs.yml index 4230310..6fe26ca 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,20 +1,32 @@ site_name: Twingle API -repo_url: https://github.com/systopia/de.systopia.twingle -theme: +theme: name: material nav: -- 'Home': index.md + - Introduction: index.md + - Installation: installation.md + - Configuration: + - User, permissions and API authentication: configuration/user_permissions.md + - Extended Contact Manager (XCM) extension: configuration/xcm.md + - CiviSEPA integration: configuration/civisepa.md + - Twingle Profiles: configuration/profiles.md + - Configuring the Twingle Account on the Twingle website: configuration/account.md + - API documentation: api.md markdown_extensions: -- attr_list -- admonition -- def_list -- codehilite -- toc: - permalink: true -- pymdownx.superfences -- pymdownx.inlinehilite -- pymdownx.tilde -- pymdownx.betterem -- pymdownx.mark + - attr_list + - admonition + - def_list + - pymdownx.highlight: + guess_lang: false + - toc: + permalink: true + - pymdownx.superfences + - pymdownx.inlinehilite + - pymdownx.tilde + - pymdownx.betterem + - pymdownx.mark + +plugins: + - search: + lang: en \ No newline at end of file