Searching for orderable concepts via REST

Development
, ,
1

Dear All,

We are beginning work on an angular2 module for facilitating order entry. As part of this effort, we’d like to allow the user to search for orderable concepts. My understanding is that this is currently not possible via the RESTWS module. Is this the case?

Vincent Tuwei (@vtuwei) , a developer on the AMPATH team, is very interested to beginning to support the RESTWS module. As a first project, we’d like him to work on this feature (assuming it doesn’t exist). We welcome suggestions on how best to approach adding this to the module.

Thanks.

JJ

2 Likes
2

That’s great @jdick and @vtuwei.

I don’t think this feature is currently supported, so yes, please work on it!

Here are some of the steps I would take to doing this:

  1. Lead a discussion about how this should work. What makes a concept “orderable”? Would you allow searching for orderable concepts within a single order type (tests, drug, etc) or across all orderables? Are you even strictly talking about concept search? Or should you also be able to find a drug formulation this way?

  2. See how the existing code for searching for concepts works.

  1. Write the code. :slight_smile: If this is in fact a concept search then I would implement this as a SearchHandler<Concept> (like those last two links). If the results may be concepts but may also be drugs, I think you’d need to introduce a new OrderableResource.

PS- Hopefully you’re on Platform 1.10+, because that’s when we completely redid the order entry APIs…

3

Hi @darius

I found out that what we wanted is implemented in ConceptSearchResource1_9.java.

We can search for orderable concepts (Tests, Drugs) in one requests using the conceptsearch resource as the conceptClasses param accepts multiple uuids.

http://localhost:8080/openmrs/ws/rest/v1/conceptsearch?conceptClasses=8d4907b2-c2cc-11de-8d13-0010c6dffd0f&conceptClasses=8d490dfc-c2cc-11de-8d13-0010c6dffd0f&v=full

4

@darius and @burke, we could update this code to work with v1.9 or we could pursue an alternate strategy to searching for orderable concepts. What do you (and others) recommend?

5

I’d think ConceptSearchResource should have been a search handler and not its own independent resource, because based on conventions in the rest module it would be hard for one to find it.

6

I don’t fully understand the question. What version of OpenMRS Platform are you running now? (e.g. does the existing resource work for you or not?)

According to the javadoc, this is separate for a reason:

Resource for ConceptSearchResult, supporting only search operations for concepts and returns ConceptSearchResults instead of Concepts, this is useful when searching for concepts and the client needs to know extra details about the matches e.g the matched words, concept names and their weights

7

That makes sense then

8

We don’t want API clients to have to know or manage the knowledge of which concepts are orderable.

Our API should provide a mechanisms for:

  • Get list of orderable concept classes
  • Search for orderable concepts without having to know or specify orderable classes
  • Search for orderable concepts within one or more specific orderable classes

The current knowledge of which concepts are orderable is defined as all concepts with a concept classes that are orderable. The list of orderable concpet classes is the set of concept classes within order_type_class_map.concept_class_id.

In the future, OpenMRS will have a way to individually mark concepts as not orderable (i.e., orderable concepts will be defined as concepts with a concept class within the list of orderable classes and not marked as unorderable). As our order service is more widely adopted, implementations will certainly have the need to individually disable ordering of specific concepts that are in orderable classes. This specific feature does not need to be supported now, but it underscores why it’s important that these business decisions are behind the API and not passed on for clients of the API to manage.

9

Here’s some brainstorming on a RESTful API for getting orderables.

  • Get list of orderable concept classes

GET /orderable/classes

HTTP/1.0 200 OK
[
  { "display": "TEST", "uuid": "...", ... },
  { "display": "DRUG", "uuid": "...", ... },
  ...
]
  • Search for orderable concepts without having to know or specify orderable classes

GET /orderable?q=ampicillin

HTTP/1.0 200 OK
[
  { display:"potassium", conceptClass: { "display": "DRUG", ... }, ... },
  { display:"serum potassium", conceptClass: { "display": "TEST", ... }, .. },
  ...
]
  • Search for orderable concepts within one or more specific orderable classes

GET orderable?q=tb&orderableClasses=TEST,REFERRAL

Same as above, but filtered to specified concept classes.

/cc @darius, @mseaton … thoughts?

10

One cross-cutting comment is that all of these should respect our standard configuration for paging (e.g. the return isn’t a plain array, but it’s an object with results and links).

If you want to get orderable concept classes it should be GET /conceptclass?orderable=true.

But shouldn’t you instead use the existing ordertype resource, e.g. GET /ordertype?

See also the OrderEntryConfig resource that I introduced to RESTWS while working on the orderentryui module. (This currently includes drugRoutes, drugDosingUnits, drugDispensingUnits, durationUnits, testSpecimenSources, and orderFrequencies; the idea is that it gives you all the reference data you need to power an “order entry” screen.)

GET /orderable?q=ampicillin

I hope this can return both Concepts and Drugs. So we might want to have them separated out in the return, e.g.

{
    concepts: [ ... ],
    drugs: [ ... ]
}

Or else we should decorate the objects returned with a “type”.

I would prefer GET orderable?q=tb&orderTypes=TEST,REFERRAL. Isn’t the most common case to filter on OrderType not ConceptClass?

We could also support GET orderable?q=tb&conceptClasses=LabSet,MiscSet.

11

Thanks to all of you for comments. Would love to move this forward but it seems we need some resolution on the design. What’s the best way to move this forward?

JJ

12

The surest way is to have @jthomas schedule a design call.

Also, you could respond here on the Talk thread about whether this is going on the right direction for you.

-Darius (by phone)

1 Like
13

@jdick if you would like to have a design call we can get that scheduled. Who would you like to have on the call?@burke will not be on Wards until March 13. Also I know @darius is going to be on vacation for the next two weeks and will not be back until March 20th call (Note: @burke will be on vacation that week)

14

(If things are time-sensitive, I don’t think it’s necessary to have both Burke and I on the call in order to make some forward progress. Hopefully both of our posts on this thread illuminate our general thinking.)

1 Like
15

Hi @burke, @darius. I plan to start working on these features immediately and i need your input/suggestions.

As @darius mentioned we can use the /ordertype?v=full to get the concept classes. @darius is it necessary to create a new resource (/orderable/classes) or edit the existing concept class resource to include the orderable filter?

From the discussions, i will implement the orderable search resource function.

I will create a “OrderableConceptResource” resource with /orderable endpoint. It will accept the following params:

  • q
  • conceptClasses ie LabSet
  • orderTypes ie Test
  • v

The output will look this

    [
      { 
    	"display": "",
    	"concept": {...},
    	"conceptClass": {...},
    	"drugs": []
      }
    ]

@daruis which submodule will i create this resource? Advise on naming and the output.

16

@vtuwei since you are creating new end point urls, i would recommend new resource classes. As for the submodule, it depends on the lowest platform version required by your changes. If for instance it is platform 1.10.x, then the omod-1.10 submodule. And the rest follows the same pattern. For naming, i like your choice of OrderableConceptResource Regarding output, does that cater for your needs?

17

@dkayiwa we are using version 1.11. I will develop it in omod-1.10. The output caters for our needs. Thank you for the feedback.

18

As I said above:[quote=“darius, post:10, topic:10161”] If you want to get orderable concept classes it should be GET /conceptclass?orderable=true. [/quote]

In other words, no, do not introduce /orderable/classes. Because you want to query the server for ConceptClasses that are orderable, this should be done as a query on the new conceptclass resource.

I’d like to ask for a small change to this. The Java class should be called OrderableResource to align with the endpoint we’re exposing it as.

I’m not 100% sure about this output. I think we’ll have to discuss with @burke about it when he has more time. But you can get started on implementing any underlying queries that you need, just knowing that we might need to modify the exact format.

19

Thanks @darius. Please help create a ticket for this on jira

20

@vtuwei as a community member, you are also empowered to create this ticket. So go ahead and do it. :slight_smile: https://wiki.openmrs.org/display/docs/Tickets