API

Querying

• param values that needs to be prefixed with #
  • number
  • boolean (true|false)
  • empty array ([])

Pagination

Parameters

Query Structure: https://yourdomain.com/<service-name>?<field-1>=<value-1>&<...>&<field-n>=<value-n>

Example Query: https://yourdomain.com/action-codes?type=credit&$limit=#20&$skip=#5&$total=#true&$select[0]=id&$select[1]=amount&$select[2]=type&$sort[id]=#1

Sample output:

{
  "skip": 5,
  "limit": 20,
  "total": 2,
  "data": [
    {
      "id": "some-id-1",
      "type": "credit",
      "amount": 100
    },
    {
      "id": "some-id-2",
      "type": "credit",
      "amount": 1000
    }
  ]
}

This applies to all services with Find method.

Find methods will always return an object consisting of items, limit and total.

In order to see the remaining items, put a value to $skip to skip the former items.

Special operators

$history (#find)

• list history

usage

const entries = await sdk.billing.invoices().find({ $history: true, id: 'some-invoice-id' });

$history (#patch)

• restore from history

usage

const invoice = { id: 'some-invoice-id' };
const entries = await sdk.billing.invoices().find({ $history: true, id: invoice.id });
const historyEntryToRestore = entries[0];
await sdk.billing.invices().update(invoice.id, { $history: true, _record: historyEntryToRestore._record });

$populate (#find, #get)

config fields

• localKey: string - the field where the itermediate variable 'ids: string | object | string[] | object[]' will be extracted
• extractKey: string - extract this key from the ids. use for objects or array of objects`
• skipEmpty: boolean - return [] or null for empty ids field
• service: string - the service to use
• method: string - the querying method to use. possible values: find, findOne, get
• foreignKey: string - the query key where ids will be put. use by methods: find and findOne
• foreignOps: string - the mongodb operator to use with querying
• ...restQuery: extra keys in the config

internal process

• let ids = parentItem[localKey]
• if (extractKey && isPlainObject(ids)) ids = ids[extractKey]
• if (extractKey && isArrayOfPlainObject(ids)) ids = ids.map(o => o[extractKey])
• if (skipEmpty && (!ids || (isArray(ids) && !ids.length))) return method === 'get' ? null : []
• if (method === 'get') return service.get(ids)
• if (method === 'find') return service.find({ [foreignKey]: foreignOps ? { [foreignOps]: ids } : ids, ...restQuery })
• if (method === 'findOne') return service.findOne({ [foreignKey]: foreignOps ? { [foreignOps]: ids } : ids, ...restQuery })

usage

// populate the patient and invoice field on the server
const encounters = await sdk.mf.encounters().find({
   facility: 'facility-id',
   $active: true,
   $populate: {
      // will populate (on the result) field '$populated._patient' 
      // by querying service `patients` using the key `patient` on the result
      _patient: { service: 'medical-patients', key: 'patient' },
      _invoice: { service: 'billing-invoices', key: 'id' }
  }
})

$prequery and $prequeryOr (#find)

config fields

• service: string - the service to use
• query: object | string - the query to use. result will be put to an itermediate variable 'items: object | object[]'
• extractKey: string - extract this key from the variable items
• localKey: string - the query key where items will be put
• localOps: string - the mongodb operator to use with querying

internal process

• let items = isPlainObject(query) ? service.find(query) : service.get(query)
• if (isPlainObject(items)) items = items[extractKey]
• if (isArrayOfPlainObject(items)) items = items.map(i => i[extractKey])
• if ($prequery) return parentQuery.$and.push({ [localKey]: localOps ? { [localOps]: items } : items })
• if ($prequeryOr) return parentQuery.$or.push({ [localKey]: localOps ? { [localOps]: items } : items })

usage

• runs pre query queries and modifies the main query

// find invoices in the facility w/c have items
// that are covered by the specified hmo
// in a date range
const invoices = await sdk.billing.invoices().find({
   // limit to facility
   facility: 'facility-id',
   // query only the finalized invoices
   finalizedAt: { $exists: true },
   // where the dates can be any date format
   createdAt: { $gte: currentDate, $lte: addDays(currentDate, 1) },
   // NOTE: important for dates as mongodb only understands JSDates so you have to let the server know w/c dates to convert
   $dateFields: ['createdAt.$gte', 'createdAt.$lte'],
   // modifies the final query
   $prequery: [
     {
       // find billing items w/c are covered
       // by a specific hmo
       service: 'billing-items',
       query: { 
         facility: 'facility-id', 
         coverages: { 
           contract: 'hmo-contract-id',
           // or insurer: 'hmo-org-id'
         }
       },
       // extract the invoice of the resulting items (for limiting query to only these invoices)
       extractKey: 'invoice',
       // modify the final query
       // by adding an $and clause with these values
       resKey: 'id',
       resOps: '$in'
     }
   ]
});


// find invoices in the facility where the attached
// encounter has the specified doctor
const invoices = await sdk.billing.invoices().find({
   facility: 'facility-id',
   // modifies the final query
   $prequery: [
     {
       // find an encounter with the specified doctor
       service: 'medical-encounters',
       query: { facility: 'facility-id', doctors: 'some-doctor-uid' },
       // extract the id of the resulting encounters
       extractKey: 'id',
       // modify the final query
       // by adding an $and clause with these values
       resKey: 'id',
       resOps: '$in'
     }
   ]
});

// final query form, assuming and encounter was found
{
  facility: 'facility-id',
  $and: [
    // where 'id' field was from the 'resKey' and '$in' from resOps
    // ['encounter-with-doc-id'] was the result of extracting 'resKey' from the result of the prequery
    { id: { $in: ['encounter-with-doc-id'] } }
  ]
}