Merge pull request #41 from Bioinformatics/feature/licensing_document…

…ation

licensing documentation

docs/introduction/getting-started.md

@@ -124,6 +124,47 @@ Here's [a toy VCF file](https://illumina.github.io/IlluminaConnectedAnnotationsD
 curl -O https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/files/HiSeq.10000.vcf.gz
 ```
 
+## Prerequisite
+
+### Creating Illumina API key
+To use Data Manager, users have to create an Illumina API key. To generate the API key, users are required to create Illumina public account which can be created freely from [this page](https://accounts.login.illumina.com).
+
+![](account-login.png)
+
+Click "Don't have an account" link to go to the user creation form. If you already have an account, enter your credentials.
+Once you login, you will go to Product Dashboard page. Click on the user icon on the top right to open menu and choose Manage API Keys.
+
+![](product-dashboard.png)
+
+In the Manage API Keys, click Generate Button and enter the API key name. Once you have done that, the generated API key will be displayed.
+
+![](api-key-page.png)
+
+### Storing Illumina API key in your system
+Copy the API key and store it into a file with json format like below:
+
+```json
+{
+  "MyIlluminaApiKey": "<your Illumina account api key>"
+}
+```
+
+By default, Data Manager will look for file `~/.ilmnAnnotations/credentials.json` but this file may be saved at any location and passed in as commandline argument.
+```json
+{
+  "MyIlluminaApiKey": "<your Illumina account api key>"
+}
+```
+
+If you have API key and API secret for Illumina Connected Annotation professional tier data source, you should put those credentials in this file also.
+```json
+{
+  "MyIlluminaApiKey": "<your Illumina account api key>",
+  "ApiKey": "<your professional data source API key>",
+  "ApiSecret": "<your professional data source API secret>"
+}
+```
+
 ## Running Illumina Connected Annotations
 
 Once you have downloaded the data sets, use the following command to annotate your VCF:

docs/introduction/introduction.mdx

@@ -92,7 +92,7 @@ The basic tier can be accessed free of charge. The professional tier requires a
 | TOPMed               | Basic        | freeze 5                 |
 
 ### Download manager
-To effectively download all of data, we have provided download manager. Please go to [download manager](./utilities/download-manager) page to read more.
+To effectively download all of data, we have provided download manager. Please go to [DataManager](./utilities/data-manager) page to read more.
 
 ## Download
 Please visit [Illumina Connected Annotations](https://developer.illumina.com/illumina-connected-annotations).

docs/introduction/licensedContent.mdx

@@ -15,14 +15,16 @@ License may be customized to allow access to one of more of the above at the tim
 :::
 
 :::note
-The Annotator packaged with DRAGEN comes with a license for all premium contents. 
-That is, if the Annotator is run from within DRAGEN, all premium content will be available. 
+The Annotator packaged with DRAGEN comes with a license for all premium contents.
+That is, if the Annotator is run from within DRAGEN, all premium content will be available.
 However, this doesn't automatically grant a license to get premium contents while running the Annotator outside of DRAGEN.
-Please contact annotation_support@illumina.com for stand-alone licenses.
+You may use your DRAGEN box serial number to access licensed content (see below).
 :::
 
 ## How to obtain the license?
-Please contact annotation_support@illumina.com to obtain a special credentials file for the data sources of interest.
+There are two ways of obtaining a license:
+1. Please contact annotation_support@illumina.com to obtain a special credentials file for the data sources of interest.
+2. If you are a DRAGEN user, you may use your DRAGEN serial number directly.
 
 Visit [Illumina Connected Annotations](https://developer.illumina.com/illumina-connected-annotations) for more details.
 
@@ -31,33 +33,59 @@ After obtaining the credentials file, it may be used in two ways:
 1. Home folder
 2. Commandline argument
 
-The default location of the license file is `~/.ilmnAnnotations/credentials.json`. An example of credentials file as below:
+The default location of the license file is `~/.ilmnAnnotations/credentials.json` but this file may be saved at any location and passed in as commandline argument.
+
+
+1. File with special credentials:
+```json {3-4}
+{
+  "MyIlluminaApiKey": "<your Illumina account api key>",
+  "ApiKey": "<your professional data source API key>",
+  "ApiSecret": "<your professional data source API secret>"
+}
+```
+2. File with DRAGEN serial number:
 ```json
 {
-	"ApiKey":"myApiKey",
-	"ApiSecret": "abcdefghikjlmnopqrstuvwxyz-secretKey"
+  "MyIlluminaApiKey": "<your Illumina account api key>",
+  "DragenSerialNo": "<your DRAGEN box serial number>"
 }
 ```
-However, this can be overridden by the command line argument while downloading/annotating.
+
+### Autogenerated Licence file
+The DataManager will also download a file that will be stored alongside the path of credentials.json file, named `premium.lic`.
+This file contains the encoded information for accessing the licensed content. It is automatically managed and used by
+Annotator and Data Manager, and user intervention is not needed.
+
+:::tip
+If you are experiencing licensing errors, you can delete this file. Running Annotator or Data Manager will automatically fetch a new `premium.lic` file based on your allowed professional content.
+:::
+
+### Offline Mode
+It should be noted that professional content is protected through online license verification system which works in the background.
+If you intend to run Annotator without internet access, make sure the `premium.lic` (which was auto downloaded by Data Manager) is present alongside the `credentials.json` file.
+The autogenerated file: `premium.lic` will expire after 90 days and must be re-downloaded from internet.
+
+#### Re-downloading premium.lic
+The file `premium.lic` will be automatically downloaded once Data Manager is used to re-download any sources.
+Running Annotator with internet access will also re-download this file.
+Once this file is re-downloaded, it may be used for offline use for another 90 days.
 
 ### Download licensed content
-```shell
-dotnet Downloader.dll \
--o ~/data \
--ga GRCh38 \
---credentialsFile ~/credentials.json
-```
+See: [DataManager](../utilities/data-manager.mdx)
+Make sure to include the `credentials.json` file
 
 
 ### Annotate with licensed content
-```shell
+Make sure to include the `credentials.json` file
+```shell {7}
 dotnet Annotator.dll \
 --ref ~/data/References/7/Homo_sapiens.GRCh38.Nirvana.dat \
---sd ~/data/SupplementaryDatabase \
+--sd ~/data/SupplementaryDatabase/GRCh38 \
 -c ~/data/Cache/32 \
 -i ~/input_vcf-hg38.vcf.gz \
 -o ~/output \
---credentialsFile ~/credentials.json
+--credentials-file ~/credentials.json
 ```