Add a how to add a service document (#637)

* Add a how to add a service document

how-to/workspace-platform-starter/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## v16
 
+- Docs - Added a document showing [How To Add A Service](./docs/how-to-add-a-service.md)
 - Improved launchPreference so that now args for a native app (app asset or external) can be specified via launchPreference. Launch preference can also be configured to allow args to be specified dynamically when the launch request is made. Please see [how to define app launch preference](./docs/how-to-define-app-launch-preference.md).
 - Improved launchPreference so additional options such as url, interop, customData can be specified. Modules can now pass a launchPreference when launching an app by appId. They can see if the app supports being updated by getting the app by id and checking for the updatable setting under launchPreference.options. Only inline-view/view and inline-window/window support updatable launch preferences. Please see [how to define app launch preference](./docs/how-to-define-app-launch-preference.md).
 - Added support for Snap, enable by setting `customSettings.snapProvider.enabled` to true. Configure the `customSettings.snapProvider.serverAssetInfo` to point to the `SNAP_ASSET_URL`. Enable the Snap debugging window by setting `customSettings.snapProvider.showDebugWindow` to true.

how-to/workspace-platform-starter/README.md

@@ -71,7 +71,7 @@ The information below provides information related to configuring and using the
 | [Configure Snap](./docs/how-to-configure-snap.md)                                                              | How to enable support for the OpenFin Snap SDK                                                                                                                                                                                                                                                                                                                              |
 | [Extend You Platform with Query Strings](./docs/how-to-extend-your-platform-with-querystrings)                 | How can you provide additional options to your applications with query strings both at launch and when already running                                                                                                                                                                                                                                                      |
 | [Secure Your Platform](./docs/how-to-secure-your-platform.md)                                                  | How would you secure your platform? What are some of the things you should consider when building your platform?                                                                                                                                                                                                                                                            |
-| [Extend Your Platform](./docs/how-to-extend-your-platform.md)                                                  | How would you extend your platform to support more use cases? E.g. Would you like to be able to have your platform launched with query strings to support additional behaviors?                                                                                                                                                                                             |
+| [How To Add A Service](./docs/how-to-add-a-service.md)                                                         | How would you extend your platform to so that a service is started up when the application has finished it's bootstrapping process and started?                                                                                                                                                                                                                             |
 | [Deploy Your Platform](./docs/how-to-deploy-your-platform.md)                                                  | How can you deploy your platform?                                                                                                                                                                                                                                                                                                                                           |
 | [Manage Environments](./docs/how-to-manage-environments.md)                                                    | How would you support local, dev, uat, staging, pre-prod and prod environments for your platform?                                                                                                                                                                                                                                                                           |
 | [Testing Your Platform Code](./docs/how-to-test-your-platform-code.md)                                         | How would you test the code for your platform?                                                                                                                                                                                                                                                                                                                              |

how-to/workspace-platform-starter/docs/how-to-add-a-service.md

@@ -0,0 +1,66 @@
+> **_:information_source: OpenFin Workspace:_** [OpenFin Workspace](https://www.openfin.co/workspace/) is a commercial product and this repo is for evaluation purposes (See [LICENSE.MD](../LICENSE.MD)). Use of the OpenFin Container and OpenFin Workspace components is only granted pursuant to a license from OpenFin (see [manifest](../public/manifest.fin.json)). Please [**contact us**](https://www.openfin.co/workspace/poc/) if you would like to request a developer evaluation key or to discuss a production license.
+
+[<- Back to Table Of Contents](../README.md)
+
+# How To Add A Service
+
+First a definition of what we mean by service:
+
+> A service is something that is not visible, automatically starts up when the platform starts, runs until the platform closes and executes some custom code created by a developer.
+
+There are two approaches to achieving the following:
+
+- Create a lifecycle module (see [how to use lifecycle events](./how-to-use-lifecycle-events.md))
+- Create a headless app and add it to your app directory configured to autostart (see [how to add an app](./how-to-define-apps.md))
+
+This document will describe the two options in more detail and the reasons why you might pick one over the other.
+
+## Lifecycle Module
+
+A lifecycle module is a JavaScript module that is built (see [how to use lifecycle events](./how-to-use-lifecycle-events.md)) by a platform developer or a content developer. A platform owner can then register the module through configuration so that it loads up and is executed at the specified lifecycle event (e.g. after bootstrapping).
+
+### Benefits of a lifecycle module
+
+- You don't require a html page and you just need to host a JavaScript file
+- Modules have access to platform helper methods and might therefore be the right choice depending on what you want to do (e.g. if you want to create a notification service the platform can permission a module so that it can request a notification client)
+- You only need module configuration, you don't need to define an application
+
+## Headless Application
+
+You can register an application in the app directory (see [how to add an app](./how-to-define-apps.md)) and you can specify the following:
+
+- It is of type: window (manifestType: window or inline-window)
+- It is a singleton so only a single instance is fired up (instanceMode: single)
+- It starts up automatically when the platform starts (autostart: true)
+- It is private and does not show up in Home, Store or Dock (private: true)
+
+As part of the window definition you will want to set the following settings in the window manifest file or inline settings:
+
+- includeInSnapshots: false (you do not want this background window to be included and switched out when workspaces are applied)
+- autoShow: false (you do not want this window to be visible)
+
+### Benefits of a headless application
+
+- It makes for a good intent target (you can specify the intents you support in the app definition)
+- It lets you load up a url that is part of the content provider's domain (if the platform provider and content provider are hosted in different domains)
+- It's simpler (you can start off with a basic web page that console logs hello world and start from there)
+- You can use the fdc3 api (modules have a getInteropClient helper function which can still share context and raise intents but the fdc3 api is not available)
+
+## Platform Startup flow
+
+```mermaid
+graph LR
+    A[Platform starts] --> B[Bootstrap finishes]
+    B --> C[Lifecycle modules instantiated]
+    C --> D[Autostart apps instantiated]
+```
+
+## Which one should I use?
+
+A lot of it is down to what your requirements are but here are two main use cases and our suggestion:
+
+If you are looking at building something that will handle intents -> Use a headless application as a service.
+
+If you are looking at listening to notifications from a backend and push out notifications -> Use a lifecycle module that is fired after the bootstrap process and use the getNotificationClient helper method.
+
+[<- Back to Table Of Contents](../README.md)