An adaptor for the Open Concept Lab API

Adaptors
1

@haftamuk , I thought we could discuss this out here for the benefit of the broader community!

I love the concept around map(params) — have you been running it locally on devtools? — but I think I need more context around how it’s used.

Maybe we can discuss this tomorrow and document the output here (or in the adaptor itself) but I’ll want to wrap my head around:

  1. The high-level use case here. Who is using language-ocl? Which other systems are they working with? What does the initial state look like when these jobs get run and what’s the desired output?
  2. Is there a live OCL server with an api that you’re testing against? Sometimes the way I go about writing an adaptor is to first get the envisioned flow all sketched out in curl or Postman. Can you show me how you’d like to take data that looks like {first_name: 'zara'} and pass it through an api at OCL so that it looks like {givenName: 'zara'} (or some other transformation) using only a series of curl requests and NodeJs scripting? With that as the basis, we can then build a more flexible and elegant function in the adaptor.

This seems to be the meat of it and I’m most excited to dig in here… are we handling the mutation of the object and decisions around recursion, etc., or is that something that’s done entirely by OCL’s api?

Best,
Taylor

1 Like
2

Yes. I was looking for ways how we could discuss the adaptor functions. This is perfect. It would be part of the documentation as well.

Who is using language-ocl?

  • Basucally any data exchange usecase with a need for terminology services. Two systems that maintain a record of the same THING independently need a way of semantic resolution of certain concepts using terminology service. As you explainind above its reolving first_name to givenName

I have a related questions too to bear in mind for our discussion later.
Considering the functions of the proposed adaptor, it seems a containment of helper functions. It is not a complete thing by itself. This is better explained with an example. So let’s say we have a use case for health data exchange on system A sending monthly agregate data to system B via an OpenFn Job. The job’s main function is to compute the raw data sent from system A build aggregation and send it to system B. In between the Job also needs to map the source(System A) data elements to destination data elements(System B). Therefore The job would use this adapters helper function to do the mapping.

  • Which other systems are they working with?
    I am not sure I have a sufficient answer for that! But …
    OCL is a terminology service managementt implementation and a reference tool in OpenHIE.
    OCL is been used in different use cases here in Ethiopia.

  • What does the initial state look like when these jobs get run and what’s the desired output?
    Input: A json object with source data element keys
    Process: converting json source data element keys to destination data element keys
    Output: A json object with destination data element keys

Maybe we can discuss the details in our discussion later.

  • Is there a live OCL server with an API that you’re testing against?
    I wouldn’t say I am in that stage yet. But there is a live server we can work with Here.

  • Can you show me how you’d like to take data that looks like {first_name: 'zara'} and pass it through an api at OCL so that it looks like {givenName: 'zara'}
    Hmmmm. Lets see the following example
    Lets say the Input contains data from System A and one data element is fp_new_at_10_to_14 (Think of this as first_name). Then, in order to know what is the coresponding data element at System B I would request the live OCL with the following RestAPI
    https://api.openconceptlab.org/users/haftamuk/sources/eCHIS-CODES/concepts/fp_new_at_10_to_14/mappings
    I would get the following as a result

[
{
“external_id”: null,
“retired”: false,
“map_type”: “Part-of”,
“source”: “eCHIS-CODES”,
“owner”: “haftamuk”,
“owner_type”: “User”,
“from_concept_code”: “fp_new_at_10_to_14”,
“from_concept_name”: “fp_new_at_10_to_14”,
“from_concept_url”: “/users/haftamuk/sources/eCHIS-CODES/concepts/fp_new_at_10_to_14/”,
“to_concept_code”: “XGzeutIIVz7”,
“to_concept_name”: “Contraceptive new acceptors by age”,
“to_concept_url”: “/users/haftamuk/sources/HMIS-CODES/concepts/XGzeutIIVz7/”,
“from_source_owner”: “haftamuk”,
“from_source_owner_type”: “User”,
“from_source_url”: “/users/haftamuk/sources/eCHIS-CODES/”,
“from_source_name”: “eCHIS-CODES”,
“to_source_owner”: “haftamuk”,
“to_source_owner_type”: “User”,
“to_source_url”: “/users/haftamuk/sources/HMIS-CODES/”,
“to_source_name”: “HMIS-CODES”,
“url”: “/users/haftamuk/sources/eCHIS-CODES/mappings/462311/”,
“version”: “462311”,
“id”: “462311”,
“versioned_object_id”: 462311,
“versioned_object_url”: “/users/haftamuk/sources/eCHIS-CODES/mappings/462311/”,
“is_latest_version”: false,
“update_comment”: null,
“version_url”: “/users/haftamuk/sources/eCHIS-CODES/mappings/462311/462312/”,
“uuid”: “462311”,
“version_created_on”: “2021-05-21T09:11:32.101055Z”,
“from_source_version”: null,
“to_source_version”: null,
“from_concept_name_resolved”: “fp_new_at_10_to_14”,
“to_concept_name_resolved”: “Contraceptive new acceptors by age”
},
{
“external_id”: null,
“retired”: false,
“map_type”: “SAME-AS”,
“source”: “eCHIS-CODES”,
“owner”: “haftamuk”,
“owner_type”: “User”,
“from_concept_code”: “fp_new_at_10_to_14”,
“from_concept_name”: “fp_new_at_10_to_14”,
“from_concept_url”: “/users/haftamuk/sources/eCHIS-CODES/concepts/fp_new_at_10_to_14/”,
“to_concept_code”: “N52ciGuI4qN”,
“to_concept_name”: “N52ciGuI4qN”,
“to_concept_url”: “/users/haftamuk/sources/HMIS-CODES/concepts/N52ciGuI4qN/”,
“from_source_owner”: “haftamuk”,
“from_source_owner_type”: “User”,
“from_source_url”: “/users/haftamuk/sources/eCHIS-CODES/”,
“from_source_name”: “eCHIS-CODES”,
“to_source_owner”: “haftamuk”,
“to_source_owner_type”: “User”,
“to_source_url”: “/users/haftamuk/sources/HMIS-CODES/”,
“to_source_name”: “HMIS-CODES”,
“url”: “/users/haftamuk/sources/eCHIS-CODES/mappings/462309/”,
“version”: “462309”,
“id”: “462309”,
“versioned_object_id”: 462309,
“versioned_object_url”: “/users/haftamuk/sources/eCHIS-CODES/mappings/462309/”,
“is_latest_version”: false,
“update_comment”: null,
“version_url”: “/users/haftamuk/sources/eCHIS-CODES/mappings/462309/462310/”,
“uuid”: “462309”,
“version_created_on”: “2021-05-21T09:08:39.999916Z”,
“from_source_version”: null,
“to_source_version”: null,
“from_concept_name_resolved”: “fp_new_at_10_to_14”,
“to_concept_name_resolved”: “10 - 14 years”
}
]

So I get the corresponding System B data element is XGzeutIIVz7 (weird but it means Contraceptive new acceptors by age).
Now I know how to post the content to System B.

I hope those things make sense.

1 Like