<commit_before>This is an experimental, badly named module, for a very specific internal
requirement to link a CiviCRM contribution page and an Aegir front-end.

* the user goes through a "contribution" payment page to sign-up to Aegir
* he gets an invoice_id that is then sent (using ajax) to the Aegir front-end
* the invoice_id is validated using the CiviCRM REST API
* a site is cloned to the requrested URL
* the user can poll the Aegir front-end to know the status of the clone operation.

To download the latest version of this module:
https://github.com/coopsymbiotic/hosting_restapi

Requirements
============

* Aegir 7.x-3.x
* hosting_saas https://drupal.org/project/hosting_saas

Recommended
===========

This module was initially developped for Coop SymbioTIC's CiviCRM hosting.
It was therefore designed to work with a CiviCRM contribution page to track
payments and to track client/organisation information.

* Front end is in the symbiocivicrm extension:
  https://github.com/coopsymbiotic/coop.symbiotic.symbiocivicrm

* Post-install site configuration is in provision_symbiotic:
  https://github.com/coopsymbiotic/provision_symbiotic 

Supported use cases and assumptions
===================================

Simplest use case
-----------------

You need a REST API to create sites in Aegir. It might be because you're using
the command line and need to script things, or you want to tie in with another
admin software.

In this case, you only need to authenticate your external tool using a single
API key.

Integration with a payment form (ex: CiviCRM, Webform or Commerce)
------------------------------------------------------------------

You would like your users to self-serve signup to your services using a web
based form. That form may include payment up front (credit card or other).

In this case, since we wanted the workflow to be interactive for clients
and avoid proxying requests through the web server, clients can submit their
REST request directly to the Aegir server.

To authenticate requets, clients must provide their invoice ID and URL.
The Aegir server then authenticates back with the front-end to validate
the invoice ID (is paid, has not been re-used). Each valid order gets
assigned a token. The token is then used to authenticate the site for
further requests (ex: get org/client information, run backups, get db, etc).

API documentation
=================<commit_msg>README.md: add Getting Started section<commit_after>This is an experimental, badly named module, for a very specific internal
requirement to link a CiviCRM contribution page and an Aegir front-end.

* the user goes through a "contribution" payment page to sign-up to Aegir
* he gets an invoice_id that is then sent (using ajax) to the Aegir front-end
* the invoice_id is validated using the CiviCRM REST API
* a site is cloned to the requrested URL
* the user can poll the Aegir front-end to know the status of the clone operation.

To download the latest version of this module:
https://github.com/coopsymbiotic/hosting_restapi

Requirements
============

* Aegir 7.x-3.x
* hosting_saas https://drupal.org/project/hosting_saas

Recommended
===========

This module was initially developped for Coop SymbioTIC's CiviCRM hosting.
It was therefore designed to work with a CiviCRM contribution page to track
payments and to track client/organisation information.

* Front end is in the symbiocivicrm extension:
  https://github.com/coopsymbiotic/coop.symbiotic.symbiocivicrm

* Post-install site configuration is in provision_symbiotic:
  https://github.com/coopsymbiotic/provision_symbiotic 

Supported use cases and assumptions
===================================

Simplest use case
-----------------

You need a REST API to create sites in Aegir. It might be because you're using
the command line and need to script things, or you want to tie in with another
admin software.

In this case, you only need to authenticate your external tool using a single
API key.

Integration with a payment form (ex: CiviCRM, Webform or Commerce)
------------------------------------------------------------------

You would like your users to self-serve signup to your services using a web
based form. That form may include payment up front (credit card or other).

In this case, since we wanted the workflow to be interactive for clients
and avoid proxying requests through the web server, clients can submit their
REST request directly to the Aegir server.

To authenticate requets, clients must provide their invoice ID and URL.
The Aegir server then authenticates back with the front-end to validate
the invoice ID (is paid, has not been re-used). Each valid order gets
assigned a token. The token is then used to authenticate the site for
further requests (ex: get org/client information, run backups, get db, etc).

Getting started with CiviCRM
============================

* Install this module in your Aegir front-end (under `/var/aegir/hostmaster-7.x-3.xx/sites/example.org/modules/`).
* Also enable `hosting_restapi_civicrm`
* Create an API user on your CiviCRM instance (where signups are handled).
* Set the API credentials on your Aegir server:

```
drush @hm vset hosting_restapi_crmhost https://crm.example.org
drush @hm vset hosting_restapi_crmapikey YOUR_USER_API_KEY
drush @hm vset hosting_restapi_crmkey YOUR_CIVICRM_SITE_KEY
```

NB: currently it assumes that you are using Drupal7 and that CiviCRM is in `/sites/all/modules/civicrm/`. This can easily be fixed in `hosting_restapi_civicrm_api` by adding the `path` parameter to `civicrm_api3` (see in `civicrm.class.php`).

API documentation
=================
{'fraction_non_alphanumeric': 0.10688920454545454, 'fraction_numerical': 0.0014204545454545455, 'mean_word_length': 4.029464285714286, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 9, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2665206', 'n_tokens_mistral': 1589, 'n_tokens_neox': 1534, 'n_words': 743}