Docs: [AEA-3932] - Added new statuses to OAS and fleshed out overview. (

#77)

## Summary

**Remove items from this list if they are not relevant. Remove this line
once this has been done**

- Routine Change
- ❗ Breaking Change
- 🤖 Operational or Infrastructure Change
- ✨ New Feature
- ⚠️ Potential issues that might be caused by this change

### Details

Add any summary information of what is in the change. **Remove this line
if you have nothing to add.**

## Pull Request Naming

Pull requests should be named using the following format:

```text
Tag: [AEA-NNNN] - Short description
```

Tag can be one of:

- `Fix` - for a bug fix. (Patch release)
- `Update` - either for a backwards-compatible enhancement or for a rule
change that adds reported problems. (Patch release)
- `New` - implemented a new feature. (Minor release)
- `Breaking` - for a backwards-incompatible enhancement or feature.
(Major release)
- `Docs` - changes to documentation only. (Patch release)
- `Build` - changes to build process only. (No release)
- `Upgrade` - for a dependency upgrade. (Patch release)
- `Chore` - for refactoring, adding tests, etc. (anything that isn't
user-facing). (Patch release)

If the current release is x.y.z then
- a patch release increases z by 1
- a minor release increases y by 1
- a major release increases x by 1

Correct tagging is necessary for our automated versioning and release
process ([Release](./RELEASE.md)).

The description of your pull request will be used as the commit message
for the merge, and also be included in the changelog. Please ensure that
your title is sufficiently descriptive.

### Rerunning Checks

If you need to rename your pull request, you can restart the checks by
either:

- Closing and reopening the pull request
- pushing an empty commit 
  ```bash
  git commit --allow-empty -m 'trigger build'
  git push
  ```
- Amend your last commit and force push to the branch
  ```bash
  git commit --amend --no-edit
  git push --force
  ```

Rerunning the checks from within the pull request will not use the
updated title.

packages/specification/eps-prescription-status-update-api.yaml

@@ -22,23 +22,23 @@ info:
         
     ## Related APIs
     * [Electronic Prescriptions Service](https://digital.nhs.uk/developer/api-catalogue/electronic-prescription-service-fhir): The national service for creating and dispensing prescriptions across health and social care.
-    * [Personal Demographics Service](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir): the national service for storing and retrieving NHS patient details such as name, address, date of birth, related people, registered GP and NHS number.
+    * [Prescriptions for Patients](https://digital.nhs.uk/developer/api-catalogue/prescriptions-for-patients): the national service to retrieve prescriptions data for individual patients from the Electronic Prescription Service (EPS), for use in patient-facing applications.
 
     ## API Status and Roadmap
-    This API is in an [internal private beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning the API is not currently available for integration by external third parties.
+    This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning the API will soon be available for testing via a sandbox service or an integration environment - but we expect to make breaking changes based on developer feedback.
 
     ## Service Level
-    This API is a platinum service, meaning it is operational and supported 24 hours a day, 365 days a year.
+    This API will be a platinum service, meaning it is operational and supported 24 hours a day, 365 days a year.
     See [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels) for more details.
 
     ## Technology
     This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).
 
-    It conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) global standard for health care data exchange, specifically to [FHIR UK Core](https://digital.nhs.uk/services/fhir-uk-core).
+    It conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) global standard for health care data exchange, specifically to [FHIR R4 (v4.0.1)](https://hl7.org/fhir/r4/).
 
-    It includes some country-specific FHIR extensions, which are built against [FHIR UK Core, specifically [UKcore.stu1 0.5.1](https://simplifier.net/packages/fhir.r4.ukcore.stu1/0.5.1).
+    It includes some country-specific FHIR extensions, which are built against FHIR UK Core, specifically [UK Core R4 (v4.0.1)](https://simplifier.net/HL7FHIRUKCoreR4/).
 
-    You do not need to know much about FHIR to use this API. The API only supports GET requests and the responses will be FHIR.
+    You do not need to know much about FHIR to use this API. The API only supports POST requests containing FHIR messages.
 
     FHIR APIs are just RESTful APIs that follow specific rules.
     These rules mean:
@@ -54,10 +54,40 @@ info:
     For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).
 
     ## Security and Authorisation
-    TBC
+    This API only supports application-restricted access, meaning we authenticate the calling application but not the end user.
+
+    The end user could be:
+    a healthcare worker - in which case you must ensure they are authenticated and suitably authorised locally
+    not present at all - for example as part of a back end process integrated with a shipping system
+
+    To use this access mode, use the following security pattern:
+    * [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)
 
     ## Environment and testing
-    TBC
+    | Environment      | Base URL                                                            |
+    |------------------|---------------------------------------------------------------------|
+    | Sandbox          | `https://sandbox.api.service.nhs.uk/prescription-status-update`     |
+    | Integration test | `https://int.api.service.nhs.uk/prescription-status-update`         |
+    | Production       | `https://api.service.nhs.uk/prescription-status-update`             |
+
+    ### Sandbox testing
+    Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):
+
+    * is for early developer testing
+    * only covers a limited set of scenarios
+    * is stateless, so it does not actually persist any updates
+    * is open access, so does not allow you to test authorisation
+
+    For details of sandbox testing, or to try out the sandbox using our "Try this API" feature, see the documentation for each endpoint.
+
+    ### Integration testing
+    Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):
+
+    * is for formal integration testing
+    * is stateful, so persists updates
+    * includes authorisation, with [smartcard](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/nhs-smartcards-for-developers) and non-smartcard options
+
+    For more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).
 
     ## Onboarding
     All dispenser suppliers are being asked to integrate with this new service.
@@ -166,7 +196,7 @@ components:
       in: header
       name: Authorization
       description: |
-        An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).
+        An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis).
       required: true
       schema:
         type: string

packages/specification/schemas/fragments/codes.yaml

@@ -1,41 +1,3 @@
-MedicationRequestCourseOfTherapy:
-  type: object
-  required: [system, code]
-  properties:
-    system:
-      type: string
-      description: Codesystem URL for the prescription treatment type.
-      enum:
-        - http://terminology.hl7.org/CodeSystem/medicationrequest-course-of-therapy
-    code:
-      type: string
-      description: |
-        Code identifying the prescription treatment type.
-        * acute: one-off prescriptions
-        * continuous: repeat prescriptions
-      enum: [acute, continuous]
-    display:
-      type: string
-      description: Display value for the prescription treatment type.
-      enum:
-        - Short course (acute) therapy
-        - Continuous long term therapy
-SnomedSctMedication:
-  type: object
-  required: [system, code]
-  properties:
-    system:
-      type: string
-      description: SNOMED codesystem URL.
-      enum: [http://snomed.info/sct]
-    code:
-      type: string
-      description: SNOMED code for the medication, as defined in the Dictionary of Medicines and Devices (DM+D).
-      example: "321196004"
-    display:
-      type: string
-      description: Human readable name for the medication.
-      example: Diazepam 2mg tablets
 SpineErrorOrWarningCode:
   type: object
   required: [system, code]

packages/specification/schemas/resources/UpdatePrescriptionStatusTask.yaml

@@ -45,7 +45,14 @@ properties:
               enum: [https://fhir.nhs.uk/CodeSystem/task-businessStatus-nppt]
             code:
               type: string
-              enum: [With Pharmacy, Ready to Collect, Collected, Dispatched]
+              enum: 
+              - With Pharmacy
+              - With Pharmacy - Preparing Remainder
+              - Ready to Collect
+              - Ready to Collect - Partial
+              - Collected
+              - Dispatched
+              - Not Dispensed
   intent:
     type: string
     description: Order is the allowed value to indicate the update informs an actionable task.