Getting authenticated openEHR Ehrscape - Marand Think/EHR and Ethercis

gistfile1.txt

# 2. Getting connected to the CDR

In this section we will just ensure that we can connect to an openEHR CDR, retreive a session token, and run a simple call to retreive a list of the loaded templates, to check that we are all setup correctly.

## A. General setup

We now need access to an openEHR CDR, currently Marand Think!Ehr or Ripple Ethercis are supported, and the following information...

1. baseUrl of the CDR
2. Username and Password of the CDR (Ethercis) or CDR Domain (Operino /Project on Code4Health Platform)

If you have signed up for a Code4Health Platform account and have created an Operino/Project, you should have received this information by email. 

Before you can interact with the CDR you need to authorise the connection. This is one of the few places that Marand ThinkEHR (Code4health Platform ) and Ripple Ethercis differslightly. Both have implemented `Bearer authentication` using JWT but this is a little more complex to manage for training purposes.

#### Marand Think!EHR / Code4health Platform 

The Think!EHR CDR which is currently used by the Code4Health Platform supports Basic Authentication for training purposes. 

The BasicAuth string is actually just an encoded form of the username and password.

`var BasicAuth = "Basic " + btoa(Username + ":" + Password);'`

This should be carried on the http `headers` of any calls to the CDR via the `Authorization` header..

`Authorization: Basic 2fhrkweofleffff23defergtty`

#### Ripple Ethercis

Ethercis works a little differently and uses 'session tokens'. First, we must make a single `POST /session` call (using our username and password) to retreive a session token, use that session token as an http header on any subsequent calls to the CDR, then formally `DELETE /session` to invalidate the session token as we close the interaction with the CDR. Note that session tokens have an expiry time and in a production system these need to be refreshed.

#### POST  /session example

```javascript
const cdrUrl = 'https://cdr.code4health.org/rest/v1';

const sessiontoken = getSessiontoken(cdrUrl,'myUsername', 'myPassword');

async getSessionToken(cdr,username,password) => {
    const response = await axios.post(`${cdrUrl}/session`, {
        params : {
            username, 	// ES6 enhanced object literal syntax 
            password	// ES6 enhanced object literal syntax	
        }
    });
    return response.data.sessionId; 
}
```

Ethercis expects a Session token to be carried on the http Headers as a custom `Ehr-Session` header ..

`Ehr-Session : {{sessionToken}}`

Code4Health/ThinkEhr also supports the Session token approach but this is likely to be deprecated in the future.

## B. Listing the openEHR Templates registered with the CDR

We do not actually need to list the openEHR Templates as part of  this project but it is a simple way of checking that our authorisation setup is correct and that we are able to hook up to the CDR

The API Call to list templates is simple - just `GET /template` ...

Code4Health/ ThinkEhr

```javascript
 async getCDRTemplates(cdrUrl, authHeader) {
        const response = await axios.get(`${cdrUrl}/template`,
            {
                headers : authHeader
            });
        return await response.data.templates;
    }    
```

This will return an array of template objects...

```json
{
    "templates": [
        {
            "templateId": "IDCR - Adverse Reaction List.v1",
            "createdOn": "2018-05-18T10:20:07.397Z"
        },
        {
            "templateId": "IDCR - Immunisation summary.v0",
            "createdOn": "2018-05-18T10:20:15.580Z"
        },
        {
            "templateId": "IDCR - Laboratory Order.v0",
            "createdOn": "2018-05-18T10:20:20.838Z"
        },
        {
            "templateId": "IDCR - Laboratory Test Report.v0",
            "createdOn": "2018-05-18T10:20:08.456Z"
        },
        {
            "templateId": "IDCR - Medication Statement List.v0",
            "createdOn": "2018-05-18T10:20:23.650Z"
        }
    ]
}
```