Failure to have appointments endpoints work with dev3 API

Hello everyone, for the last couple of weeks, the appointments team has been blocked while trying to build the appointments module.

The weird part is that the appointments endpoints work for some API but for some reason are failing for the dev3 API.

The working API and UI can be viewed in this video on this PR. O3-1431: Create an appointment. by hadijahkyampeire · Pull Request #295 · openmrs/openmrs-esm-patient-management · GitHub.

OR by running the patient management locally with this command.

npx openmrs develop --sources 'packages/esm-appointments-app' --port 8086 --backend=https://data.kenyahmis.org:8500 --api-url=/openmrs

Working API https://data.kenyahmis.org:8500.

We need backend help to figure out why the dev3 appointments are not working as expected.

cc @zacbutko @minimalist @dkibet @dkayiwa @grace @dkigen @kdaud @ibacher

1 Like

Can you describe the exact REST call that you are making? Is it a POST or GET? What parameters are you passing, if any? What is the exact url? Give as much detail as one would need to reproduce it with any REST API client like postman.

The issue, almost certainly, is that the 3.x reference application does not have the metadata necessary to setup the appointments module. We need someone who understands what metadata is necessary to add that to the distro setup here.

I will share some screenshots shortly I am still in a conference.

@dkayiwa almost all the appointments endpoints are failing, some throw a 404 in dev3 yet they exist in the other backend that the Palladium team uses. The one that I was working with was a POST to /ws/rest/v1/appointment.

Hi all here,

Thanks for reporting this @hadijah315. I’ve been recently working on expanding the reference application demodata and had to expand the demo meta-data as well in the same ticket(RA-1993). Hopefully when the underlying PRs are merged in plus the other one on the appointments module, you’d be in better position to try out again.

cc @angshuonline, @gsluthra

3 Likes

Currently dev3 is running Bahmni Appointment Scheduling v1.5.0. A call to a path like this works:

https://dev3.openmrs.org/openmrs/ws/rest/v1/appointments

Glancing at the code, it looks like there’s a bespoke approach to the REST API. For example, instead of

GET /appointment/efc60f88-3755-45b9-97a4-bd7bd4786fd5

it expects

GET /appointment?uuid=efc60f88-3755-45b9-97a4-bd7bd4786fd5

Perhaps the Bahmni Appointment module’s REST API is documented somewhere? (I didn’t spend much time googling for it)

1 Like

@dkayiwa here are some of the endpoints and their results;

  1. https://dev3.openmrs.org/openmrs/ws/rest/v1/appointment/appointmentStatus?forDate=2022-09-14T00:00:00.000+0300&status=Scheduled GET, returns 404 and it is expected to return the scheduled appointments for that day.

And good news I just tested the one for posting it works now. cc @zacbutko

Just to clarify about the POST endpoint working now in dev3.

With payload

{
    "appointmentKind": "WalkIn",
    "status": "Requested",
    "serviceUuid": "df396972-d8a3-42c5-aee4-23e9435106da",
    "startDateTime": "2022-09-15T00:00:00+03:00",
    "endDateTime": "2022-09-15T00:00:00+03:00",
    "comments": "Creating appointments",
    "locationUuid": "",
    "patientUuid": "471a19d0-930f-42bf-9126-c787a3ff8420"
}

and returning back the created appointment as

{
    "uuid": "0268dc90-66dc-4087-a875-89e9eabc44f7",
    "appointmentNumber": "0000",
    "patient": {
        "identifier": "10004KK",
        "name": "Test",
        "uuid": "471a19d0-930f-42bf-9126-c787a3ff8420"
    },
    "service": {
        "appointmentServiceId": 1,
        "name": "Cardiology Consultation",
        "description": null,
        "speciality": {},
        "startTime": "09:00:00",
        "endTime": "17:30:00",
        "maxAppointmentsLimit": 30,
        "durationMins": 30,
        "location": {},
        "uuid": "df396972-d8a3-42c5-aee4-23e9435106da",
        "color": "#00ff00",
        "initialAppointmentStatus": null,
        "creatorName": null
    },
    "serviceType": null,
    "provider": null,
    "location": null,
    "startDateTime": 1663189200000,
    "endDateTime": 1663189200000,
    "appointmentKind": "WalkIn",
    "status": "Requested",
    "comments": "Creating appointments",
    "additionalInfo": null,
    "teleconsultation": null,
    "providers": [],
    "voided": false,
    "extensions": {
        "patientEmailDefined": false
    },
    "teleconsultationLink": null,
    "recurring": false
}

Posting to which endpoint works now? @hadijah315 do you have a list of all endpoints you need to be working? Maybe it would be helpful to see the list of which ones are working vs not working

Side note: Does our CI leverage any automated endpoint testing?

Hello, @zacbutko and @dkayiwa I am sorry I didn’t capture the working endpoint details but it’s the POST endpoint to /appointment. I have a list of endpoints that were shared with me as some of the useful endpoints that I will need to develop the appointments module.

Just in case the Pastebin link fails to work, this is the JSON.

{
	"info": {
		"_postman_id": "bea353f2-acff-40fb-a303-e563a11a7d29",
		"name": "New Collection",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"_exporter_id": "9064607"
	},
	"item": [
		{
			"name": "Get all appointments",
			"request": {
				"auth": {
					"type": "basic",
					"basic": [
						{
							"key": "password",
							"value": "Admin123",
							"type": "string"
						},
						{
							"key": "username",
							"value": "Admin",
							"type": "string"
						}
					]
				},
				"method": "GET",
				"header": [],
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointment/all",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointment",
						"all"
					]
				}
			},
			"response": []
		},
		{
			"name": "Get all appointment by date",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointment/all?forDate=2022-08-02T00:00:00.0Z",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointment",
						"all"
					],
					"query": [
						{
							"key": "forDate",
							"value": "2022-08-02T00:00:00.0Z"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "Save Appointment",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"providerUuid\": \"823fdcd7-3f10-11e4-adec-0800271c1b75\",\n    \"appointmentNumber\": \"1\",\n    \"patientUuid\": \"2c33920f-7aa6-48d6-998a-60412d8ff7d5\",\n    \"serviceUuid\": \"c36006d4-9fbb-4f20-866b-0ece245615c1\",\n    \"startDateTime\": \"2017-07-20\",\n    \"endDateTime\": \"2017-07-20\",\n    \"appointmentKind\": \"WalkIn\",\n    \"providers\": [\n        {\n            \"uuid\": \"2d15071d-439d-44e8-9825-aa8e1a30d2a2\",\n            \"comments\": \"available\",\n            \"response\": \"ACCEPTED\"\n        }\n    ]\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointment",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointment"
					]
				}
			},
			"response": []
		},
		{
			"name": "Get all non-cancelled, non-voided future appointment by appointmentServiceUuid",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointment/futureAppointmentsForServiceType?appointmentServiceTypeUuid=678906e5-9fbb-4f20-866b-0ece24564578",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointment",
						"futureAppointmentsForServiceType"
					],
					"query": [
						{
							"key": "appointmentServiceTypeUuid",
							"value": "678906e5-9fbb-4f20-866b-0ece24564578"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "Count appointment per service type in a date range",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointment/appointmentSummary?startDate=2022-08-02T00:00:00.0Z&endDate=2022-08-02T00:00:00.0Z",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointment",
						"appointmentSummary"
					],
					"query": [
						{
							"key": "startDate",
							"value": "2022-08-02T00:00:00.0Z"
						},
						{
							"key": "endDate",
							"value": "2022-08-02T00:00:00.0Z"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "Search appointments by serviceUuid (POST Request)",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"serviceUuid\": \"c36006e5-9fbb-4f20-866b-0ece245615a6\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointment/search",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointment",
						"search"
					]
				}
			},
			"response": []
		},
		{
			"name": "Create audit info when appointment is editted",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"uuid\": \"c36006e5-9fbb-4f20-866b-0ece245615a7\",\n    \"appointmentNumber\": \"1\",\n    \"patientUuid\": \"2c33920f-7aa6-48d6-998a-60412d8ff7d5\",\n    \"serviceUuid\": \"c36006d4-9fbb-4f20-866b-0ece245615c1\",\n    \"serviceTypeUuid\": \"672546e5-9fbb-4f20-866b-0ece24564578\",\n    \"startDateTime\": \"2017-07-20\",\n    \"endDateTime\": \"2017-07-20\",\n    \"comments\": \"Some notes\",\n    \"appointmentKind\": \"WalkIn\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointment",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointment"
					]
				}
			},
			"response": []
		},
		{
			"name": "Undo appointment status change, should return an error object",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointment/undoStatusChange/uuid",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointment",
						"undoStatusChange",
						"uuid"
					]
				}
			},
			"response": []
		},
		{
			"name": "Create appointment service",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"name\": \"Cardiology Consultation\",\n    \"startTime\": \"09:00:00\",\n    \"endTime\": \"17:30:00\",\n    \"durationMins\": \"30\",\n    \"locationUuid\": \"c36006e5-9fbb-4f20-866b-0ece245615a1\",\n    \"specialityUuid\": \"c36006e5-9fbb-4f20-866b-0ece245615a1\",\n    \"maxAppointmentsLimit\": \"30\",\n    \"color\": \"#00ff00\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointmentService",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointmentService"
					]
				}
			},
			"response": []
		},
		{
			"name": "Create appointment service with only name",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"name\": \"Sample Appointment Servie\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointmentService",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointmentService"
					]
				}
			},
			"response": []
		},
		{
			"name": "Create appointment service with service availability",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"name\": \"Cardiology Consultation\",\n    \"startTime\": \"09:00:00\",\n    \"endTime\": \"17:30:00\",\n    \"durationMins\": \"30\",\n    \"locationUuid\": \"c36006e5-9fbb-4f20-866b-0ece245615a1\",\n    \"specialityUuid\": \"c36006e5-9fbb-4f20-866b-0ece245615a1\",\n    \"maxAppointmentsLimit\": \"30\",\n    \"color\": \"#0000ff\",\n    \"weeklyAvailability\": [\n        {\n            \"dayOfWeek\": \"MONDAY\",\n            \"startTime\": \"09:00:00\",\n            \"endTime\": \"17:30:00\",\n            \"maxAppointmentsLimit\": \"10\"\n        }\n    ]\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointmentService",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointmentService"
					]
				}
			},
			"response": []
		},
		{
			"name": "Create appointment with service type",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"name\": \"Cardiology Consultation\",\n    \"startTime\": \"09:00:00\",\n    \"endTime\": \"17:30:00\",\n    \"durationMins\": \"30\",\n    \"color\": \"#fff000\",\n    \"locationUuid\": \"c36006e5-9fbb-4f20-866b-0ece245615a1\",\n    \"specialityUuid\": \"c36006e5-9fbb-4f20-866b-0ece245615a1\",\n    \"serviceTypes\": [\n        {\n            \"name\": \"type1\",\n            \"duration\": \"20\"\n        }\n    ]\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointmentService",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointmentService"
					]
				}
			},
			"response": []
		},
		{
			"name": "Create appointment with initial appointment status",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"name\": \"Cardiology Consultation\",\n    \"initialAppointmentStatus\": \"Requested\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointmentService",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointmentService"
					]
				}
			},
			"response": []
		},
		{
			"name": "Get all appointment services",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointmentService/all/default",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointmentService",
						"all",
						"default"
					]
				}
			},
			"response": []
		},
		{
			"name": "Get appointment service by uuid",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointmentService?uuid=some-uuid",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointmentService"
					],
					"query": [
						{
							"key": "uuid",
							"value": "some-uuid"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "Delete appointment service by appointment servie uuid",
			"request": {
				"method": "DELETE",
				"header": [],
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointmentService?uuid=some-delete-uuid",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointmentService"
					],
					"query": [
						{
							"key": "uuid",
							"value": "some-delete-uuid"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "Update appointment service",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"name\": \"Chemotherapy\",\n    \"startTime\": \"09:00:00\",\n    \"endTime\": \"17:30:00\",\n    \"durationMins\": \"30\",\n    \"uuid\": \"uuid\",\n    \"locationUuid\": \"c36006e5-9fbb-4f20-866b-0ece245615a1\",\n    \"specialityUuid\": \"c36006e5-9fbb-4f20-866b-0ece245615a1\",\n    \"serviceTypes\": [\n        {\n            \"name\": \"stage 1\",\n            \"duration\": \"20\",\n            \"uuid\": \"c36006d5-9fcc-4f20-866b-0ece245615b1\"\n        }\n    ]\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointmentService",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointmentService"
					]
				}
			},
			"response": []
		},
		{
			"name": "Get load by serviceType for a dange range",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "https://dev3.openmrs.org/openmrs/ws/rest/v1/appointmentService/load?uuid=99b2ea38-e041-41eb-9ed2-25a265068764&startDateTime=&endDateTime=",
					"protocol": "https",
					"host": [
						"dev3",
						"openmrs",
						"org"
					],
					"path": [
						"openmrs",
						"ws",
						"rest",
						"v1",
						"appointmentService",
						"load"
					],
					"query": [
						{
							"key": "uuid",
							"value": "99b2ea38-e041-41eb-9ed2-25a265068764"
						},
						{
							"key": "startDateTime",
							"value": ""
						},
						{
							"key": "endDateTime",
							"value": ""
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "Get all appointment by date and status",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "http:///openmrs/rest/v1/appointmentStatus?forDate=2022-08-02&status=missed",
					"protocol": "http",
					"path": [
						"openmrs",
						"rest",
						"v1",
						"appointmentStatus"
					],
					"query": [
						{
							"key": "forDate",
							"value": "2022-08-02"
						},
						{
							"key": "status",
							"value": "missed"
						}
					]
				}
			},
			"response": []
		}
	]
}

Please let me know if you need me to share more information about the appointments.

The other additional endpoints I can think of are the ones to support the change of the appointment status, all use this endpoint POST to /ws/rest/v1/appointments/${appointmentUuid}/status-change
with a payload

{ toStatus: status', onDate: statusChangeTime, timeZone: timeZone }

Statuses can be [CheckedIn, Completed, Missed, Cancelled ] depending on the action and this is expected to update the apppointement.

These can also be tested in the Bahmin Demo UI Credentials superman/Admin123.

Check-In request

Expected response of an updated appointment.

@hadijah315 i have tested the endpoints that you have shared above, and they all work well on dev3. Can you be specific with any end point that you tested but does not behave as you expect? It would be great if you give details for the exact url, the data you are posting, and the expected results.

Oh, that’s great news then, it might be that we are the ones consuming the wrong endpoint(the one quoted above), the endpoint that we are consuming to retrieve appointments based on their statuses is the one that is throwing a 404 which means it might be a wrong one, I will talk to the team and we use a working endpoint. Maybe @dkayiwa could you help me tell me how many GET endpoints are there for appointments and what response should I expect from them, I see many GET endpoints and I am wondering which one returns all appointments and what parameters it takes for example if I want Scheduled appointments and does it currently have any appointments? do they get saved there when we create them in dev3?

I think it would be more productive if you can either mention specific queries you’re trying that are failing, with the parameters you’re using (the Postman collection has been very helpful) or the specific questions you would like to be able to ask the backend. The appointments module was developed primarily by the Bahmni team, so the OpenMRS Platform Team is not really well-equipped to give you comprehensive documentation on the module API. If we have specific questions, we can probably work through the code.

Just to add to this, the main chunks of the API seem to be defined in these 6 Java classes, so we can start tracing things from there…

1 Like