Search concepts by concept class via REST

In radiology, before you add an order you first need to set the Radiology Concept Classes global property which is a comma separated list of concept class UUIDs which define concepts that are orderable as radiology orders.

I have added the UUID of the Test concept class to that global property as shown by


I have created one concept of the concept class Test with name X-RAY.

When creating a an order. An imaging procedure is is asked which is a concept. If I use a query string like ‘X-RAY’ only one concept is been returned as expected.

When I do a search with other queries like ‘Tr’ or ‘True’ I get no result as expected.

But when I visit http://localhost:8080/openmrs/module/webservices/rest/apiDocs.htm#!/concept/getConcept

And make a get to /openmrs/ws/rest/v1/concept with the class param set to the UUID of the Test concept class and a search query of Tr, I actually get multiple results of which the concept True is one of them. I didn’t expect this. I expected it to behave like radiology add order form and return no result.

I’m trying to reimplement the add order form via angular2 and I’m searching for this concept via REST and I want it to behave exactly like the radiology add order form.

Below is the result of the search results from my angular app running on the same openmrs platform as above

I expected no results. That’s the same behavior I get when I try to do the same via the http://localhost:8080/openmrs/module/webservices/rest/apiDocs.htm

Below is the code in legacyui that handles that

    <td><spring:message code="radiology.imagingProcedure" /><span class="required">*</span></td>
    <td><spring:bind path="concept">
        <openmrs_tag:conceptField formFieldName="concept" formFieldId="conceptId"
          initialValue="${status.editor.value.conceptId}" onSelectFunction="onQuestionSelect"
          includeClasses="${radiologyConceptClassNames}" />
      </spring:bind> <form:errors path="concept" cssClass="error" />
      <div class="description" id="conceptDescription"></div></td>

We’ll not be using that and I don’t have the time to go through the openmrs_tag internals just to understand how to do this.

I found this thread Searching for orderable concepts via REST which led me to Merge pull request #274 from vtuwei/RESTWS-647 · openmrs/ · GitHub

Which talks of a new OrderableResource but it’s not clear how to use that and I don’t see any orderable endpoint in


My server is setup via SDK for Platform 2.0.5 and it’s running Rest Web Services OMOD 2.19.0.f2b4a2

cc @teleivo

I think there are two ways to search for concepts by class:

  1. Use the conceptsearch resource with a conceptClasses query parameter. (This returns ConceptSearchResult instead of Concept, FYI.)
  2. Use the concept resource with query parameters ?searchType=fuzzy&class=xyz&name=xyz.
1 Like

Just tried this

Still doesn’t behave the way I want it to. When I checked the returned result I noticed that the concept class of all returned concepts matched the class parameter. But what I don’t get is why in the radiology order form only X-RAY is returned and the other concepts like True are not.

I can’t find any helpful documentation on searching for a concept via the REST API. This chat seems to point in the right direction, but still no luck. I’m using reference app v12.2.

Right now, I’m trying to search for a concept by name and concept class (“Symptom”).

So, for the /concept resource:

  • Should I use q or name?
  • I want exact name, not fuzzy, so is name better, instead of q?
  • But q also seems to support searchType: I can’t find any documentation on the possible values of searchType (apart from “fuzzy”). Is “exact” possible? Doesn’t seem to work…
  • I don’t really want to match identifiers other than name, so I’d prefer using name instead of q. Is that assumption correct?
  • I also want to add a concept class filter, e.g. “Symptom” only. Again, no documentation: I tried both the UUID and name of the concept class - it made no difference: if I filter on an incorrect concept class, I still get the result back, although it should have filtered it out.
  • The cryptic documentation on the Swagger/OpenAPI page for fields searchType and class mention “Must be used with name”. Does this mean that both these filters must be provided when searching on name?
  • What if I want to search fuzzy on name, but still filter e.g. on conceptClass?

Can someone explain the general patterns for searching on concept? Thanks!

Use name

Yes. Use something like below:


searchType can have fuzzy or equals

Am not sure of what you mean by identifiers. Do you mean concept id, uuid, or something else?

If you want to use the class parameter, then use name instead of q.

It simply means that they will be ignored if you use q instead of name. Otherwise they are optional parameters.

Yes this should be possible with something like below:


1 Like

Thanks @dkayiwa.

OK, let’s ignore class=whatevertheclassis for now, let’s just look at searching on name: according to my tests, I must specify the exact name only, otherwise I get no results…

These return 1 result successfully:

  • Exact name, no searchType: /concept?name=Cough
  • Exact name, searchType=equals: /concept?name=Cough&searchType=equals

With searchType fuzzy, I get no results, although I would have expected the 1 successful result:

  • Exact name (‘Cough’), fuzzy: /concept?name=Cough&searchType=fuzzy
  • Partial name (‘Coug’), fuzzy: /concept?name=Coug&searchType=fuzzy

And why does searching with q=Cough also return no results? Doesn’t q match on partial name?

Are you able to reproduce that problem on this server? Login

No, everything works as expected on that that server.


  • /concept?name=Dyspepsia (1 result)
  • /concept?name=Dyspepsia&searchType=equals (same result)


  • /concept?name=Dyspepsia&searchType=fuzzy (same result)
  • /concept?name=Dyspep&searchType=fuzzy (same result)

Query with q also works on that server: /concept?q=Dyspep

I have now tested ‘Dyspepsia’ on my local instance, I still get the same bugs. So it works on QA, but not on my local one. My local OpenMRS Version is 2.6.0 SNAPSHOT Build 0.

Is there perhaps some search index I must build…?

Try from your equivalent of this page: Login

Thanks @dkayiwa, it works now.

So, for future travellers: if searching on name with searchType=fuzzy, or on q with exact or partial name - and you get no results (where you know you should be getting a result) - rebuild the search index on the admin page at {your host}/openmrs/admin/maintenance/searchIndex.htm.