Generic HIS integration Quick Install


1. Among files external.sample-*.php, find the one dedicated to your PACS
   and rename/copy it to external.php.

2. Modify first lines of external.php:

	define("SHOW_ENABLED", true);		// true: HIS integration is enabled; false: disabled
	define("SHOW_DB", "dbname");		// database name
	define("SHOW_USER", "user");		// a database user
	define("SHOW_PASSWORD", "password");	// corresponding password

3. Ensure that your HIS generates URLs with proper query keys:

	URL?study=STUDY_UID
		Will open a study referenced by Study UID

		Unsupported by FileSystem and eHC.

	URL?accnum=ACCESSION_NO
		Will open a study referenced by Accession Number

		DCM4CHEE and external.sample-dcm4chee.php only.

	URL?patient=PATIENT_UID
		Will open the Search dialog with studies of the patient referenced
		by Patient UID

		Unsupported by FileSystem and eHC.

	URL?series=SERIES_UID
		Will open a series referenced by Series UID

		PacsOne and DCM4CHEE only, external.sample-rssdimed-*.php required.

	URL?file=PATH_TO_FILE
		Will open an image file referenced by its path. If the path refers
		to a directory, there will be an attempt to load the first study.

		FileSystem only.

	URL?identification=EHC_IDENT
		Will open a study referenced by a combined eHC identifier ("tipoid"
		column, '-', "identificacion" column)

		eHC only.

	A most popular example:
		http://localhost/meddream/index.php?study=1.2.392.200036.9107.500.110113

	Besides GET, a more secure POST request is supported, too. For added
	convenience, you might also want to open a new browser window: then
	it becomes possible to reuse this window when opening other objects.
	Both ideas are implemented in the HTML example at the end of this
	document.

	PacsOne and DCM4CHEE, via external.sample-rssdimed-*.php, support opening
	multiple studies or multiple series at once; see the integration details
	below. Since 3.15, ClearCanvas supports multiple studies as well.

4. If MedDream still shows the login page:

	For most PACSes (except "WADO" and "DICOM" pseudo-DBMSes), the login page
	is shown instead if external.php was unable to validate the reference. The
	message below the "Login" button tells the cause. Values of the Hint are:

		1	No object found by this reference

		2	Unable to connect to the database for validation. Check
			definitions of SHOW_* in the first lines of external.php.
			Also try logging in interactively as the problem might be
			more general.

		3	Invalid validation query (DBMS reported an error)

		4	This query key is not supported by PACS

	This is the old validation mechanism. The newer one, implemented so far
	in a few integration samples (for example, ClearCanvas and FileSystem),
	uses more user-friendly messages and hides the login page in most cases.


----------------------------------------------------------------------------


			INTEGRATION SYNTAX DETAILS

The following corresponds to meddream.swf at least v3.10.1112.2000. At the
time of this writing, these capabilities are not fully supported yet by every
version of external.php. For example, multiple studies fail UID validation via
external.sample-pacsone.php, they require external.sample-rssdimed-pacsone.php
instead.


DEFINITIONS

	URL
		MedDream root hyperlink without the query part (e.g., http://localhost/meddream/).
		It is OK to include index.php or home.php.

	series_uid
		Series unique ID (PacsOne database: series.uuid, DCM4CHEE: series.series_iuid)

	study_uid
		Study unique ID (PacsOne: study.uuid, DCM4CHEE: study.study_iuid)

	view
		Basic MedDream interface: a thumbnail strip plus an image viewing
		area. Multiple "copies" of this interface, called "views" from now
		on, are supported side-by side, with a common toolbar; this is
		typically used to compare two studies.

	layout
		Further division of the image viewing area in a particular view.
		Multiple divisions, called "layout areas" from now on, are typically
		used to compare arbitrary images from the same study. Controlled
		by toolbar buttons "1x1 Screen Layout" etc, but also see
		specification for the "layout" query key, below.

	Multi Image
		A function that divides a particular layout area even further
		and automatically displays adjacent images in the resulting grid.
		Typically used to compare neighboring CT slices etc. Controlled
		by toolbar buttons "1x1 Multi Image" and "2x2 Multi image", but
		also see specification for the "multiimage" query key, below.


QUERY KEYS

	view
		The number of views on the screen, tiled horizontally. An integer,
		1 by default. Too large values are replaced with the maximum, 5.

		Example: URL?view=2
			Two views. Works also in the interactive (non-HIS) mode, however
			do not forget to select a particular view before adding a study
			with the Search button.

	study
		Enter study viewing mode, display the specified study. Basic
		example:

			URL?study=study_uid
				A single study referenced by study_uid is added to the
				view 1.

		Multiple identifiers are delimited by commas and semicolons. A
		sequence of identifiers delimited by commas is intended for a
		particular view and targets layout areas available there. A
		semicolon starts contents of another view. Examples:

			URL?study=study_uid1,study_uid2
				View 1 contains study_uid1 and study_uid2

			URL?study=study_uid1;study_uid2
				View 1: study_uid1, view 2: study_uid2

			URL?study=study_uid1,study_uid2;study_uid2,study_uid3
				View 1: study_uid1 and study_uid2, view 2: study_uid2 and
				study_uid3

		If there are not enough views, all excess identifiers are assigned
		to the last one. Example:

			 URL?study=study_uid1;study_uid2;study_uid3&view=2
				View 1: study_uid1, view 2: study_uid2 and study_uid3

		Duplicate identifiers in the same view are ignored. Example:

			URL?study=study_uid1,study_uid1&view=2
				View 1: study_uid1, view 2: empty

		However, different views can receive the same study. Example:

			URL?study=study_uid1;study_uid1&view=2
				View 1: study_uid1, view 2: study_uid1

	series
		Enter series viewing mode (incompatible with the "study" key). Basic
		example:

			URL?series=series_uid
				A single series referenced by series_uid is added to the
				view 1.

		For multiple series, see the "study" key above -- the same rules apply.

		NOTE: This key is ignored if the "study" key is also found.

	layout
		The layout of each view. Two integers in form of
		num_of_rows, "x", num_of_columns. Values outside limits 1 ... 3 are
		silently replaced with those limits. A differently formatted entry
		is ignored. Example:

			URL?layout=2x2
				The view 1 is split into a 2-by-2 grid and can therefore show
				4 images, just like after the button "2x2 Screen Layout".

		Multiple layouts are intended for different views and, as before,
		are delimited by a semicolon. Examples:

			URL?layout=2x2;1x1
				View 1: 2-by-2, view 2: a single image.

			URL?layout=2x2;1x1&view=1
				View 1 is 2-by-2. The excess specification "1x1" is ignored.

			URL?layout=2x2;&view=2
				View 1 is 2-by-2. View 2 sports the default layout defined in
				MedDream settings.

	thumbpos
		Initial location of the thumbnail strip. Possible values are "bottom"
		and "left". Unrecognized values are silently ignored. Example:

			URL?thumbpos=bottom;&view=2
				Both views have thumbnail strips at the bottom. The toolbar
				button "Thumbnails Position Left/Bottom" can still change
				orientation for the selected view (but not for *all* views
				simultaneously).

		NOTE: If you open the Settings dialog when this option is in effect,
		its value will override a preserved value and, therefore, will become
		default after settings are saved by pressing "OK".

	compactview
		Display only the first thumbnail image in every series. Thumbnail size
		is set to maximum (150-by-150 pixels).

		Available values:
			1 -- activate compact thumbnails view
			0 -- usual contents of the thumbnail strip (default)

		Example:

			URL?study=study_uid1&compactview=1
				Each series of study_uid1 will contain only one thumbnail image.
	vw
		Series width for the vertical thumbnail strip.
		Available values: 60 ... 1000. Default value as defined in settings.

		Example:

			URL?study=study_uid1&vw=150
				Each series of study_uid1 will be 150px wide.
	vh
		Series height for the vertical thumbnail strip.
		Available values: 60 ... 1000. Default value as defined in settings.

		Example:

			URL?study=study_uid1&vh=150
				Each series of study_uid1 will be 150px high.
	hw
		Series width for the horizontal thumbnail strip.
		Available values: 60 ... 1000. Default value as defined in settings.

		Example:

			URL?study=study_uid1&vw=150
				Each series of study_uid1 will be 150px wide.
	hh
		Series height for the horizontal thumbnail strip.
		Available values: 60 ... 1000. Default value as defined in settings.

		Example:

			URL?study=study_uid1&vh=150
				Each series of study_uid1 will be 150px high.

	multiimage
		Automatically enables Multi Image function on every opened study or
		series. Two integers in form of num_of_rows, "x", num_of_columns. Values
		outside limits 1 ... 3 are silently replaced with those limits. A
		differently formatted entry is ignored.

		Multiple entries are intended for different views and, as before, are
		delimited by a semicolon. Example:

			URL?study=study_uid1&multiimage=2x2;2x2&view=2
				Enables Multi Image function for view 1 and view 2. Both views
				will contain 4 images each.

		NOTE: If the Auto Open First Image option (in the settings) is set to

			Always:
				for a study -- open first image and apply Multi Image;

				for a series -- open first image of each series in available
				layout areas, and apply Multi Image to each area. Example:

					URL?series=series_uid1,series_uid2&multiimage=2x2&layout=2x1

						Open first image of series_uid1 in the first layout area
						and apply Multi Image; as a result, the first area divides
						into a 2-by-2 grid and displays up to 3 further images from
						that series.

						Open first image of series_uid2 in the second layout area
						and apply Multi Image, therefore 4 consequent images are
						shown there.

			None:
				Applies Multi Image to every layout area, without opening any
				images.

			Single: (open if study/series consists of a single image)
				The Multi Image is not applied to such studies or series as it
				has no practical use. The button "2x2 Multi Image" in this case
				still works as intended and (needlessly) divides the selected
				layout area.

	toolbar
		Hide and/or rearrange the toolbar buttons. Button numbers must be
		delimited by semicolons. Out-of-range numbers are ignored. An empty
		list effectively means "no toolbar"; that might also occur due to
		invalid numbers or wrong delimiters.

		Button numbers are 1-based and correspond to a full unmodified toolbar:

			1	Search
			2	Windowing (W)
			3	Hand (H)
			4	Zoom (+/-)
			5	Measure
			6	Magnifinder (M)
			7	Fit to Screen (2)
			8	1:1 Resolution (1)
			9	Transform
			10	Lock Scroll
			11	Reference Lines
			12	Set Scroll
			13	RGB Chanels
			14	Report
					(visible if a report is present)
			15	1x1 Multi Image
			16	2x2 Multi Image
			17	1x1 Screen Layout
			18	1x2 Screen Layout
			19	2x2 Screen Layout
			20	Screen Layout
			21	Thumbnails Position Left/Bottom
			22	Forward
			23	Burn
			24	Print
			25	Plugins
					(visible if at least one plugin was found)
			34	Save Images...
			40	Reset
					(visible in the HIS integration mode only)

		The remaining buttons can only be hidden (by *not* specifying their
		numbers), and will always remain near the toolbar end in this order:

			26	Settings
			27	Users
			28	i (About)
			29	? (Help (F1))
			30	FullScreen
			31	Language
					(visible if languages.xml exists)
			32	Logoff
					(visible in the non-HIS mode only)
			33	Close
					(visible in the HIS integration mode only)

		Examples:
			URL?toolbar=1
				A toolbar that contains only the Search button.

			URL?toolbar=0
				The simplest way to hide the entire toolbar.

			URL?toolbar=3;14;8;27;4
				Will host the buttons "Hand (H)", "1x1 Multi Image",
				"1:1 Resolution (1)", "Zoom (+/-)". The right side also
				contains "FullScreen".

	dicomflow
		Override the "DICOM Flow" setting. Available values: 1 or 0.

		Some installations might turn off the "DICOM Flow" setting, in order
		to avoid problems with slow connection and/or extremely large
		studies that require more RAM than present in a typical client
		computer.

		Of course, sometimes it might be required to do the opposite.

		Example:
			URL?study=study_uid&dicomflow=1
				If one is sure that this study can be opened, then some
				navigation comfort is added even if "DICOM Flow" is globally
				off.


MORE EXAMPLES

	http://localhost/meddream/index.php?study=study_uid;study_uid;study_uid;study_uid
	http://localhost/meddream/index.php?study=study_uid;study_uid1;study_uid1;study_uid1
	http://localhost/meddream/index.php?study=study_uid;study_uid1&view=2&thumbpos=left

	http://localhost/meddream/index.php?study=study_uid&view=2
	http://localhost/meddream/index.php?study=study_uid&view=2&layout=2x2;1x1
	http://localhost/meddream/index.php?study=study_uid&view=2&layout=5x5
	http://localhost/meddream/index.php?series=series_uid&view=2&layout=5x5&toolbar=1;2;3;4;5
	http://localhost/meddream/index.php?series=series_uid&view=2&thumbpos=bottom
	http://localhost/meddream/index.php?series=series_uid&view=2&thumbpos=left
	http://localhost/meddream/index.php?study=study_uid;study_uid;study_uid;study_uid&view=2&thumbpos=bottom&layout=2x2;1x1&toolbar=1;2;3;4;5


----------------------------------------------------------------------------


			INTEGRATION HTML EXAMPLE

Copy the following to an HTML file in the MedDream root directory. It is
assumed that this directory is hosted as "/", otherwise you should correct
the path. You also should replace the study identifier "123456" with some
real identifier that exists in your PACS.


<html>
<body>

<script language="JavaScript" type="text/javascript">
<!--

var hwin;

function openWindow(url)
{
	if (hwin) hwin.close();
	hwin = window.open(url, "MedDream","status=1,toolbar=0,menubar=0,fullscreen=1,location=0,scrollbars=0,resizable=1,width="+screen.width+",height="+screen.height+",left=0,top=0");
}

function formSubmit1(study)
{
  document.forms["form1"].study.value = study;
  document.forms["form1"].submit();
}

function formSubmit2(study)
{
	if (hwin) hwin.close();
	hwin = window.open("", "MedDream","status=1,toolbar=0,menubar=0,fullscreen=1,location=0,scrollbars=0,resizable=1,width="+screen.width+",height="+screen.height+",left=0,top=0");
	document.forms["form2"].study.value = study;
	document.forms["form2"].submit();
}

// -->
</script>

<A href="/?study=123456">Link (GET method) to study Number 123456</a>

<br>
<br>

<A onclick="openWindow('/?study=123456'); return false;" href="#">
Link (GET method) in external window to study Number 123456
</A>
<br>
<br>

<form name="form1" action="/" method=POST>
	<input type=hidden name=study value=-1>
	<A href="javascript:formSubmit1('123456')">Link (POST method) to study Number 123456</a>
</form>

<form name="form2" action="/" method=POST target="MedDream">
	<input type=hidden name=study value=-1>
	<A href="javascript:formSubmit2('123456')">Link (POST method) in external window to study Number 123456</a>
</form>

</body>
</html>