Quick start

Below you can find guidance how to render a form with Form Renderer.

Configure

The following code illustrates a basic component configuration.

// Component import and 'extends Component' keywords are crucial
import {Component} from 'react';

class App extends Component {
  // form data
  formMetadata = {
    name: 'my-form',
    version: '1.0.0'
  };
  ehrServerUrl = 'https://better-ehr-server.com/rest/v1';
  credentials = {
    username: 'user',
    password: 'pswd'
  };
  context = {
    language: 'en',
    readonly: false
  };
  compositionId = '28e813d9-5caf-4302-8274-3966a5b1f819::user::1';

  // define and access component properties inside componentDidMount() method
  componentDidMount() {
    this.component.formMetadata = this.formMetadata;
    this.component.ehrServerUrl = this.ehrServerUrl;
    this.component.credentials = this.credentials;
    this.component.context = this.context;
    this.component.compositionId = this.compositionId;
  }
  
  // component reference handler
  handleRef = component => {
    this.component = component;
  };

  // ref={this.handleRef} is crucial
  render() {
    return (
      <div className="App">
        <form-renderer ref={this.handleRef}></form-renderer>
     </div>
    );
  }
}

export default App;

NOTE version in formMetadata is an optional parameter, if omitted the latest version of that form is used

Compositions and CompositionIds

Passing composition or compositionId to the form will fill the form with data from the composition.

When you pass a composition to the form renderer, the form renderer will fill the form with the composition provided.
When you pass a compositionId to the form renderer, the form renderer will fetch the composition from the server and fill the form with it.
When you pass both compositionId and composition, the form renderer will ignore the provided composition and fetch the composition from the server using the compositionId.
When you do not pass either compositionId or composition, the form renderer will render an empty form.
When you pass a null value as compositionId, the form renderer will render an empty form.

Configurable EHR form context parameters

We understand that each application has its own use cases and requirements, and we understand we can't cover all those needs without an extensive set of configuration options which you can configure for your needs. Below are instructions how to pass configuration (EhrFormContext object) to Form Renderer. For more details about options head to EhrFormContext.

  componentDidMount() {
    this.component.ehrServerUrl = this.ehrServerUrl;
    this.component.credentials = this.credentials;
    this.component.formMetadata = this.formMetadata;
    this.component.context = this.context;
    this.component.compositionId = this.compositionId;
  }

class App extends Component {
  // ...
  context = {
    language: 'en',
    readonly: false,
    territory: 'SI',
    presentationMode: true,
    showAllPages: false,
    dateFormat: 'dd/MM/yyyy',
    autoPrefill: {
      enabled: true,
      mode: 'LATEST_COMPOSITION'
    }
  };
}

Credentials

There are two ways of providing credentials to the renderer directly:

Basic Auth
OAuth 2.0

Basic Auth

With basic auth you only provide a resource url and a username and password for the url. authType can be set to basic or it can be left out entirely.

credentials = {
  username: 'my_user',
  password: 'my_password'
};

OAuth 2.0

Form renderer also supports OAuth2.0, where you can provide the form renderer with an access token.

Instead of username and password you provide a credentials object with authType and token. authType value for OAuth2.0 is oauth2 while you should get the token from your auth server.

credentials = {
  authType: 'oauth2',
  token: 'eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIdasiwia2lkIiA6ICJiA'
};

This example, however, is only the first step in configuring the renderer, because the token will eventually expire. If you do not provide a new token until, then the renderer has a built-in fallback and will trigger an onRequestUpdatedToken output event you can use to pass a function that updates the token.

class App extends MyComponent {
  //methods 
  provideNewToken = () => {
    // implement refresh token
  }

  componentDidMount() {
    // ... access functions through event listeners
    this.component.addEventListener('onRequestUpdatedToken', this.provideNewToken());
  }
  
  handleRef = component => {
    this.component = component;
  };

  // ref={this.handleRef} is crucial
  render() {
    return (
      <div className="App">
        <form-renderer ref={this.handleRef}></form-renderer>
      </div>
    );
  }
}

To update the token you can use the updateToken(token) method call. The token can be updated at any time, however the renderer does expect an updated token within 5000ms after emitting the onRequestUpdatedToken event. If a new token is not provided or an invalid token is passed the renderer will throw an error.

class App extends MyComponent {
  credentials = {
    authType: 'oauth2',
    token: 'eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIdasiwia2lkIiA6ICJiA'
  };

  provideNewToken = async() => {
    // fetch refresh token
    const refreshedToken = await ... // <--- retrieved new access token
    this.component.updateToken(refreshedToken);
  };
  
  componentDidMount() {
    // ... access functions through event listeners
    this.component.addEventListener('onRequestUpdatedToken', this.provideNewToken());
  };
  
  handleRef = component => {
    this.component = component;
  };
  
  // ref={this.handleRef} is crucial
  render() {
    return (
      <div className="App">
        <form-renderer ref={this.handleRef}></form-renderer>
      </div>
    );
  }
}

Alternatively you can provide form-renderer with a new credentials object, which will also trigger the updateToken input:

class App extends MyComponent {
  credentials = {
    authType: 'oauth2',
    token: 'eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIdasiwia2lkIiA6ICJiA'
  }

  provideNewToken = async() => {
    // fetch refresh token
    const refreshedToken = await ... // retrieved new access token
    this.component.credentials = {authType: 'oauth2', token: refreshedToken};
  };
  
  componentDidMount() {
    // ... access functions through event listeners
    this.component.addEventListener('onRequestUpdatedToken', this.provideNewToken());
  }
  
  handleRef = component => {
    this.component = component;
  };
  
  // ref={this.handleRef} is crucial
  render() {
    return (
      <div className="App">
        <form-renderer ref={this.handleRef}></form-renderer>
      </div>
    );
  }
}

If a new token is not received in 5000ms the form renderer will throw an error.

Configure​

Compositions and CompositionIds​

Configurable EHR form context parameters​

Credentials​

Basic Auth​

OAuth 2.0​