Updating realm admin guide

docs/realm-admin-guide.md

@@ -28,7 +28,7 @@ Realm administrators should monitor the number of codes issued and take correcti
 
 Go to the realm setting by selecting the `settings` drop down menu (shown under your name).
 
-![settings](images/admin/settings01.png "Click on your name and select 'settings'")
+![settings](images/admin/menu_settings.png "Click on your name and select 'settings'")
 
 Under general settings, confirm the `Name` (display name only) and `Region code` settings.
 
@@ -42,11 +42,70 @@ Once that is confirmed and saved, click the `Enable EN Express` button.
 
 ![express](images/admin/settings03.png "Enable EN Express")
 
-After you have enabled EN Express, it is possible to customize the text of the SMS message that gets sent to patients.
+## Settings, code settings
+
+Also under realm settings `settings` from the drop down menu, there are several settings for code issuance.
+
+![express](images/admin/settings_code.png "Code settings")
+
+### Bulk Issue Codes
+
+  * Enabled
+
+    A new tab is added to the realm that allows the issuance of many codes from a CSV file.
+    This can be useful for case-workers who are given a data-set of test results rather than
+    administering tests one-by-one.
+
+  * Disabled
+
+    Only the single issue-code tab will be shown. Calls to the batch issue API will fail
+    for this realm.
+
+### Allowed Test Types
+
+  Realms may allow the following test result types from case workers.
+
+  * Positive + Likely + Negative
+  * Positive + Likely
+  * Positive
+
+  Although only `positive` and `likely` are used for matching exposure notifications on the client,
+  `negative` is recommended for realms where the test result is shown to the user through the patient app.
+  Showing all diagnosis - including `negative` through the app upon code issuance is a more powerful way to
+  drive adoption of this system and can be more secure because the receipt of an SMS from this system does not
+  reveal the diagnosis outcome.
+
+### Date Configuration
+
+Issuing codes have two date fields `testDate` and `symptomDate`. If this setting is marked `required`
+the issuer must pass one or both of these dates. Case workers might ask for the date of symptom onset together
+with the test, but when only `testDate` is given, apps are optionally recommended to prompt the user to enter
+a date for first onset of symptoms - this may allow for more accurate matching of exposure.
+
+If set to `optional`, codes may be issued successfully with no dates present.
+
+### Code Length & Expiration
+
+This setting adjusts the number of characters required for both long and short codes.
+Realm admins may also define how long an issued code lasts before it expires. Once expired,
+the patient will not longer be able to claim the diagnosis as theirs.
+
+If EN Express is enabled, these fields are not adjustable.
+
+Short codes are intended to be used where a case-worker may need to dictate the code to their patients
+whereas long codes may be more secure for realms where they may be sent via SMS (but may be more difficult to dictate and recall).
+
+### SMS Text Template
+
+It is possible to customize the text of the SMS message that gets sent to patients.
 See the help text on that page for guidance.
 
 ![sms text](images/admin/settings04.png "SMS Template")
 
+The fields `[region]`, `[code]`, `[expires]`, `[longcode]`, and `[longexpires]` may be included with brackets
+which will be programmatically substituted with values. It is recommended that the text of this SMS be composed
+in such a way that is respectful to the patient and does not reveal details about their diagnosis to potential onlookers of the phone's notifications with further information presented in-app.
+
 ## Settings, Twilio SMS credentials
 
 To dispatch verification codes / links over SMS, a realm must provide their credentials for [Twilio](https://www.twilio.com/). The necessary credentials (Twilio account, auth token, and phone number)
@@ -58,7 +117,7 @@ must be obtained from the Twilio console.
 
 Go to realm users admin by selecting 'Users' from the drop-down menu (shown under your name).
 
-![settings](images/admin/settings01.png "Click on your name and select 'Users'")
+![settings](images/admin/menu_users.png "Click on your name and select 'Users'")
 
 Add users, by clicking on `create a new user`.
 
@@ -76,7 +135,7 @@ If a user only needs to be able to issue verification codes, they do not need to
 API Keys are used by your mobile app to access the verification server.
 These API keys should be kept secret and only used by your mobile app.
 
-![api keys](images/admin/settings01.png "Click on your name and select 'API Keys'")
+![api keys](images/admin/menu_apikeys.png "Click on your name and select 'API Keys'")
 
 Click the link to create a new API key.
 
@@ -101,7 +160,7 @@ Periodically, you will want to rotate the certificate signing key for your verif
 
 This is done from the 'Signing Keys' screen.
 
-![settings](images/admin/settings01.png "Click on your name and select 'Signing Keys'")
+![settings](images/admin/menu_signing.png "Click on your name and select 'Signing Keys'")
 
 ### Step 1 - Create a new signing key version