Skip to content

Commit 6e2593b

Browse files
ORybak5ORybak5
committed
README.md update
1 parent 85eeac3 commit 6e2593b

File tree

1 file changed

+4
-266
lines changed

1 file changed

+4
-266
lines changed

‎README.md‎

Lines changed: 4 additions & 266 deletions
Original file line numberDiff line numberDiff line change
@@ -21,276 +21,14 @@ GP2GP 2.2b producer, or those wishing to decommission their existing producer, m
2121
1. [Guidance on integrating with the adaptors APIs](#how-to-query-the-ehr-status-api)
2222
1. [Documentation on how this adaptor maps GPConnect concepts to GP2GP concepts](https://github.com/NHSDigital/patient-switching-adaptors-mapping-documentation)
2323

24-
## How to query the EHR Status API
24+
## How to query the EHR Status API and the Requests endpoint
2525

2626
An API is provided to query the status of any transfer to an incumbent.
27-
28-
Requests can be made to the following endpoint using the *Conversation ID (SSP-TraceID)* of the transfer:
29-
30-
```http request
31-
{location of gp2gp service}/ehr-status/{conversationId} [GET]
32-
```
33-
34-
The response will contain the following fields:
35-
36-
### EhrStatus
37-
38-
| Field name | Description | Data type | Possible values | nullable |
39-
|---------------------|-----------------------------------------------------------------------------------------------------------------|--------------------------------------------------|------------------------------------------------------------------------------------------------------------------|----------|
40-
| originalRequestDate | The date and time of the original request | ISO-8601 | | False |
41-
| migrationStatus | The current state of the transfer, a status of COMPLETE_WITH_ISSUES is given if placeholder documents were sent | string / enum | COMPLETE <br/><br/>COMPLETE_WITH_ISSUES <br/><br/> FAILED_NME <br/><br/> FAILED_INCUMBENT <br/><br/> IN_PROGRESS | False |
42-
| attachmentStatus | An array of statuses for each document sent during the transfer | Array of **AttachmentStatus** (See below) | | False |
43-
| migrationLog | An array containing details of acknowledgments received during the transfer | Array of **ReceivedAcknowledgement** (See below) | | False |
44-
45-
<br/>
46-
47-
### Subtypes
48-
49-
#### AttachmentStatus
50-
51-
| Field name | Description | Data type | Possible values | Nullable |
52-
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------|-----------------------------------------------------|----------|
53-
| identifier | An array of identifiers taken from the `identifier` element of the GP Connect `DocumentReference` | Array of **Identifier** (see below) | | False |
54-
| fileStatus | The status of the document sent to the winning practice (can be used to identify if a placeholder document was sent) | string / enum | PLACEHOLDER <br/><br/>ORIGINAL_FILE <br/><br/>ERROR | False |
55-
| filename | The filename sent to winning practice in the GP2GP message | string | | False |
56-
| originalDescription | The description of the file as given by the `description` element of the GP Connect `DocumentReference` resource.<br/><br/> This is inserted into the GP2GP placeholder document as the original filename and suffix. So should be of the form *filename.suffix*, e.g. *referral.txt* | string | | True |
57-
58-
<br/>
59-
60-
#### Identifier
61-
62-
| Field name | Description | Data type | Nullable |
63-
|------------|---------------------------------------------------------------------------|-----------|----------|
64-
| system | The `system` element of the Gp Connect `DocumentReference.identifier` | string | False |
65-
| value | The `identifier` element of the Gp Connect `DocumentReference.identifier` | string | False |
66-
67-
68-
<br/>
69-
70-
#### ReceivedAcknowledgement
71-
72-
| Field name | Description | Data type | Nullable |
73-
|--------------------|------------------------------------------------------------------------------------------------------------|--------------------------------|----------|
74-
| received | The date and time the acknowledgment was received | ISO-8601 | False |
75-
| conversationClosed | If the acknowledgement ended the transfer, the date and time the conversation was closed can be found here | ISO-8601 | True |
76-
| errors | An array of errors which will be populated in the case of a negative / rejected acknowledgement | Array of **Error** (see below) | True |
77-
| messageRef | the Message ID of the message that has been acknowledged | string | False |
78-
79-
<br/>
80-
81-
#### Error
82-
83-
| Field name | Description | Data type | Nullable |
84-
|------------|----------------------------------------------------|-----------|----------|
85-
| code | The GP2GP response code from the negative response | string | False |
86-
| display | The GP2GP response text from the negative response | string | False |
87-
88-
<details>
89-
<summary>EHR Status example responses</summary>
90-
91-
#### Successful migration, with single positive acknowledgement of EHR Extract (conversation closed and no errors):
92-
```json
93-
94-
{
95-
"attachmentStatus": [],
96-
"migrationLog": [
97-
{
98-
"received": "2023-07-24T09:39:09.377Z",
99-
"conversationClosed": "2023-07-24T09:39:09.377Z",
100-
"errors": null,
101-
"messageRef": "0BEBCA12-8BE4-44B4-BDC0-016A4FE3D107"
102-
}
103-
],
104-
"migrationStatus": "COMPLETE",
105-
"originalRequestDate": "2023-07-24T09:38:50.947Z",
106-
"fromAsid": "918999198738",
107-
"toAsid": "200000000359"
108-
}
109-
```
110-
111-
#### Failed by requester, with single negative acknowledgement of EHR Extract (conversation closed and error):
112-
113-
```json
114-
115-
{
116-
"attachmentStatus": [],
117-
"migrationLog": [
118-
{
119-
"received": "2023-07-21T16:09:19.594Z",
120-
"conversationClosed": "2023-07-21T16:09:19.594Z",
121-
"errors": [
122-
{
123-
"code": "11",
124-
"display": "Failed to successfully integrate EHR Extract."
125-
}
126-
],
127-
"messageRef": "C5271147-3D89-4EF6-A719-01AEB3AD00A1"
128-
}
129-
],
130-
"migrationStatus": "FAILED_INCUMBENT",
131-
"originalRequestDate": "2023-07-21T16:09:12.695Z",
132-
"fromAsid": "918999198738",
133-
"toAsid": "200000000359"
134-
}
135-
```
136-
137-
138-
#### Failed by requester, with multiple positive acknowledgements for COPC messages (without conversation closed) and one negative acknowledgement for EHR Extract (conversation closed and error):
139-
140-
```json
141-
142-
{
143-
"attachmentStatus": [
144-
{
145-
"identifier": [
146-
{
147-
"system": "https://EMISWeb/A82038",
148-
"value": "ad174c84-51d1-4744-89e3-7918a31248d1"
149-
}
150-
],
151-
"fileStatus": "ORIGINAL_FILE",
152-
"fileName": "54E94A29-B0CC-4CD6-86B0-B21C9C0CA894.doc",
153-
"originalDescription": "Referral for further care (22-Dec-2020)"
154-
},
155-
{
156-
"identifier": [
157-
{
158-
"system": "https://EMISWeb/A82038",
159-
"value": "D7AF52BA-79BA-4AF8-9010-F0C2DF916CEC"
160-
}
161-
],
162-
"fileStatus": "ORIGINAL_FILE",
163-
"fileName": "629BF3F7-C71F-49D7-8FCD-AEE16C11AFBD.doc",
164-
"originalDescription": "Referral for further care (22-Dec-2020)"
165-
},
166-
{
167-
"identifier": [
168-
{
169-
"system": "https://EMISWeb/A82038",
170-
"value": "D7AF52BA-79BA-4AF8-9010-F0C2DF916CEC"
171-
}
172-
],
173-
"fileStatus": "ORIGINAL_FILE",
174-
"fileName": "2F73A243-0F94-4683-B3F9-727CE7780815.doc",
175-
"originalDescription": "Referral for further care (22-Dec-2020)"
176-
}
177-
],
178-
"migrationLog": [
179-
{
180-
"received": "2023-07-24T10:42:18.591Z",
181-
"conversationClosed": null,
182-
"errors": null,
183-
"messageRef": "ED2FB0DD-52AE-4EBC-B596-3BCA9CF5B272"
184-
},
185-
{
186-
"received": "2023-07-24T10:42:19.176Z",
187-
"conversationClosed": null,
188-
"errors": null,
189-
"messageRef": "5068BAE1-7228-4E59-B3AD-92FA5CBDE4AC"
190-
},
191-
{
192-
"received": "2023-07-24T10:42:19.467Z",
193-
"conversationClosed": null,
194-
"errors": null,
195-
"messageRef": "A9E37B68-07F4-43A5-889E-645D6681CE68"
196-
},
197-
{
198-
"received": "2023-07-24T10:42:22.611Z",
199-
"conversationClosed": "2023-07-24T10:42:22.611Z",
200-
"errors": [
201-
{
202-
"code": "99",
203-
"display": "Unexpected condition."
204-
}
205-
],
206-
"messageRef": "E600D1D4-D5BE-4D0D-8080-F7F6188B0548"
207-
}
208-
],
209-
"migrationStatus": "FAILED_INCUMBENT",
210-
"originalRequestDate": "2023-07-24T10:42:05.757Z",
211-
"fromAsid": "918999198738",
212-
"toAsid": "200000000359"
213-
}
214-
```
215-
#### Failed by adaptor, due to a PATIENT_NOT_FOUND error from the GP Connect provider's migrate structured endpoint
216-
```json
217-
218-
{
219-
"attachmentStatus": [],
220-
"migrationLog": [],
221-
"migrationStatus": "FAILED_NME",
222-
"originalRequestDate": "2023-07-26T15:36:22.284Z",
223-
"fromAsid": "918999198738",
224-
"toAsid": "200000000359"
225-
}
226-
```
227-
</details>
228-
229-
## How to query the Requests endpoint
230-
231-
An API is provided to query the status of all transfers to an incumbent.
23227
Any "in-progress" transfers are excluded from this list, but become available once they either succeed or fail.
23328

234-
Requests can be made to the following endpoint, where each attribute within the JSON POST body is an optional filter criteria.
235-
236-
```http request
237-
POST /requests
238-
Content-Type: application/json
239-
240-
{
241-
"fromDateTime": "2020-10-31T01:30:00.000Z",
242-
"toDateTime": "2030-10-31T01:30:00.000Z",
243-
"fromAsid": "",
244-
"toAsid": "",
245-
"fromOdsCode": "",
246-
"toOdsCode": ""
247-
}
248-
```
249-
250-
The response will contain a JSON array of the following:
251-
252-
### EhrStatusRequest
253-
| Field name | Description | Data type | Possible values | nullable |
254-
| ------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------- | -------- |
255-
| initialRequestTimestamp | The date and time of the original request. | ISO-8601 | | False |
256-
| actionCompletedTimestamp | The date and time of when the transfer completed. | ISO-8601 | | False |
257-
| nhsNumber | | string | | False |
258-
| conversationId | | string | | False |
259-
| fromAsid | | string | | False |
260-
| toAsid | | string | | False |
261-
| fromOdsCode | | string | | False |
262-
| toOdsCode | | string | | False |
263-
| migrationStatus | The current state of the transfer, a status of COMPLETE_WITH_ISSUES is given if placeholder documents were sent | string / enum | COMPLETE <br/> COMPLETE_WITH_ISSUES <br/> FAILED_NME <br/> FAILED_INCUMBENT | False |
264-
265-
266-
#### Example EhrStatusRequest response
267-
268-
```json
269-
[
270-
{
271-
"initialRequestTimestamp":"2023-09-20T11:47:58.966Z",
272-
"actionCompletedTimestamp":"2023-09-20T11:54:19.552Z",
273-
"nhsNumber":"9729734925",
274-
"conversationId":"59B118DB-70C3-4883-8A60-5E725981F003",
275-
"migrationStatus":"COMPLETE",
276-
"fromAsid":"858000001001",
277-
"toAsid":"200000001908",
278-
"fromOdsCode":"C88046",
279-
"toOdsCode":"B84012"
280-
},
281-
{
282-
"initialRequestTimestamp":"2023-09-20T12:18:10.364Z",
283-
"actionCompletedTimestamp":"2023-09-20T12:18:13.923Z",
284-
"nhsNumber":"9729735336",
285-
"conversationId":"C2A59970-57AF-11EE-AFE6-CD607DC58E3B",
286-
"migrationStatus":"FAILED_INCUMBENT",
287-
"fromAsid":"200000000169",
288-
"toAsid":"200000001908",
289-
"fromOdsCode":"P84009",
290-
"toOdsCode":"B84012"
291-
}
292-
]
293-
```
29+
The API has been documented using the OpenAPI Specification (version 3.0.1). The documentation includes detailed descriptions of endpoints,
30+
parameters, and data models, as well as examples of requests and responses to help developers integrate and use the API effectively
31+
[Ehr Extract OpenAPI Documentation](gp2gp_adaptor_response_docs.yaml)
29432

29533
## Diagrams
29634

0 commit comments

Comments
 (0)