PhenoTips » Administration Guide » Integration


Integration of PhenoTips is governed by the terms of the License. For information about integrating PhenoTips with closed-source software, such as electronic medical record systems, please contact Gene42 Inc.

PhenoTips is easy to integrate with other applications through its embeddable UI and RESTful APIs.

Web-based integration

The easiest way to integrate PhenoTips with another web-based system is through an embedded HTML iframe.

Stripping the PhenoTips skin

The default skin of PhenoTips is not well suited for embedding into another application, since it comes with its own header, footer, and extra padding. However, there already is a special skin useful for embedding. To activate it:

  • Open PhenoTips in a browser
  • Log in with an administrative account
  • Click on the Administration link displayed in the top left corner
  • Select the Look & Feel / Presentation entry from the left menu
  • Type PhenoTips.EmbeddableSkin in the Skin field, click Save

You should now see only the essential elements of the page. Unfortunately, this doesn't include links back to the homepage, or to the administration. Fortunately, you can configure the skin only for a specific user, too, though the UI for doing that is not easily discoverable:

  • Open http://localhost:8080/phenotips/bin/edit/XWiki/Admin?editor=object&classname=XWiki.XWikiUsers&object=0&property=skin - using the right protocol, host name, optional port, optional application name, and the right username
  • Type PhenoTips.Skin in the skin field, click one of the Save buttons

Displaying a patient record

Display http[s]://<hostname>[:<port>]/<appname>/bin/PhenoTips/OpenPatientRecord?[e]id=<identifier>[&mode=<mode>][&create=true] in an iframe.


the actual hostname where PhenoTips is reachable
the port, if needed
the name of the webapp (missing in the standalone zip)
the PhenoTips identifier of an existing patient record, for example P0000001
the external identifier that users can set for a patient; either one already set in an existing patient record, or a new identifier to set for a new record when create=true
(only one of id or eid is required in the URL)
view or edit; optional, default is view
use to force the creation of a new record when passing an eid and no record was found with that identifier; optional, by default an error message is returned when the requested patient is not found

For example:


Passing data from an external application into the PhenoTips record

When opening the patient record, it is possible to pass in values for the fields in PhenoTips.PatientClass. Send in the request, either as GET parameters in the URL, or as POST parameters, key-value pairs where the key is the name of the PatientClass property, such as date_of_birth, last_name, global_mode_of_inheritance, indication_for_referral, and the value is the value you want to assign, with the following rules:

  • BooleanClass fields accept 0 for false/no, 1 for true/yes, and -1 for unsetting the value: miscarriages=1&consanguinity=0
  • NumberClass fields accept normal arabic numerals, such as 42 or 123.45, always using the dot as the decimal separator: gestation=37
  • DateClass fields accept dates in the ISO 8601 format: date_of_birth=1984-06-13
  • For fields that accept a list of values, such as phenotype or maternal_ethnicity, send multiple key-value pairs with the same key: maternal_ethnicity=Irish&maternal_ethnicity=Italian
  • Strings should be sent using the UTF-8 character encoding, URL-encoded if sent in the URL: first_name=Herg%C3%A9
  • StringClass fields, and individual values in a list field, must be at most 255 characters long
  • TextAreaClass fields must be at most 60,000 characters long

For example:


Changing the skin to better emulate the wrapping application

The recommended way of styling PhenoTips is through a custom Color Theme.

  • Open PhenoTips in a browser
  • Log in with an administrative account
  • Click on the Administration link displayed in the top left corner
  • Select the Look & Feel / Presentation entry from the left menu
  • Select one of the existing Color Themes, or click on Manage color themes to create a new one
  • From the color theme management interface, you can create a new color theme by typing a name for it and clicking the Create new theme button
  • The colors for the different elements of the page can now be modified using an in-place editor, though this doesn't cover other aspects of the skin, such as fonts, paddings and margins, shadows and gradients...
  • To add extra CSS, while on your custom color theme page, hover over the Edit menu and select the Objects option
  • From the New object drop down, select XWiki / StyleSheetExtension, click Add
  • Type your custom CSS code in the Code text area, save when done
    While still developing the CSS rules, change the Caching policy to forbid so that you don't save the old version of the code in the browser's cache; don't forget to change it back to long when the site is ready for production use

If you do not see the drop down list under the Edit menu, then the currently logged in user is marked as a Simple user, and only Advanced users can see that menu. To change your user type:

  • Click on your username in the top right corner
  • Select Preferences from the left side menu
  • Click the pencil icon on the right of Display Preferences
  • From the Editor Preferences / User type drop down, select Advanced
  • Click one of the Save buttons

You should now see the edit options.


PhenoTips® is freely available under the terms of the the GNU Affero General Public License, version 3.0.

 Download the latest release
 Play with our demo
 Get the source code


 Ask for free support (by volunteers):
 Inquire about commercial support:
 Follow us on twitter:

PhenoTips® is an exclusive trademark of Gene42 Inc.