OpenHEXA

[laszcz]

Request

We want to build an adaptor to integrate with OpenHEXA, an open-source data integration platform for public health. OpenHEXA provides a GraphQL API for managing workspaces, pipelines, datasets, and connections to external data sources.

While OpenHEXA uses GraphQL, this adaptor will abstract the GraphQL complexity by providing REST-like helper functions that make HTTP POST requests to the GraphQL endpoint behind the scenes. Users will not need to write GraphQL queries directly, they will use simple JavaScript functions.

We want to build a basic adaptor to integrate with the REST API for openHEXA, which does authentication, retrieving workspaces, pipelines and trigger pipelines.

To start, this adaptor should:

1. Handle authentication
2. Provide convenience functions for common operation: trigger pipeline operations (for now) and potentially to query the output of a pipeline (get results / files generated) (will investigate the latter)
3. Include generic query() and mutate() helper functions for users who want to write GraphQL operations (not sure how much helper functions we want to set up for now)

Credentials

• Login credentials: TBC shortly once URL set up
• Authentication method(s): Bearer Token to be communicated

Sample Code

All requests to OpenHEXA's GraphQL endpoint should be:

• Method: POST
• URL: <baseUrl>/graphql
• Headers:

{
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
  }

• Body: JSON with query and optional variables fields:

Get Pipelines

{
  "query": "{ pipelines { items { id code name description } } }"
}

Trigger Pipeline without variables

{
    "query": "mutation { runPipeline(input: {id: \"c02d58d1-4a2b-4c20-8496-70cc395d20d6\", config: {}}) { success run { id status } errors } }"
  }

Trigger Pipeline with variables

{
    "query": "mutation runPipeline($input: RunPipelineInput!) { runPipeline(input: $input) { success run { id status } errors } }",
    "variables": {
      "input": {
        "id": "352191a1-7e99-4058-9201-8bce5ed4c473",
        "config":
          {
            "patient_data": {"patients":
             [
                {
                    "id": "P001", 
                    "name": "Alice Johnson", 
                    "age": 34, 
                    "condition": "Diabetes"
                    }, 
                {
                    "id": "P002",
                    "name": "Bob Williams",
                    "age": 56, 
                    "condition": "Hypertension"
                    },
                {
                    "id": "P003",
                     "name": "Carol Martinez",
                    "age": 41, 
                    "condition": "Diabetes"
                }
             ]
          },
            "facility_id":"OPENFN_FACILITY",
            "analysis_type": "summary"
          }
      }
    }
  }

FYI We can note that similarly to us, openHEXA accepts triggering pipelines using webhook endpoints

From the UI

Resources

graphql API structure

Python SDK

Logo Links

LOGO

[laszcz]

@aleksa-krolls cc @taylordowns2000 Here is what we could expect from an MVP adaptor. Just triggering a pipeline really for now (for our imeediate demo purpose), potentially listing pipeline ids.

The main value I see now to have this instead of using webhooks is 1) having a visible adaptor we can have a logo for and some docs 2) protect who can trigger runs (it seems their webhook functionality does not allow any auth for now)

As we develop the adaptor we can probably develop more helper functions that would ease our users to keep using our JS based syntax instead of the graphql complexity: for instance having methods likerunPipeline(id, config) vs mutate('mutation { ... }')

[aleksa-krolls]

@AishaHassen @martalovescoffee let's discuss if pius or mtuchi can fit this in next week. Basic adaptor is just a function that sends a POST request to a designated OpenHexa webhook URL.

@laszcz if you have OpenHEXA up and running, do you have a webhook you could expose sos we could try this out?

[martalovescoffee]

@AishaHassen Mtuchi mentioned that few specs are not ready for MSF. Should we give this to Mtuchi then?

[AishaHassen]

@martalovescoffee Justin just finished specing an issue for MSF, and i will have the iHRIS issue ready by end of day. His plate will be pretty full.

[aleksa-krolls]

@martalovescoffee @AishaHassen I just heard from client -> this is now lower priority, but ideally we can deliver ahead of January 15th. Let's plan to add to sprint early next year (if we have capacity).