Skip to content

Commit fece70a

Browse files
ORybak5ORybak5
authored
endpoint docs update (#1024)
1 parent 8569b3b commit fece70a

File tree

2 files changed

+1684
-275
lines changed

2 files changed

+1684
-275
lines changed

‎README.md‎

Lines changed: 12 additions & 275 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,16 @@
22

33
National Integration Adaptor - [GP2GP Sending Adaptor](https://digital.nhs.uk/developer/api-catalogue/gp2gp/gp2gp-sending-adaptor)
44

5-
The existing GP2GP solution uses a legacy messaging standard and infrastructure (HL7v3 and Spine TMS). Reliance
6-
on these standards going forward presents a significant barrier to successful GP2GP implementation by new suppliers,
7-
and perpetuation of these standards in the long term presents a risk to the continued operation of GP2GP across all
5+
The existing GP2GP solution uses a legacy messaging standard and infrastructure (HL7v3 and Spine TMS). Reliance
6+
on these standards going forward presents a significant barrier to successful GP2GP implementation by new suppliers,
7+
and perpetuation of these standards in the long term presents a risk to the continued operation of GP2GP across all
88
suppliers.
99

10-
A hybrid solution approach has been selected as the best option for GP2GP adoption by NMEs and transition by existing
10+
A hybrid solution approach has been selected as the best option for GP2GP adoption by NMEs and transition by existing
1111
incumbent suppliers.
1212

13-
The "National Integration Adaptor - GP2GP" implements a GP2GP 2.2b producer using the supplier's existing GP Connect
14-
Provider implementation to extract the Electronic Health Record. Suppliers that have not already implemented a
13+
The "National Integration Adaptor - GP2GP" implements a GP2GP 2.2b producer using the supplier's existing GP Connect
14+
Provider implementation to extract the Electronic Health Record. Suppliers that have not already implemented a
1515
GP2GP 2.2b producer, or those wishing to decommission their existing producer, may deploy the GP2GP adaptor in its place.
1616

1717
## Table of contents
@@ -21,276 +21,13 @@ 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.
2727

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.
232-
Any "in-progress" transfers are excluded from this list, but become available once they either succeed or fail.
233-
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-
```
28+
The API has been documented using the OpenAPI Specification (version 3.0.1). The documentation includes detailed descriptions of endpoints,
29+
parameters, and data models, as well as examples of requests and responses to help developers integrate and use the API effectively
30+
[Ehr Extract OpenAPI Documentation](gp2gp_adaptor_response_docs.yaml)
29431

29532
## Diagrams
29633

@@ -305,9 +42,9 @@ If you are looking to make changes to the adaptor you should first read the [gui
30542

30643
## Disclaimer
30744

308-
All Patient data within this repository is synthetic
45+
All Patient data within this repository is synthetic
30946

31047
## Licensing
31148
This code is dual licensed under the MIT license and the OGL (Open Government License). Any new work added to this repository must conform to the conditions of these licenses. In particular this means that this project may not depend on GPL-licensed or AGPL-licensed libraries, as these would violate the terms of those libraries' licenses.
31249

313-
The contents of this repository are protected by Crown Copyright (C).
50+
The contents of this repository are protected by Crown Copyright (C).

0 commit comments

Comments
 (0)