Create, Read, Update client samples/orders + results

Functional How-to
1

Hi SENAITE team…

Glad to join you.

Continuing discussion from SENAITE + FHIR: status update and roadmap?

I’m trying to use the current jsonapi available with SENAITE documented here while it’s not yet FHIR-ized. Could there be a more comprehensive api documentation covering all available options with the supported portal types [ Client, AnalysisRequest, AnalysisService]?

In the end my use-case will require for an ability to translate from fhir to senaite.jsonapi. I’d like to therefore also know whether the following FHIR resources are correctly translated to what senaite api understands theoretically,

FHIR → SENAITE JSONAPI
patient → client
ServiceRequest (A lab Order) → AnalysisRequest
DiagnosticReport (Results from the ServiceRequest) → AnalysisService

Any advise on this is helpful already. Thanks.

Regards,
Nathan.

1 Like
2

Hi @ruhanga and welcome!

SENAITE JSON API is designed to query for any content type available in the LIMS. Also, the API is able to retrieve data from content types defined in other add-ons for SENAITE, such as SENAITE Health or customer-specific extensions. Therefore, there is no specific documentation for the content types supported by SENAITE JSON API.

If you want to know the content types registered in SENAITE and their schema you can find them inside the “content” folder from any SENAITE add-on:

The schema is the way SENAITE (Plone) describes data models. For examples, patient schema defines allowed input data fields and its format, validators and class methods to manipulate the object.

Also, by getting an object by its UID, you will get all available information. Example:

  • https://demo.your_senaite.com/@@API/senaite/v1/analysisrequest/6202fee2688646aeb12f909d101ee5fa

    "count": 1,
"pagesize": 25,
"items": [
  {
    "SampleTypeTitle": "Dust",
    "StorageLocation": {
      
    },
    "PublicationSpecification": null,
    "StorageLocationUID": null,
    "RejectionReasons": null,
    "Preserver": null,
    "ResultsInterpretation": null,
    "Template": null,
    "Sampler": null,
    "ContactUID": "e3a3db1ab4aa470dbb2c84970315b617",
    "exclude_from_nav": null,
    "effectiveDate": null,
    "ContactFullName": "Rita Mohale",
    "ScheduledSamplingSampler": null,
    "TemplateUID": null,
    "ClientSampleID": null,
    "start": null,
    "Composite": null,
    "MemberDiscount": "20.00",
    "ContactUsername": "ritamo",
    "SamplerFullName": null,
    "DatePublished": "2020-07-03 20:01 PM",
    "ContactEmail": "mohale@example.com",
    "parent_id": "client-1",
    "ResultsRange": null,
    "CreatorEmail": "labmanager1@example.com",
    ...

I hope this answer helps you to map FHIR resources to SENAITE content types.

2 Likes
3

Thanks alot @Espurna! This clears away some mist about SENAITE content types. I don’t have much background with Python but will hopefully get along well.
Just for a start @Espurna, how would I be able to query results or progress on an analysisrequest? Would this map to the item.ResultsInterpretation property in the above snippet? Thanks.

Regards
Nathan.

4

HI @ruhanga ,

How to make queries in JSON call is covered in the same documentation: https://senaitejsonapi.readthedocs.io/en/latest/api.html?highlight="review_state"#search-resource

You have some examples there. The following one returns samples in published status assigned to client with ID "HHILLS".

http://localhost:8080/senaite/@@API/senaite/v1/search?getClientID=HHILLS&review_state=published&sort_on=getDateSampled&sort_order=desc&catalog=bika_catalog_analysisrequest_listing

You can find all catalogs and their indexes to search by in the “catalog” folder for any addon: https://github.com/senaite/senaite.core/tree/1.3.x/bika/lims/catalog

Regards,

2 Likes
5

Thanks for the above pointers @Espurna. One simple inquiry following the example below extracted from the api documentation, how is a sample associated with the type of lab test requested, say for example requesting for an HIV test on a sample for a patient/client?

{
    "Contact": <client_contact_uid>,
    "SampleType": <sample_type_uid>,
    "DateSampled": "2020-03-05 14:21:20",
    "Template": <ar_template_uid>,
}

Kind regards,
Nathan.

6

Many analyses can be assigned to a sample, it is a (1-n)analysis <-> (1) sample relation. You may find this page useful: https://www.senaite.com/docs/sample-analyses

In code, samples are referred as “analysis requests” for inheritance from Bika. In the following link you have the line of code where analyses (analysis services) are assigned to the sample: https://github.com/senaite/senaite.core/blob/5b8e8ec4f835a58227a2f992a864538cffedb2eb/bika/lims/utils/analysisrequest.py#L87

1 Like
7

Thanks very much @Espurna! This is very helpful.

8

I’ve been looking into the Catalog Resource and it seems like different Catalogs can be configured but I could not figure out how. Could anyone shade more light on this?

On a freshly installed SENAITE docker project, I could only interact with the default portal_catalog. How and where could the other catalogs like bika_catalog_analysisrequest_listing be defined so I could query client info using senaite.jsonapi? Thanks.

9

Hi @ruhanga

Some Plone documentation about catalogs: https://docs.plone.org/develop/plone/searching_and_indexing/catalog.html

Also, I pointed to the place where catalogs are defined in SENAITE:

Please, carefully read my example to see that the same call defines the catalog to query by. Note the &catalog=bika_catalog_analysisrequest_listing

Kind regards,

10

Thanks @Espurna.

I asked because following the example you shared above, also enlisted in the api docs you shared, and using the actual getClientID parameter representing the client that I created, I got the below result.

{
   "_runtime":0.0025060176849365234,
   "message":"'bika_catalog_analysisrequest_listing'",
   "success":false
}

where as with the default portal_catalog I get

{
   "count":0,
   "pagesize":25,
   "items":[
      
   ],
   "page":1,
   "_runtime":0.0032520294189453125,
   "next":null,
   "pages":1,
   "previous":null
}

I could be missing something. Thanks for the guidance already @Espurna.

11

@ruhanga Just sending a request like http://localhost:9090/senaite/@@API/senaite/v1/search?&catalog=bika_catalog_analysisrequest_listing should be enough to get samples (analysis requests in code) from SENAITE…

Be sure that you are writing the call properly

1 Like
12

Thank @Espurna. I am deploying SENAITE using the latest docker project (1.3.3) and can see the senaite.jsonapi artifact missing, not sure if this could cause a problem.

13

Hi @Espurna! I’m not sure why I cannot make a successful request on http://localhost:8080/senaite/@@API/senaite/v1/search?&catalog=bika_catalog_analysisrequest_listing url with my local instance. I can see senaite.jsonapi successfully initialised in the logs though. Is there a public and stable demo instance of SENAITE lims that new users could probably interface with should locally installed instances fail for some reason? This would be helpful for demonstrations and testing purposes. This way it would be easier sharing challenges experienced when using the app locally against the correctly running demo app.

14

You can privately contact the providers with this request.

Kind regards,

15

Hi team,

I’m able to create a sample using the senaite.jsonapi using the snippet below as guided in the docs,

{
    "Contact": <client_contact_uid>,
    "SampleType": <sample_type_uid>,
    "DateSampled": "2020-03-05 14:21:20",
    "Template": <ar_template_uid>,
}

The sample creates successfully with the correct reference to the template without errors however it(sample) is not pre-filled with the templated content(analysis services requested, analysis profiles and/or sample type specified) as would be expected and is done on the UI. I’m using SENITE 1.3.4 and senaite.jsonapi 1.2.3.

Also I would think it is not quite necessary to require a SampleType if it was already defined by the reference Template in the posted payload.

Thanks already for any guidance forward in getting this resolved.
cc: @Espurna, @xispa

Kind regards
Nathan

1 Like
16

Also I would think it is not quite necessary to require a SampleType if it was already defined by the reference Template in the posted payload.

Good suggestion. Would you mind to open a ticket on senaite.jsonapi repos: Issues · senaite/senaite.jsonapi · GitHub

17

Thanks @xispa. Sorry for the delayed response. I’ve been on vacation. I have created the ticket here.

18

Hi Ruhanga

Is it possible to update “Result” field, using JSON APIs?

Regards
Sammer

19

Hi @Sameer, where you unblocked?