Add documentation for new AS Notification/Profile feature

docs/features/experimental/application-service.md

@@ -1,6 +1,63 @@
 # Integration as an Application Service
-**WARNING: **These features are highly experimental. They can be removed or modified without notice.  
+**WARNING:** These features are currently highly experimental. They can be removed or modified without notice.  
-Support is only available via a paid subscription or consultancy.
+All the features requires a Homeserver capable of connecting Application Services.
 
-## 3PID notification for Matrix ID Room invites
+## Email notification for Room invites by Matrix ID
-*TBC*
+This feature allows for users found in Identity stores to be instantly notified about Room Invites, regardless if their
+account was already provisioned on the Homeserver.
+
+### Requirements
+- [Identity store(s)](../../stores/README.md) supporting the Profile feature
+- At least one email entry in the identity store for each user that could be invited.
+
+### Configuration
+In your mxisd config file:
+```yaml
+matrix:
+  listener:
+    url:  '<URL TO THE CS API OF THE HOMESERVER>'
+    localpart: 'appservice-mxisd'
+    token:
+      hs: 'HS_TOKEN_CHANGE_ME'
+```
+
+You can also change the default template of the notification using the `generic.matrixId` template option.  
+See [the Template generator documentation](../../threepids/notification/template-generator.md) for more info.
+
+### Homeserver integration
+#### Synapse
+Create a new appservice registration file. Futher config will assume it is in `/etc/matrix-synapse/appservice-mxisd.yaml`
+```yaml
+id: "appservice-mxisd"
+url: "http://127.0.0.1:8090"
+as_token: "AS_TOKEN_CHANGE_ME"
+hs_token: "HS_TOKEN_CHANGE_ME"
+sender_localpart: "appservice-mxisd"
+namespaces:
+  users:
+    - regex: "@*"
+      exclusive: false
+  aliases: []
+  rooms: []
+```
+`id`: An arbitrary unique string to identify the AS.  
+`url`: mxisd to reach mxisd. This ideally should be HTTP and not going through any reverse proxy.  
+`as_token`: Arbitrary value used by mxisd when talking to the HS. Not currently used.  
+`hs_token`: Arbitrary value used by synapse when talking to mxisd. Must match `token.hs` in mxisd config.
+`sender_localpart`: Username for the mxisd itself on the HS. Default configuration should be kept.  
+`namespaces`: To be kept as is.  
+
+Edit your `homeserver.yaml` and add a new entry to the appservice config file, which should look something like this:
+```yaml
+app_service_config_files:
+  - '/etc/matrix-synapse/appservice-mxisd.yaml'
+  - ...
+```
+
+Restart synapse when done to register mxisd.
+
+#### Others
+See your Homeserver documentation on how to integrate.
+
+### Test
+Invite a user which is part of your domain while an appropriate Identity store is used.

docs/features/experimental/profile.md

@@ -0,0 +1,12 @@
+# Profile enhancement
+**WARNING**: Alpha feature, not officially supported. Do not use.
+
+This feature allows to enhance a profile query with more info than just Matrix ID and Display name, allowing for custom
+applications to retrieve custom data not currently provided by synapse, per example.
+
+## Configuration
+### Reverse proxy
+#### Apache
+```apache
+ProxyPassMatch "^/_matrix/client/r0/profile/([^/]+)$" "http://127.0.0.1:8090/_matrix/client/r0/profile/$1"
+```

docs/features/profile.md

@@ -1,9 +0,0 @@
-# Profile enhancement
-**WARNING**: Alpha feature not officially supported. Do not use.
-
-## Configuration
-### Reverse proxy
-#### Apache
-```apache
-ProxyPassMatch "^/_matrix/client/r0/profile/([^/]+)$" "http://127.0.0.1:8090/_matrix/client/r0/profile/$1"
-```

docs/stores/firebase.md

@@ -7,6 +7,7 @@ https://firebase.google.com/
 | Authentication | Yes        |
 | Directory      | No         |
 | Identity       | Yes        |
+| Profile        | No         |
 
 ## Requirements
 This backend requires a suitable Matrix client capable of performing Firebase authentication and passing the following

docs/stores/ldap.md

@@ -13,6 +13,7 @@ For NetIQ, replace all the `ldap` prefix in the configuration by `netiq`.
 | Authentication | Yes        |
 | Directory      | Yes        |
 | Identity       | Yes        |
+| Profile        | Yes        |
 
 ## Getting started
 ### Base

docs/stores/rest.md

@@ -13,6 +13,7 @@ To integrate this backend with your webapp, you will need to implement three spe
 | Authentication | Yes        |
 | Directory      | Yes        |
 | Identity       | Yes        |
+| Profile        | No         |
 
 ## Configuration
 | Key                              | Default                                        | Description                                          |

docs/stores/sql.md

@@ -11,6 +11,7 @@
 | Authentication | No         |
 | Directory      | Yes        |
 | Identity       | Yes        |
+| Profile        | Yes        |
 
 Due to the implementation complexity of supporting arbitrary hashing/encoding mechanisms or auth flow, Authentication
 will be out of scope of SQL Identity stores and should be done via one of the other identity stores, typically

docs/stores/synapse.md

@@ -7,6 +7,7 @@ Synapse's Database itself can be used as an Identity store.
 | Authentication | No         |
 | Directory      | Yes        |
 | Identity       | Yes        |
+| Profile        | Yes        |
 
 Authentication is done by Synapse itself.
 

docs/stores/wordpress.md

@@ -10,6 +10,7 @@ Two types of connections are required for full support:
 | Authentication | Yes        |
 | Directory      | Yes        |
 | Identity       | Yes        |
+| Profile        | No         |
 
 ## Requirements
 - [Wordpress](https://wordpress.org/download/) >= 4.4

docs/threepids/notification/template-generator.md

@@ -19,6 +19,8 @@ threepid.medium.<YOUR 3PID MEDIUM HERE>:
         validation:
           local: '/path/to/validate-local-template.eml'
           remote: 'path/to/validate-remote-template.eml'
+      generic:
+        matrixId: '/path/to/mxid-invite-template.eml'
 ```
 The `template` generator is usually the default, so no further configuration is needed.