Skip to main content

ibipimo Adaptor developer README.md

Source: https://github.com/OpenFn/adaptors/tree/main/packages/ibipimo

language-ibipimo

An OpenFn adaptor for building integration jobs for use with the IBIPIMO laboratory system API.

Documentation​

View the docs site for full technical documentation.

Overview​

The IBIPIMO adaptor allows you to interact with the IBIPIMO laboratory system to:

  • Post viral load test requests
  • Retrieve viral load test results
  • And do other get and post request to IBIPIMO

Authentication​

This adaptor uses Bearer token authentication. You need to provide:

  • baseUrl: The base URL of the IBIPIMO API server (e.g., https://demo.ibipimo.org)
  • apiToken: Your IBIPIMO API access token

Configuration​

All required and optional properties for state.configuration are defined in the official configuration-schema.

Example configuration:

{
  "baseUrl": "https://demo.ibipimo.org",
  "apiToken": "your_access_token_here"
}

Usage Examples​

Post Viral Load Request​

Post a new viral load test request to the IBIPIMO system:

postViralLoadRequest({
  siteid: '77889900',
  samples: [
    {
      sidainfo_uid: '147460',
      p_code: '000003',
      p_name: 'Magara',
      p_prename: 'Mahire',
      p_sex: 'M',
      p_dob: '1950-01-15',
      p_telephone: '79932635',
      female_status: 'na',
      colline: null,
      arv_start_date: '2006-09-21',
      p_stade_clinique: '4',
      p_ligne_therap: '1',
      reason_vl: 'suspicion_echec',
      on_arv: '1',
      sample_type: null,
      date_blood_taken: '2024-04-15 11:49:00',
      place_blood_taken: 'CDS Training',
      blood_taken_by: null,
      prescription_by: null,
      contact_sender: null,
      blood_received_by: '',
      province_id: '017BD',
      commune_id: '003BDI017001',
      arv_combination_id: 'TDF(300)/3TC(300)/DTG(50)',
      date_last_vl: null,
      last_vl_copies: '-1',
      site: '77889900',
      dateprelevement: '2024-04-15',
      sidainfo_siteid: '77889900',
      hf_district: null,
      hf_province: null,
    },
  ],
});

Success Response (201):

{
  "data": {
    "errors": [],
    "saved_viral_load_samples": [
      {
        "id": 830139,
        "s_uid": "634W",
        "siteid": "22222222",
        "codepatient": "000010",
        "date_prelevement": "15/04/2024 11:49:00",
        "updated_at": "2026-02-18 12:52:51"
      }
    ]
  },
  "references": [{}],
  "response": {
    "url": "https://demo.ibipimo.org/api/v1/post-viral-load-requests",
    "method": "POST",
    "statusCode": 201,
    "statusMessage": "Created",
    "headers": {
      "date": "Fri, 20 Feb 2026 15:12:40 GMT",
      "server": "Apache",
      "cache-control": "no-cache, private",
      "access-control-allow-origin": "*",
      "vary": "Authorization,User-Agent",
      "upgrade": "h2",
      "connection": "Upgrade, Keep-Alive",
      "keep-alive": "timeout=5, max=100",
      "transfer-encoding": "chunked",
      "content-type": "application/json"
    },
    "duration": 5555
  }
}

Get Viral Load Results​

Retrieve viral load test results by sample UIDs:

getViralLoadResults({
  siteid: '77889900',
  sample_uids: ['2026010401', 'IBI-2024-000001'],
});

Success Response (200):

{
  "data": {
    "siteid": "22222222",
    "results": [],
    "sample_statuses": {
      "634W": {
        "sample_uid": "634W",
        "request_found": true,
        "request_status": "not_processed",
        "request_mode": "api_sidainfo",
        "sidainfo_uid": "147460",
        "codelabo": null,
        "date_blood_taken": "15/04/2024 11:49:00",
        "date_blood_received": null,
        "created_at": "2026-02-18T12:52:51.000000Z",
        "updated_at": "2026-02-18T12:52:51.000000Z",
        "result_status": "not_available",
        "result_available": false,
        "no_result_reason_code": "sample_not_processed",
        "no_result_reason_message": "Sample request exists but has not been processed by the laboratory yet.",
        "latest_result_meta": null,
        "result": null
      }
    },
    "no_published_results": ["634W"],
    "no_results": ["634W"],
    "no_results_summary": {
      "sample_not_processed": {
        "count": 1,
        "sample_uids": ["634W"]
      }
    },
    "not_found_sample_uids": [],
    "total_requested": 1,
    "total_found": 0,
    "total_without_published_result": 1
  },
  "references": [{}],
  "response": {
    "url": "https://demo.ibipimo.org/api/v1/ask-for-vl-results",
    "method": "POST",
    "statusCode": 200,
    "statusMessage": "OK",
    "headers": {
      "date": "Fri, 20 Feb 2026 15:14:19 GMT",
      "server": "Apache",
      "cache-control": "no-cache, private",
      "access-control-allow-origin": "*",
      "vary": "Authorization,Accept-Encoding,User-Agent",
      "upgrade": "h2",
      "connection": "Upgrade, Keep-Alive",
      "keep-alive": "timeout=5, max=100",
      "transfer-encoding": "chunked",
      "content-type": "application/json"
    },
    "duration": 2760
  }
}

Generic Post Request​

Post data to any endpoint:

post('/api/v1/your-endpoint', {
  siteid: '77889900',
  sample_uids: ['2026010401', 'IBI-2024-000001'],
});

Generic Post Request​

Get data from any endpoint:

get('/api/v1/your-endpoint');

Avanced processing​

Handling post request response

postViralLoadRequest(...);

processViralLoadSubmission((state, processSubmission) => {
  const submission = processSubmission(state.data);

  console.log('\n=== SUBMISSION RESULTS ===');
  console.log(`Saved samples: ${submission.savedCount}`);
  console.log(`Errors: ${submission.errorCount}`);

  if (submission.hasErrors) {
    console.log('\n--- Errors ---');
    submission.errors.forEach(error => {
      console.log(`- ${error}`);
    });
  }

  return {
    ...state,
    submissionResult: submission,
  };
});

Handling IBIPIMO returned results:

getViralLoadResults(...);

processViralLoadResults((state, processResults) => {
  const processed = processResults(state.data);

  console.log('=== VIRAL LOAD RESULTS ===');
  console.log(`Requested result: ${processed.totalRequested}`);
  console.log(`Total found: ${processed.totalFound}`);
  console.log(`Total pending: ${processed.totalPending}`);
  console.log(`Available results: ${processed.availableResults.length}`);
  console.log(`Pending samples: ${processed.pendingSamples.length}`);

  return {
    ...state,
    processedResults: processed,
  };
});

Error Handling​

The adaptor handles various error responses:

  • 400 Bad Request: Validation failed or invalid format
  • 401 Unauthorized: Invalid or missing access token
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: No results found for provided UIDs
  • 409 Conflict: Duplicate integration attempt
  • 5xx Server Errors: Server processing failed

Development​

Clone the adaptors monorepo. Follow the "Getting Started" guide inside to get set up.

Go to the Adaptor project cd /packages/ibipimo

Run tests using pnpm run test or pnpm run test:watch

Build the project using pnpm build.

To build only the docs run pnpm build docs.

Installation and testing​

1. Install dependencies​

npm install

2. Local testing​

tmp files​

Create /tmp/state.json and /tmp/output.json files

{
  "configuration": {
    "baseUrl": "https://demo.ibipimo.org",
    "apiToken": "your_api_token_here"
  },
  "data": {}
}

Test with OpenFn CLI (if installed)​

# Install OpenFn CLI
npm install -g @openfn/cli

# Test individual jobs
openfn jobs/test-post-request.js -o tmp/output.json -s tmp/state.json
openfn jobs/test-get-results.js -o tmp/output.json -s tmp/state.json
openfn jobs/test-generic-post-request.js -o tmp/output.json -s tmp/state.json
openfn jobs/test-generic-get-request.js -o tmp/output.json -s tmp/state.json
openfn jobs/test-advanced-processing.js -o tmp/output.json -s tmp/state.json