34.0.1JSON Admin API
Smile CDR includes an administration API based on (non-FHIR) RESTful JSON Web Services. This API uses simple JSON-based REST calls to check status information and configure the CDR.
In a default installation of Smile CDR, this will be found on port 9000 so it will be accessible by a URL similar to http://localhost:9000/.
This API makes use of Swagger, which is a RESTful web services description framework as well as a convenient testing tool for using these services. A screenshot of this tool is shown below.
34.0.2Security
By default, these services are secured using HTTP Basic Authentication, which means every request should include an Authorization header.
When using Swagger-UI, you will be prompted by your browser for credentials when accessing any services where the default security is preserved.
34.0.2.1HTTP Basic Authentication
If HTTP Basic Authentication is enabled, a typical GET request to the JSON Admin API will resemble the following:
GET http://localhost:9000/runtime-status/node-statuses/complete
Authorization: Basic YWRtaW46cGFzc3dvcmQ=
Accept: application/json
These services may also be configured to use a different security module, such as an OpenID Connect module.
34.0.3Format
Note that all dates and times in this API follow the same ISO-8601 format used by FHIR (e.g. 2017-01-01T00:00:00.0000-05:00).
34.0.4Allowing Anonymous Access
It is sometimes beneficial to allow specific types of requests to be performed without authentication. This is most commonly the case for monitoring tools. Note that this is recommended only in cases where the JSON Admin API is not accessible to the outside world (e.g. it is exposed only to a port on an internal management network). If you would like to enable anonymous access, use the following steps:
-
Enable Allow Anonymous Access on the JSON Admin API module. Enabling this setting means that requests to the JSON Admin API will receive the permissions associated with your anonymous user. By default the anonymous user has no meaningful permissions so this setting has no effect on its own.
-
Grant your anonymous user the
ACCESS_ADMIN_JSONpermission. This allows anonymous requests to access the endpoint, but does not grant any ability to invoke specific operations. -
Grant your anonymous user appropriate permissions for the functions you want to enable anonymous access for. For example, if you want to enable anonymous metric access, grant the
VIEW_METRICSpermission. Be careful about which permissions you grant here, since anonymous access can be a significant security concern.
34.0.5MDM Endpoints Exposed in JSON Admin Module
A number of mdm-related endpoints are exposed through the admin module for convenience.
See fhir documentation for the fhir endpoint versions of these MDM endpoints.
34.0.5.0.1MDM Create Link
Creates a new MDM link between an existing golden resource and an existing source resource with the provided match result.
Eg:
POST http://localhost:{admin_json_port}/mdm/{mdm_module_id}/create-link
Request body:
{
"goldenResourceId": "Patient/10",
"resourceId": "Patient/1",
"matchResult": "MATCH"
}
Output:
{
"links": [{
"goldenResourceId": "Patient/10",
"sourceId": "Patient/1",
"matchResult": "MATCH"
}]
}
See the related documentation for the FHIR endpoint here.
34.0.5.0.2MDM Update Link
Updates an existing MDM link, changing the link relationship between a provided golden resource id and source resource id.
Eg:
POST http://localhost:{admin_json_port}/mdm/{mdm_module_id}/update-link
Request Body:
{
"goldenResourceId": "Patient/10",
"resourceId": "Patient/1",
"matchResult": "MATCH"
}
Output:
{
"links": [{
"goldenResourceId": "Patient/10",
"sourceId": "Patient/1",
"matchResult": "MATCH"
}]
}
See the related documentation for the FHIR endpoint here.
34.0.5.0.3MDM Not Duplicate
Marks the provided golden resources as not duplicates.
Output is always true, or an exception is thrown.
Eg:
POST http://localhost:{admin_json_port}/mdm/{mdm_module_id}/not-duplicate
Request body:
{
"goldenResourceId": "Patient/10",
"resourceId": "Patient/1"
}
Output:
true
See the related documentation for the FHIR endpoint here.
34.0.5.0.4MDM Merge Golden Resources
Merges one golden resource into another. After the merge is complete, the "from" golden resource will be deactivated.
Eg:
POST http://localhost:{admin_json_port}/mdm/{mdm_module_id}/merge-golden-resources
Request body:
{
"fromGoldenResourceId": "Patient/10",
"toGoldenResourceId": "Patient/20"
}
Output:
{
"resourceType": "Patient",
"id": "20",
"meta": {
"versionId": "2",
"lastUpdated": "2000-01-31T00:00:00.000-00:00",
"tag": [
{
"system": "http://hapifhir.io/fhir/NamingSystem/mdm-record-status",
"version": "1",
"code": "GOLDEN_RECORD",
"display": "Golden Record",
"userSelected": false
},
{
"system": "https://hapifhir.org/NamingSystem/managing-mdm-system",
"version": "1",
"code": "HAPI-MDM",
"display": "This Golden Resource can only be modified by HAPI MDM system.",
"userSelected": false
}
]
},
"identifier": [
{
"system": "http://hapifhir.io/fhir/NamingSystem/mdm-golden-resource-enterprise-id",
"value": "4f8d1113-6a76-4671-88cd-10f7dc3bd2e6"
},
{
"system": "http://hapifhir.io/fhir/NamingSystem/mdm-golden-resource-enterprise-id",
"value": "799fec0d-7904-4698-bc7d-3cf6dd757c30"
}
]
}
See the related documentation for the FHIR endpoint here.
34.0.5.0.5MDM Query Links
Returns a pageable list of MDM links that fit the optionally provided query parameters.
The available query parameters include:
- goldenResourceId - a single string value of the golden resource id. Eg:
goldenResourceId=Patient%2F10 - resourceId - a single string value of the source resource id. Eg:
resourceId=Patient%2F1 - matchResult - a string value of the match type of interest (
MATCH,NO_MATCH,POSSIBLE_MATCH). Eg:matchResult=MATCH - linkSource - a single string of the link type (
AUTO,MANUAL). Eg:linkSource=AUTO - _offset - offset for paging. Eg:
_offset=1 - _count - the number of links to return. Eg:
_count=10 - _sort - one or more comma separated string values indicating the fields of the
MDM Link on which to sort (prefaced with a
-for decending order). Eg:sort=-myUpdated - resourceType - the resource types of interest. Eg:
resourceType=Patient - partitionIds - a list of partition ids to search. Eg:
partitionIds=1,2,3
Eg:
GET http://localhost:{admin_json_port}/mdm/{mdm_module_id}/query-links?matchResult=NO_MATCH
Output:
{
"links": [
{
"goldenResourceId": "Patient/10",
"sourceId": "Patient/1",
"matchResult": "MATCH",
"linkSource": "AUTO",
"created": 1691003284116,
"updated": 1691003284116,
"version": "1",
"eidMatch": false,
"vector": 0,
"score": 1.0,
"ruleCount": 0,
"linkCreatedNewGoldenResource": true
}
]
}
See the related documentation for the FHIR endpoint here.
34.0.5.0.6MDM Link History
Shows a history for a given set of MDM links, querying by golden resource IDs, source IDs, or both.
The following query parameters are available. One or both must be provided:
- goldenResourceId - the golden resource id of interest. Eg:
goldenResourceId=Patient/10 - resourceId - the source resource id of interest. Eg:
resourceId=Patient/1
Eg:
GET http://localhost:{admin_json_port}/mdm/{mdm_module_id}/link-history?goldenResourceId=Patient/10
Output:
{
"links": [
{
"mdmLink": {
"goldenResourceId": "Patient/10",
"sourceId": "Patient/1",
"matchResult": "MATCH",
"linkSource": "AUTO",
"created": 1691003284116,
"updated": 1691003284116,
"version": "1",
"eidMatch": false,
"vector": 0,
"score": 1.0,
"ruleCount": 0,
"linkCreatedNewGoldenResource": true
},
"revisionNumber": 1,
"revisionTimestamp": 1691003284123
}
]
}
See the related documentation for the FHIR endpoint here.
34.0.5.0.7MDM Duplicate Golden Resources
Returns a list of all the duplicate golden resources.
The following optional query params are available:
- _offset - the offset to begin returning records at. Eg:
_offset=1 - _count - the number of resources to be returned per page. Eg:
_count=10 - partitionIds - a list of partitions to query. Eg:
partitionIds=1,2,3 - resourceType - the resource type of interest. Eg:
resourceType=Patient
Eg:
GET http://localhost:{admin_json_port}/mdm/{mdm_module_id}/duplicate-golden-resources
Output:
{
"links": [
{
"goldenResourceId": "Patient/10",
"sourceId": "Patient/1",
"matchResult": "POSSIBLE_DUPLICATE",
"linkSource": "AUTO",
"created": 1691003284116,
"updated": 1691003284116,
"version": "1",
"eidMatch": false,
"vector": 0,
"score": 1.0,
"ruleCount": 0,
"linkCreatedNewGoldenResource": true
}
]
}
See the related documentation for the FHIR endpoint here.
34.0.5.0.8MDM Submit
Submits a batch job to perform MDM matching on all existing resources in the system.
An optional criteria can be provided to filter resources on which to match.
The output value will be the number of resources submitted for MDM processing.
Eg:
POST http://localhost:{admin_json_port}/mdm/{mdm_module_id}/mdm-submit
Request body:
{
"resourceType": "Patient",
"criteria": "birthdate=2020-07-28"
}
Output:
27
See the related documentation for the FHIR endpoint here.
34.0.5.0.9MDM Clear
Submits a batch job to bulk delete all MDM links and related golden resources from the system.
The returned output will include a batch jobId which can be used to find the status of the job in the admin console.
Eg:
POST http://localhost:{admin_json_port}/mdm/{mdm_module_id}/mdm-clear
Request body:
{
"resourceType": "Patient,Practitioner",
"batchSize": 500,
"tenantId": "{tenant-id}"
}
Output:
{
"resourceType": "Patient",
"parameter": [{
"name": "jobId",
"valueString": "some-guid-value"
}]
}
See the related documentation for the FHIR endpoint here.
34.0.5.0.10MDM Metrics
Returns metrics about the MDM module.
The available query parameters include:
- resourceType - (required) - The resource type of interest. Must be a valid FHIR resource type. Eg:
resourceType=Patient - matchResult - (optional) - A string value of the match type of interest (
MATCH,NO_MATCH,POSSIBLE_MATCH). Metrics (for score and link type counts) will be filtered to only look at the provided match results. If none are provided, all will be checked. Eg:matchResult=MATCH - linkSource - (optional) - A single string of the link type (
AUTO,MANUAL). Metrics for link type counts will be filtered to only look at the provided link sources. If none are provided, all will be checked. Eg:linkSource=AUTO
Eg1:
GET http://localhost:{admin_json_port}/mdm/{mdm_module_id}/mdm-metrics?resourceType=Patient
Output:
{
"resourceType": "Patient",
"matchResult2linkSource2count": {
"NO_MATCH": {
"MANUAL": 1
},
"MATCH": {
"AUTO": 5
}
},
"scoreCounts": {
"NULL": 0,
"x_<_0.01": 0,
"0.01_<_x_<=_0.02": 0,
"0.02_<_x_<=_0.03": 0,
"0.03_<_x_<=_0.04": 0,
"...": "...",
"0.97_<_x_<=_0.98": 0,
"0.98_<_x_<=_0.99": 0,
"0.99_<_x_<=_1.00": 6
},
"goldenResources": 4,
"sourceResources": 5,
"excludedResources": 0
}
Eg2:
GET http://localhost:{admin_json_port}/mdm/{mdm_module_id}/mdm-metrics?resourceType=Patient&matchResult=MATCH&linkSource=AUTO
Output:
{
"resourceType": "Patient",
"matchResult2linkSource2count": {
"MATCH": {
"AUTO": 5
}
},
"scoreCounts": {
"NULL": 0,
"x_<_0.01": 0,
"0.01_<_x_<=_0.02": 0,
"0.02_<_x_<=_0.03": 0,
"0.03_<_x_<=_0.04": 0,
"...": "...",
"0.97_<_x_<=_0.98": 0,
"0.98_<_x_<=_0.99": 0,
"0.99_<_x_<=_1.00": 5
},
"goldenResources": 4,
"sourceResources": 5,
"excludedResources": 0
}
This operation is currently only supported on the JSON Admin API.
Note: This operation is currently in experimental stage and may be subject to change with minimal notice.