add docs

tdashworth · Nov 4, 2020 · 359354a · 359354a
1 parent edd3032
commit 359354a
Show file tree

Hide file tree

Showing 40 changed files with 263 additions and 0 deletions.
diff --git a/docs/Assets/Add Subscription.png b/docs/Assets/Add Subscription.png
diff --git a/docs/Assets/Blank Notification Tray.png b/docs/Assets/Blank Notification Tray.png
diff --git a/docs/Assets/Choose event and methods.png b/docs/Assets/Choose event and methods.png
diff --git a/docs/Assets/Delete Device Subscription.png b/docs/Assets/Delete Device Subscription.png
diff --git a/docs/Assets/DeleteAnEvent.gif b/docs/Assets/DeleteAnEvent.gif
diff --git a/docs/Assets/Device name change after.png b/docs/Assets/Device name change after.png
diff --git a/docs/Assets/Device name change before.png b/docs/Assets/Device name change before.png
diff --git a/docs/Assets/Dismiss all notifications.gif b/docs/Assets/Dismiss all notifications.gif
diff --git a/docs/Assets/Dismiss single notification.gif b/docs/Assets/Dismiss single notification.gif
diff --git a/docs/Assets/DismissAllNotifiactionMessages.gif b/docs/Assets/DismissAllNotifiactionMessages.gif
diff --git a/docs/Assets/DismissAllNotificationMessages.gif b/docs/Assets/DismissAllNotificationMessages.gif
diff --git a/docs/Assets/DismissNotificationMessage.gif b/docs/Assets/DismissNotificationMessage.gif
diff --git a/docs/Assets/Hide Notification Tray.png b/docs/Assets/Hide Notification Tray.png
diff --git a/docs/Assets/Main Buttons.png b/docs/Assets/Main Buttons.png
diff --git a/docs/Assets/Manage events.png b/docs/Assets/Manage events.png
diff --git a/docs/Assets/ModifyAnEvent.gif b/docs/Assets/ModifyAnEvent.gif
diff --git a/docs/Assets/Notification Tray in banner.png b/docs/Assets/Notification Tray in banner.png
diff --git a/docs/Assets/Notification subscriptions.png b/docs/Assets/Notification subscriptions.png
diff --git a/docs/Assets/Notification tray with notifications.png b/docs/Assets/Notification tray with notifications.png
diff --git a/docs/Assets/OpenRelatedRecord.gif b/docs/Assets/OpenRelatedRecord.gif
diff --git a/docs/Assets/PowerApps app store.png b/docs/Assets/PowerApps app store.png
diff --git a/docs/Assets/PowerApps launch screen.png b/docs/Assets/PowerApps launch screen.png
diff --git a/docs/Assets/PowerApps successful sign in.png b/docs/Assets/PowerApps successful sign in.png
diff --git a/docs/Assets/Re-open Notification Tray.png b/docs/Assets/Re-open Notification Tray.png
diff --git a/docs/Assets/Refresh browser settings.png b/docs/Assets/Refresh browser settings.png
diff --git a/docs/Assets/ResubscribeToBrowser.gif b/docs/Assets/ResubscribeToBrowser.gif
diff --git a/docs/Assets/Security padlock.png b/docs/Assets/Security padlock.png
diff --git a/docs/Assets/Settings Menu.png b/docs/Assets/Settings Menu.png
diff --git a/docs/Assets/Solution Import Variables.png b/docs/Assets/Solution Import Variables.png
diff --git a/docs/Assets/SubscribeToBrowser.gif b/docs/Assets/SubscribeToBrowser.gif
diff --git a/docs/Assets/SubscribeToEvents.gif b/docs/Assets/SubscribeToEvents.gif
diff --git a/docs/Assets/UnsubscribeToBrowser.gif b/docs/Assets/UnsubscribeToBrowser.gif
diff --git a/docs/Assets/User sign in.png b/docs/Assets/User sign in.png
diff --git a/docs/Assets/View notification permissions.png b/docs/Assets/View notification permissions.png
diff --git a/docs/Assets/Web Browser Subscription.png b/docs/Assets/Web Browser Subscription.png
diff --git a/docs/How-to-integrate.md b/docs/How-to-integrate.md
@@ -0,0 +1,20 @@
+Before reading this page, please read the [technical design](./Technical-design.md) page for nessassary context.
+
+Integrating with Power Notify is simple. User's manage Notification Subscriptions which link them to Notification Events while describing how they'd like to be notified, if at all. The system emits Notification Messages which also link to Notification Events and a User/Team to notify. 
+
+After [installing](./Installation.md) the managed solution into your environment, you can begin integrating with Power Notify. As a system developer there are a few methods to you could use:
+
+1. Build new Flows, Workflows or Plugins which create the Notification Messages upon certain system events (create, update, delete, custom actions). 
+2. Modify existing business Flows, Workflows or Plugins which create Notification Messages upon more complex business events.
+3. Create Notification Messages via the WebAPI (or XRM SDK) externally from the Power Platform. 
+
+_Note: If given the permissions, citizen developers can also utilise method (1) to build personal/team events._
+
+If your system currently sends emails to it's internal users, that's a great candidate to replace with Notification Messages with appropriate Notification Events. 
+
+Regarding Notification Events, I'd recommend migrating these records from your development environment through to test, staging, and production to guarantee their existances. This also means they can be referenced by their GUID (record primary key) which saves searching by name. 
+
+Sample Flows can be found in the Samples solution found in the repo/release. These include: 
+
+- Notify Owner when Account is updated
+- Notify Followers when Contact is updated
diff --git a/docs/How-to-use-as-an-end-user.md b/docs/How-to-use-as-an-end-user.md
@@ -0,0 +1,139 @@
+# PowerNotify for an end user
+
+PowerNotify delivers real time notifications to you when events occur that you choose to be notified about. As we move away from a business world that evolves around emails, for those who work directly in a CRM system, you should be able to receive notifications within the app, similar to the notification centre on your phone.
+
+What are some use cases?
+- Case status has changed
+- Important information has changed on a Contact record
+- New sale opportunity arrises
+- The list is endless!
+
+## Methods of delivery
+In PowerNotify there are four methods of receiving notifications:
+- Web
+- Mobile
+- Email
+- Notification Tray
+
+To receive notifications via Mobile, please see the steps [here](#how-do-i-setup-powernotify-on-mobile) to register your device for mobile notifications.
+
+## What is the Notification Tray?
+The Notification Tray is a core part of Power Notify. From here you can setup you event subscriptions and manage all of your notifications.
+
+- It's always accessible through the fixed location in the top right hand corner.
+
+- To open, you simply click the icon. The number represents the number of notifications currently in the notification tray.
+
+- The first time you access the Notification Tray, you will be prompted with the below dialog box, asking you if you would like to receive notifications via this browser. If you would like this option select 'Yes' otherwise select 'No'.
+
+### How to manage my devices?
+**Starting from the home page of the Notification Tray**
+1. Click **Settings**
+2. Click **Manage Device Subscriptions**
+
+Here you will see all devices to which you are subscribed to receive notifications
+
+You can rename any device by 
+1. Simply clicking anywhere on the name of the Device Subscription Record
+2. Entering the new name
+3. Clicking anywhere on the screen away from the name
+
+![Subscribe with browser to Power Notify](Assets/SubscribeToBrowser.gif)
+
+You can collapse the Notification Tray at any point by clicking '>' in the top right-hand corner.
+![Collapse Notification Tray](Assets/Hide%20Notification%20Tray.png)
+
+
+To re-open the Notification Tray for viewing when collapsed, click '<'.<br>
+![Re-open Notification Tray](Assets/Re-open%20Notification%20Tray.png)
+
+## Notifications
+Notifications are the main feature of PowerNotify. They inform you of key events which have occured in the system in real time. To receive notifications you first must subscribe to an event. 
+
+### How to subscribe & unsubscribe from events?
+**Prior to being able to subscribe to any events, events must be created first. For more information on how to create events, please visit this [page](./How-to-integrate.md).**
+1. Open the Notification Tray
+2. Click **Settings**
+3. Click **Manage Event Subscriptions**
+4. Click **Add Subscription**
+5. Select an event to subscribe to from the events listed by clicking on the name of the event
+6. Choose your methods to be notified by, selecting as many or few as you like by clicking on the name of the methods
+7. Click **Save Subscription**
+8. On the **Notification Subscriptions** screen you'll then see the event to which you're now subscribed
+![Subscribe to events](Assets/SubscribeToEvents.gif)
+
+### Amend notification methods for an event
+**Starting from the home page of the Notification Tray**
+
+1. Click **Settings**
+2. Click **Manage Event Subscriptions**
+3. Click on the drop-down associated with the particular event you wish to amend your notification methods
+4. To add new ones select the additional method
+5. To remove click the **x** for the mechanism you no longer want to be notified by
+![Amend notification methods for an existing event](Assets/ModifyAnEvent.gif)
+
+### Unsubscribing to an event
+**Starting from the home page of the Notification Tray**
+
+1. Click **Settings**
+2. Click **Manage Event Subscriptions**
+3. Click the **bin** icon associated with the particular event you wish to delete
+4. You are now no longer subscribed to an event and won't receive any notifications when that event is triggered. The event is also remove from the Notification Subscription screen.
+![Unsubscribe to an event](Assets/DeleteAnEvent.gif)
+
+Once you are subscribed to an event, when that event is triggered, you'll receive a notification in the notification tray.
+
+### What can you do with a notification?
+1. Open a record from a notification
+2. Dismiss notifications
+
+### Open a record from a notification
+When you have notifications in your notification tray, you can click on the circular icon with '>' to open the specific record for which you've received a notification.
+![Notification tray with notifications](Assets/OpenRelatedRecord.gif)
+
+
+### How do I clear down my notification tray?
+There are **two** methods to clear out notifications listed in the Notification Tray. 
+1. Individual
+2. All
+
+#### **Individual**
+Removing one by one gives you the complete control regarding what notifications to keep or delete. To remove click on the 'bin' icon next to the notification you wish to remove. 
+
+![Dismiss single notification](Assets/DismissNotificationMessage.gif)
+#### **All**
+Sometimes you just want to remove all notifications in one go because you've seen them all and they're no longer relevant.
+
+1. On the bottom of the homepage within the Notification Tray, simply click **Dismiss All**. *Poof*, just like magic, they're all gone!
+
+![Dismiss all notifications](Assets/DismissAllNotificationMessages.gif)
+
+## Additional Instructions
+If you no longer want a particular device to receive notifications, because maybe you don't own that device any longer, you can simply click the 'bin' icon associated with that Device Subscription record. After a few seconds you'll no longer see that device listed.
+![Unsubscribe from device](Assets/UnsubscribeToBrowser.gif)
+
+### Re-setup a browser for PowerNotify
+Once you've deleted your device, after some days/weeks/months, you may want to set the device up again. Browsers hold onto a setting preventing PowerNotify recognising your device as a new device.
+
+1. Click the padlock adjacent to the URL
+2. Set **Notifications** to **Ask (Default)**
+3. Click **X** in the top right hand corner of the pop-up window.
+4. Refresh browser
+5. Open the Notification Tray and you will be prompted to enable this browser to receive notifications.
+
+![Resubscribe to browser](assets/../Assets/ResubscribeToBrowser.gif)
+
+## How do I setup PowerNotify on mobile?
+1. Download the Power Apps mobile app from your phones app store
+<br>
+<img src="Assets/PowerApps%20app%20store.png" alt="Download PowerApps" width="400"/>
+2. Launch the app
+3. Click '**Sign in**'
+ <br>
+ <img src="Assets/PowerApps%20launch%20screen.png" alt="PowerApps launch screen" width="400"/>
+4. Enter your username and password
+ <br>
+ <img src="Assets/User%20sign%20in.png" alt="PowerApps sign-in" width="400"/>
+5. Open the Notification Tray App
+ <br>
+ <img src="Assets/PowerApps%20successful%20sign%20in.png" alt="PowerApps successful sign in" width="400"/>
diff --git a/docs/Installation.md b/docs/Installation.md
@@ -0,0 +1,58 @@
+This guide will explain the steps required to get Power Notify working in your PowerApps environment. 
+
+# Forwarding Server
+Firstly, if you wish to use the Web Push (browser notification) delivery method, a forwarding server is required that would encrypt and send the notification. This is achieved with an Azure Functions which handles this computation but this is a small amount of NodeJS code which could be hosted anywhere accessible for the Flow to call. The code for this can be found [here](https://dev.azure.com/tdashworth/Power%20Notify/_git/power-notify?path=%2FAzure). 
+
+[![Deploy To Azure](https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/1-CONTRIBUTION-GUIDE/images/deploytoazure.svg?sanitize=true)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Ftdashworth%2FPowerNotify%2Fmaster%2Fsrc%2Fazure%2Fazure-deploy.json)
+
+It's worth noting that the server is **very** generic and is not tied to an environment which means it can be used for multiple such as dev, CI/CD, and test. The server requires a set of keys, public and private, which are used for the encryption and an optional subject (primary contact email)[see section 2.1 [here](https://datatracker.ietf.org/doc/rfc8292/?include_text=1)]. The keys need to first be generated which can be done using [https://vapidkeys.com/](https://vapidkeys.com/).
+
+The public key also needs to be retained within the PowerPlatform for the user to access enabling them to decrypt the notification upon delivery. Please save that value in the environment variable called `Web Push Public Key` during the solution installation.
+
+The Flow that triggers this process is bound to a custom connector which defines the routes available on the webserver. Once your server is running, update the custom connector (under PowerApps Maker Portal > Data > Custom Connectors > Web Push Forwarding Server) with your server's details (URL and authentication) and save the connector. 
+
+# Solution Install 
+After downloading a copy of the [managed solution](), it needs to be installed into your environment. This can be done several ways including manually or the Solution Deployer.
+
+If importing manually, the following screen will show asking to enter the variable values. You will see a warning in the maker portal once the import is complete if you don't enter these values now.
+
+![Solution Import - Environment Variables](Assets/Solution%20Import%20Variables.png)
+
+For `Web Push Public Key`, use the value generated while setting up the Forwarding Server. For `Default App Id`, enter the App Id of the Model-Driven App your users will use by default - it will be used by a Flow the generate a link for the Notification Message upon clicking it. This can be left blank and users can set their own value within the Notification Tray. 
+
+# Additional Configuration
+**Next, and importantly, you need to activate the Flows in the solution.** These aren't activated on install because it requires some connections to be set up. Open the PowerNotify solution and for each Flow: 
+1) Open the editor for the Flow.
+2) You should be greeted with a dialogue asking for four connections.
+ - CDS Current Environment - this is a premium connector so make sure as the logged-on user you have a licence
+ - Web Push Forwarding Server - this is what you previously configured and now need to create a connection with authentication
+ - Mail - out-of-the-box PowerApp mail sender
+ - PowerApps Notification - used to send the mobile notification. The solution contains an app called "Notification Tray" which should be the app id provided.
+3) **Save!**
+4) Go back to the details screen and activate if not already done so. 
+
+
+All these configurations can be added to your own unmanaged solution if you'd like them to migrate with your solution. I'd recommend the `Default App Id` is not included in that at all as it will always be different. The other environment variables and custom connector could be added but I'd imagine they would change for production so manually configuring for each environment is recommended.
+
+
+# Test
+You are now configured and can test your set up.
+1) Create an Event record (right now a temporary one will do) by navigating to [environment base url]/main.aspx?forceUCI=1&pagetype=entityrecord&etn=tda_notificationchannel
+2) Click in the bell icon within the application ribbon (top-right of the screen) 
+3) Create a new Notification Subscription selecting your newly created Event and all the methods. [Visit usage guide](./How-to-use-as-an-end-user.md#how-to-subscribe--unsubscribe-from-events)
+4) Create a new Notification Message Activity setting the Owner to yourself and the Event to the one you are subscribed to. Add a subject, description, and regarding record then save. [environment base url]/main.aspx?forceUCI=1&pagetype=entityrecord&etn=tda_notificationmessage
+5) Just wait... you should:
+ - receive an email to your primary email address
+ - receive a web push notification from your browser
+ - be able to view the Message in the Notification Tray in the browser via the notification symbol in the top ribbon and on the mobile PowerApps app if you open the specific PowerApp.
+ - not receive a mobile push notification **unless** you have previously opened the Notification Tray app in the mobile PowerApp app. 
+
+If something does fail here unexpectedly, have a look the Flow within the Power Notify solution for any failures.
+
+# Events Data
+
+Event records are nothing more than streams for which users subscribe to. With only a name, these could be created manually (even for other environments). My recommendation would be to source control these records (at least those referenced within your own solutions) and import them into each environment through automation. This method also allows you to use the records' unique indentifiers, knowning they'll exist in each environment. 
+
+I would also recommend access is managed under security role to limit who in the organisation can create, update, and view these records. 
+
+To create a record, if it hasn't been added to an app which you have access to, navigate to: [environment base url]/main.aspx?forceUCI=1&pagetype=entityrecord&etn=tda_notificationchannel