7/22/2019 CDSA Developers Guide.pdf
1/74
Clinical Documentation Solution Accelerator
Developer's Guide
Thursday, 15 April 2010Version 1.0.0.0
Prepared by
Microsoft
7/22/2019 CDSA Developers Guide.pdf
2/74
Microsoft
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication.
Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft
cannot guarantee the accuracy of any information presented after the date of publication.
MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be
reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, orotherwise), or for any purpose, without the express written permission of Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document.
Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these
patents, trademarks, copyrights, or other intellectual property.
The descriptions of other companies products in this document, if any, are provided only as a convenience to you. Any such references should not be
considered an endorsement or support by Microsoft. Microsoft cannot guarantee their accuracy, and the products may change over time. Also, the
descriptions are intended as brief highlights to aid understanding, rather than as thorough coverage. For authoritative descriptions of these products, please
consult their respective manufacturers.
2010 Microsoft Corporation. All rights reserved.
Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
SNOMED CT is a registered trademark of the International Health Terminology Standards Development Organization.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.
Page ii
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
7/22/2019 CDSA Developers Guide.pdf
3/74
Microsoft
Page iii
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
TABLE OF CONTENTS
1 Introduct ion .............................................................................................................................. 12 Overview of the CDSA Development Environment ................................................................. 3
2.1 System Prerequisites ........................................................................................................... 32.2 Assumed Skills and Knowledge ........................................................................................... 32.3 Building the CDSA Solution in Visual Studio......................................................................... 4
2.3.1 Visual Studio 2008.......................................................................................................... 42.3.2 Visual Studio 2010.......................................................................................................... 4
2.4 Debugging the CDSA Add-in using Visual Studio ................................................................. 42.4.1 Office Word 2007 ........................................................................................................... 42.4.2 Office Word 2010 ........................................................................................................... 5
2.5 Installing the CDSA Office Word Add-in ............................................................................... 52.6 The CDSA Source Folders ................................................................................................... 62.7 Accessing the CDSA Development Environment .................................................................. 6
3 Constructing a Template Using the Included Controls........................................................... 93.1 Introduction.......................................................................................................................... 93.2 Inserting and Formatting Office Word Tables ....................................................................... 93.3 Adding and Modifying the CDSA Controls .......................................................................... 103.4 Deleting Controls ............................................................................................................... 16
4 Creating a Simple Contro l ...................................................................................................... 174.1 Introduction........................................................................................................................ 174.2 Creating the Name Input Control ........................................................................................ 18
5 Customising the Layout of an Existi ng Control .................................................................... 215.1 Introduction........................................................................................................................ 215.2 Creating the Customised Single Concept List Control ........................................................ 21
6 Creating a WPF-Based Control .............................................................................................. 266.1 Introduction........................................................................................................................ 266.2 Creating the WPF-Based Control ....................................................................................... 28
7 Creating a WPF-Based List Control ....................................................................................... 397.1 Introduction........................................................................................................................ 397.2 Creating the WPF-Based List Control ................................................................................. 40
8 Creating an XML Mapp ing Class ............................................................................................ 558.1 Introduction........................................................................................................................ 558.2 Creating the New XML File ................................................................................................ 55
7/22/2019 CDSA Developers Guide.pdf
4/74
Microsoft
Page iv
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
8.3 Creating a Storage Class ................................................................................................... 588.4 Creating a Storage Template ............................................................................................. 588.5 Changing the Storage Class Reference ............................................................................. 618.6 Mapping Across All Items................................................................................................... 638.7 Running Custom Code ....................................................................................................... 658.8 Creating a Model ............................................................................................................... 66
9 Document Information............................................................................................................ 699.1 Terms and Abbreviations ................................................................................................... 699.2 Definitions .............................................................................Error! Bookmark not defined.9.3 Nomenclature .................................................................................................................... 69
9.3.1 Body Text ..................................................................................................................... 699.3.2 Cross References ......................................................................................................... 70
9.4 References ........................................................................................................................ 70
7/22/2019 CDSA Developers Guide.pdf
5/74
Microsoft
Page 1
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
1 INTRODUCTION
The Clinical Documentation Solution Accelerator (CDSA) for the MicrosoftOffice system enables
you to provide solutions for users whose task is to create clinically encoded documents. Users write
those documents based on the CDSA templates you have designed (for example, for a Discharge
Summary or a Referral) and edit them using MicrosoftOffice Word.
CDSA promotes the safety and consistency of clinical documentation by utilising Microsoft Health
Common User Interface (CUI) software toolkit controls. Those controls support the embedding of
structured, machine-readable clinical information in a human-readable Office Word document that
is shareable across care boundaries. The encoding of clinical information is to industry standard
formats (such as the Health Level 7 (HL7) Clinical Document Architecture (CDA)).
CDSA allows for the direct utilisation of external clinical data in a document (perhaps from a cloud
computing or WindowsAzure source). Example external data sources include Systematized
Nomenclature of Medicine Clinical Terms (SNOMED CT) encoding services or drug reference
data.
That combination of features provides the means of creating clinical documents that incorporatecomplex encoding but which are written using the familiar Office Word interface.
Figure 1 provides an example of what the user might see when editing a CDSA document (on the
left is the main document and on the right the summary of clinically-encoded terms from it):
Figure 1: Users View When Editing a CDSA-Enabled document
Such documents can act as significant building blocks within an overall healthcare environment.
For example, you can incorporate them as the foundation for clinical document workflows (perhaps
in combination with MicrosoftOffice SharePoint
Server 2010). To facilitate this, CDSA allows you
to:
Tailor documents to the specific Electronic Medical Record (EMR) or Electronic Health
Record (EHR) systems in your healthcare environment
Create clinical documents suitable for upload to a Personal Health Record (PHR) system
(such as MicrosoftHealthVault) or to other external storage
Easily share clinical documents, passing them across care boundaries whilst retaining the
clinically encoded data
7/22/2019 CDSA Developers Guide.pdf
6/74
Microsoft
Page 2
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
More specifically, the CDSA toolkit extends Office Word to provide the functionality indicated for the
following groups:
For Clinical Template Designers With the CDSA add-in enabled, a template designer
can create Office Word templates. In addition to providing a human-readable document,
such templates can allow the data entered in the document to be mapped to a
machine-readable representation using clinical encoding taxonomies (such asSNOMED CT)
For Clinical Document Creators With the CDSA add-in enabled, a user can complete a
clinical form created from a CDSA-enabled Office Word template. The one Office Word
(.docx) file contains both human-readable and machine-readable clinical information (such
as a HL7 CDA representation).
For Clinical Document recipients Without the need for the CDSA add-in, a recipient can
read (but not edit) the Office Word document. The document .docx file still contains the
machine-readable clinical information and this can be extracted and uploaded to an
external clinical system.
The remainder of this document provides background information and worked examples to
illustrate how you can customise CDSA for your own purposes. The topics covered are:
Overview of the CDSA development environment (see section2)
Constructing a template using the included controls (see section3)
Creating a simple control (see section4)
Customising the layout of an existing control (see section5)
Creating a WindowsPresentation Foundation (WPF) based control (see section6)
Creating a WPF-based list control (see section7)
Creating a mapping class (see section8)
7/22/2019 CDSA Developers Guide.pdf
7/74
Microsoft
Page 3
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
2 OVERVIEW OF THE CDSADEVELOPMENT
ENVIRONMENT
2.1 System PrerequisitesTo run and use the CDSA development environment requires a system matching at least the
following requirements.
Your computer must be running one of the following operating systems:
Windows7
Windows Vista
Service Pack 1
With Windows Vista, you also need Microsoft.NET Framework 3.5 Service Pack 1
1
WindowsXP Service Pack 3
With Windows XP, you also need Microsoft.NET Framework 3.5 Service Pack 1
1
Your computer must have these applications installed:
Microsoft Office Word 2010 or Microsoft Office Word 2007
With Microsoft Office Word 2007, you also need:
2007 Microsoft Office System Update: Redistributable Primary Interop Assemblies2
MicrosoftVisual Studio
Tools for the Microsoft Office System (version 3.0 Runtime)
(x86)
3
Microsoft Visual Studio Tools for the Microsoft Office System (version 3.0 Runtime)
Service Pack 1 (x86)
4
MicrosoftVisual Studio2008 Service Pack 1 or Microsoft Visual Studio 2010
2.2 Assumed Skills and Knowledge
This guide assumes that you have at least the following technical knowledge and skills:
Expertise with Office Word, in particular an in-depth knowledge of table formatting and the
creation of templates
General understanding of Microsoft Visual Studio and its underlying platform technology
Guidelines on the skill sets required in order to make best use of CDSA, as well as reference
material and training resources, are detailed on the Microsoft TechNet Web site5
1Downloadable from
. However, the use
of Microsoft courses and resources are optional and training on a number of relevant areas can be
provided by a variety of certified training partners.
Microsoft .NET Framework 3.5 Service Pack 1
2Downloadable fromRedistributable Primary Interop Assemblies
3Downloadable fromVisual Studio Tools for the Microsoft Office System
4
Downloadable fromVisual Studio Tools for the Microsoft Office System Service Pack 15Microsoft TechNet {R1}:http://technet.microsoft.com/
http://www.microsoft.com/downloads/details.aspx?FamilyID=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=59daebaa-bed4-4282-a28c-b864d8bfa513&DisplayLang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=59daebaa-bed4-4282-a28c-b864d8bfa513&DisplayLang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=59daebaa-bed4-4282-a28c-b864d8bfa513&DisplayLang=enhttp://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=54eb3a5a-0e52-40f9-a2d1-eecd7a092dcbhttp://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=54eb3a5a-0e52-40f9-a2d1-eecd7a092dcbhttp://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=54eb3a5a-0e52-40f9-a2d1-eecd7a092dcbhttp://www.microsoft.com/downloads/details.aspx?familyid=D8EB4921-891A-4B5E-973F-0B96E6CCF376&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?familyid=D8EB4921-891A-4B5E-973F-0B96E6CCF376&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?familyid=D8EB4921-891A-4B5E-973F-0B96E6CCF376&displaylang=enhttp://technet.microsoft.com/http://technet.microsoft.com/http://technet.microsoft.com/http://technet.microsoft.com/http://www.microsoft.com/downloads/details.aspx?familyid=D8EB4921-891A-4B5E-973F-0B96E6CCF376&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=54eb3a5a-0e52-40f9-a2d1-eecd7a092dcbhttp://www.microsoft.com/downloads/details.aspx?FamilyID=59daebaa-bed4-4282-a28c-b864d8bfa513&DisplayLang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=en7/22/2019 CDSA Developers Guide.pdf
8/74
Microsoft
Page 4
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
2.3 Building the CDSA Solution in Visual Studio
You can build the CDSA solution in either Visual Studio 2008 or Visual Studio 2010. Obtain the
CDSA solution files by downloading the Microsoft.Cdsa.zip file6
2.3.1 Visual Studio 2008
.
To build the CDSA solution in Visual Studio 2008, follow these steps:
1. Extract all the files from the Microsoft.Cdsa.zip file into their default file structure
2. Navigate to the \Microsoft.Cdsa\Solutions\Main folder and open the Main.sln file
3. Press F6 to build the solution
2.3.2 Visual Studio 2010
The CDSA solution has been created by Visual Studio 2008. The solution needs to be upgraded for
use with Visual Studio 2010. To do so, follow these steps:
1. Extract all the files from the Microsoft.Cdsa.zip file into their default file structure.
2. Navigate to the \Microsoft.Cdsa\Solutions\Main folder and open the Main.sln file
3. Follow the steps in the Visual Studio Conversion Wizard to upgrade the solution to Visual
Studio 2010
4. A dialog box will appear asking Do you want to upgrade the Web site to use .NET
Framework 4.0? Select the Do the same for all Webscheck box and click No
5. When the solution has opened, right-click on the Microsoft.Consulting.OfficeTools.Controls
project and select the Properties> Code Analysistab
6. Disable the code analysis rule CA1903 - Microsoft.Portability: Use only API from
targetted frameworklisted under Portability Rules by clearing the check box
7. Disable the same rule for the Microsoft.Consulting.Servicesproject
8. Press F6 to build the solution
2.4 Debugging the CDSA Add-In Using Visual Studio
You can run the Office Word add-in project in debug mode using Visual Studio for either Office
Word 2007 or Office Word 2010.
2.4.1 Office Word 2007
To run in debug mode for Office Word 2007, follow these steps:
1. In Solution Explorer, check that the Microsoft.Consulting.OfficeTools.WordAddinproject is
set as the start-up project by default (the project name should be displayed in bold). If it is
not, right-click the project and select Set as StartUp Project
2. Press F5 to launch Office Word with the CDSA add-in enabled
6Downloadable fromhttp://www.codeplex.com/cdsa
http://www.codeplex.com/cdsahttp://www.codeplex.com/cdsahttp://www.codeplex.com/cdsahttp://www.codeplex.com/cdsa7/22/2019 CDSA Developers Guide.pdf
9/74
Microsoft
Page 5
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
2.4.2 Office Word 2010
To run in debug mode for Office Word 2010, follow these steps:
1. In Solution Explorer, check that the Microsoft.Consulting.OfficeTools.WordAddinproject is
set as the start-up project by default (the project name should be displayed in bold). If it is
not, right-click the project and select Set as StartUp Project
2. Right-click on the Microsoft.Consulting.OfficeTools.WordAddin project and select the
Properties > Debug tab
3. Set the Start Actionby selecting the Start external programradio button.
4. Navigate to the location of the Office 2010 WINWORD.EXE file (usually C:\Program
Files\Microsoft Office\Office14\WINWORD.EXE)
5. Press F5 to launch Office Word with the CDSA add-in enabled
2.5 Installing the CDSA Office Word Add-In
The CDSA solution includes a set-up project (Microsoft.Consulting.OfficeTools.WordAddin.Setup)that creates a sample MSI. You can use this to install the CDSA Office Word add-in on a per-user
basis (that is, for the current user only).
The sample installer performs the following actions:
Installs the CDSA Office Word add-in for the current user
Adds a new registry key:
HKEY_CURRENT_USER\Software\Microsoft\Office\Word\Addins\Microsoft.Consulting.OfficeTools.WordAddin
Copies the following files to the installation folder:
All assemblies used by the CDSA Office Word add-in
Schemas for native CDSA XML
The CDSABuildingBlocks Word template
Unlocked versions of the sample CDSA Office Word templates (for developer
demonstration purposes)
By default, the installation folder is:
C:\Users\\AppData\Roaming\Microsoft\Clinical Documentation Solution Accelerator
Copies the sample CDSA Office Word templates to the Clinical Documents folder in the
users Templates directory. Those versions of the templates are locked and end users can
only update the content of the form fields. On Windows 7 and Windows Vista, the
Templates directory is:
C:\Users\\AppData\Roaming\Microsoft\Templates\Clinical Documents
Note
The sample installer does not check for prerequisites before installing CDSA. When creating a version of
the installer for a production environment, you may need to create different versions of the installer for
Office 2007 and Office 2010 (Office 2007 has a number of prerequisites that are not required for Office
2010). See the ReadMe.txt for a full list of the end-user prerequisites.
7/22/2019 CDSA Developers Guide.pdf
10/74
Microsoft
Page 6
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
2.6 The CDSA Source Folders
Table 1 describes the directory structure of the CDSA source and the content of each folder:
Directory Content
Sample Forms Two sample Office Word templates (.dotx files) built using CDSA controls:
Cardiology Referral form
Cardiology Referral form (Unlocked)
Discharge Summary form
Discharge Summary form (Unlocked)
Microsoft.Cdsa.Services.Common Service contracts for the Terminology Service and the Drug Service and
data contracts for the Terminology service
Microsoft.Consulting.Data Data contracts for the Drug Service
Microsoft.Consulting.OfficeTools.Controls All controls-related classes including:
CDSA section controls WPF controls used by the section controls
Layout for the WPF controls on the Document Summary task pane
Helper classes for the controls
Base storage class and sample classes for the Referral and Discharge
Summary forms
Referral and Discharge Summary mappings and schema files
Model class used by the storage class
Microsoft.Consulting.OfficeTools.WordAddin The CDSA Office Word add-in project including:
Ribbon class
Developer Properties window implementation Document Summary task pane implementation
Microsoft.Consulting.OfficeTools.WordAddin.Setup Setup project that builds a sample Microsoft Installer (MSI) to install the
CDSA Office Word add-in and the two sample templates on a per-user basis
Microsoft.Consulting.Services WindowsCommunication Foundation (WCF) service interfaces for:
The sample SNOMED CT Terminology Service
(TerminologyService.svc)
The sample medications Data Service (DrugService.svc)
Table 1: CDSA Directories and Folder Content
2.7 Accessing the CDSA Development Environment
To access the CDSA development environment after installing the CDSA Office Word add-in, follow
these steps:
1. Start Office Word
2. Click the CDSA Developertab. If it is not visible, take these steps first:
a. Click the CDSA Usertab
b. From the CDSA Userribbon, click the Developer Tabbutton
7/22/2019 CDSA Developers Guide.pdf
11/74
Microsoft
Page 7
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Figure 2 shows what the CDSA developer ribbon looks like when you first access it:
Figure 2: CDSA Developer Ribbon
Table 2 describes the function of each button on the CDSA developer ribbon:
Button Description
Converts an Office Word document into a CDSA document by creating the correct XML
configuration.
You use this tool as the first step in developing a CDSA-compliant document. Until this is done,
CDSA disables all of the other developer ribbon buttons.
Accesses the configuration and data details of the controls in the document.
Opens the library of built-in controls that you can use in your CDSA document. You can also add
controls to the Section Gallery that you have implemented.
A control placed in a document is referred to as a section.
Table 3details the controls available in the Section Gallery.
Removes a section from your CDSA document.
You have to select the section before you can delete it.
Ensures all sections are updated according to the latest configuration and are bound to the native
XML.
You use this after making amendments to controls or changing other CDSA document definitions.
Accesses the array of built-in section building-blocks that you can use to create your own controls.
A section building block is referred to as apart.
Table 4details the parts available in the Custom Parts Gallery.
Table 2: CDSA Developer Buttons
If you are implementing a new CDSA template, you can make use of the built-in sections already
available in the Section Gallery.Table 3 lists and describes the sections in the Section Gallery:
Section Name Descript ion
Address Field Multi-line address entry fields with labels
Allergies Concept List Allergy search and list control with date and status settings (provides encoding)
Check Box Simple check box with label
Date Field Automatic and free-text date entry
Drop Down List Selection menu with prompt watermark text
Free Text Parser Clinical terms search and list control based on user entered free-text (provides encoding)
Medication List Medications search and list control (provides encoding)
7/22/2019 CDSA Developers Guide.pdf
12/74
Microsoft
Page 8
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Section Name Descript ion
Mini Patient Banner Simplified patient details banner with labels
Patient Banner Full patient details banner with labels
Radio Button Simple radio button with label
Single Concept List (no date) Single concept search and list control either without date support (provides encoding)
Single Concept List (with date) Single concept search and list control either with date support (provides encoding)
Text Field Simple text entry field with prompt watermark text
Table 3: Section Gallery
If you are implementing a new CDSA control, you can make use of the built-in parts available in the
Custom Parts Gallery, each of which provides a rich text content control placeholder.Table 4 lists
and describes the parts in the Custom Parts Gallery:
Part Name Descript ion
Action Control Insertion Part Placeholder for a .NET Framework control
Section Edit Button Insertion Part Placeholder for a Section Edit button
Section Line Delete Button Insertion Part Placeholder for a lines Delete button
Section Line Edit Button Insertion Part Placeholder for a lines Edit button
Section Line Part Placeholder for a line layout
Section Lines Insertion Part Placeholder for a sections line insertion table
Section Part Constructs a section layout. Adds a new section to the document and to the Developer
Propertieswindow
Word Control Insertion Part Placeholder for an Office Word Visual Basic for Applications (VBA) control
Table 4: Custom Parts Gallery
The worked examples in the remainder of this guide describe how you can use the CDSA
development environment to create and customise your own CDSA-compliant documents.
7/22/2019 CDSA Developers Guide.pdf
13/74
Microsoft
Page 9
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
3 CONSTRUCTING A TEMPLATE USING THE INCLUDED
CONTROLS
3.1 IntroductionThe CDSA software includes a number of ready-made controls for you to use when constructing
your Office Word templates. You can also use controls of your own making, as described in section
7.However, the built-in controls provide a wide range of functionality and you may find that they are
sufficient to implement all of the features you need.
You construct a template by using the tools and facilities provided by the CDSA development
environment (as described in section2.3). After starting Office Word, you must open the CDSA
Developertab and click the Convert To Clinical Documentbutton to begin the development
process.
In outline, the steps involved in constructing a template are:
1. Insert and format Office Word tables to structure your document (for ease of layout andusability purposes, most controls are located in tables) (see section3.2)
2. Add and modify the required controls (see section3.3)
3. Delete controls to fine-tune the template layout (see section3.4)
To guide you in implementing your template, the remainder of this section provides more details
and examples to illustrate each of those steps.
3.2 Inserting and Formatting Office Word Tables
You use the standard table insertion and layout features of Office Word to create the outline
structure of your document. An example set of steps you might follow would be:
1. Insert a table with enough columns and rows to match your input requirements
2. Turn on gridlines to help track the layout of the cells
3. Adjust the size and other features of the cells to match the layout you require
4. Add narrow rows as spacers to separate distinct blocks of the table
5. Use the first row as a header for the material in the table (for example, by adding special
formats such as a different background shade with an external border and the text in a
coloured font)
6. Prepare the cells that will hold the controls (for example, to emphasise that these are inputareas, configure borders around the cells and add an appropriate label to each)
When you have completed the outline structure, you can move on to include the CDSA controls
that will help your users add their information to the document.
7/22/2019 CDSA Developers Guide.pdf
14/74
Microsoft
Page 10
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
3.3 Adding and Modifying the CDSA Contro ls
Although the provided controls offer a wide range of functionality, when adding each one to your
template you follow the same top-level procedure:
1. Place the cursor where you want to locate the control
2. Insert the control you require by selecting from the Section Galleryin the CDSA
Developerribbon
3. Click the Developer Propertiesbutton and open the controls Configurationscreen. Enter
a unique Section Idfor it
4. If required for your implementation, modify other Configurationscreen parameters (for
example, to modify label or watermark text)
At its simplest, you can use a control in your template just by taking steps 1 to 3. However, the
controls also allow you to customise them according to your needs. The remainder of this section
provides examples of how you do this by detailing how to add and customise the most useful
controls for clinical documents.
The examples include controls for entering relatively basic text:
Text Field Where a user enters plain text
Address Field Where a user enters an address
There are also more sophisticated search and match controls to help your users find and enter
specific medical terms:
Medication List Helps the user build a list of drug prescriptions
Single Concept L ist Helps the user build a list of descriptive terms and concepts (such
as symptoms)
Free Text Parser Identifies medical terms and concepts from a free-text descriptionentered by the user
Additional controls assist the users in selecting from pre-defined options:
Drop Down List Where a user selects from a menu of items
Radio Button Where a user selects or deselects an item
7/22/2019 CDSA Developers Guide.pdf
15/74
Microsoft
Page 11
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Table 5 describes how you add and modify each of those controls:
Step Descript ion Screenshot
Adding a Text Field
1. Select the control you want to
insert. In this case, create a simpletext entry control by selecting Text
Field.
Note
Some controls include
paragraph spaces before and
after them. Delete if not
required.
2. TheText Fieldcontrol displays
default watermark text.
To edit this:
1. In the Office Word Developer
ribbon, click Design Mode
2. Edit the text as required
3. Click Design Modeto exit
3. As templates can contain a lot of
controls, it is good practice to alter
the Section Id of each control as
you add it. This ensures the Section
Id has a more meaningful name for
future reference.
Alter the Section Id by:
1. In the CDSA Developer ribbon,
click Developer Properties
2. Select the control from the left
pane
3. Click the Configurationtab
4. Edit the text in the Section Id
field so it is specific to this
section of the document or is
otherwise meaningful to you
5. Click elsewhere in the pane to
save the new Section Id
6.
Exit the ClinicalDocumentation Developer
Windowto return to your
document
Remember to repeat these steps
for every control you add
7/22/2019 CDSA Developers Guide.pdf
16/74
Microsoft
Page 12
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
Adding an Address Field
1. Another commonly required
component of a document is a
section to hold an address.To include this, selectAddr ess
Fieldfrom theSection Gallery.
2. To edit the labels:
1. In the Office Word Developer
ribbon, click Design Mode
2. Edit the text as required
3. Click Design Modeto exit
Adding a Medicat ion List
1. To include a Medication List, select
it from the Section Gallery.
This control supports the formal
encoding of terms. Therefore,
including it in your document also
creates an entry in the Document
Summarypanel
2. Besides altering the Section Id, you
can also modify the display and
label text.
To do so, click Developer
Propertiesand edit these
Configurationfields for the control:
Display Name Modifies the
section header displayed in the
Document Summarypane
Word Control Label Modifies
the label on the Add button
Section Line Edit ButtonLabel Modifies the label on
the Edit button (only visible
after the user has added a
medication to the list)
Section Line Delete Button
Label Modifies the label on
the Delete button (only visible
after the user has added a
medication to the list)
7/22/2019 CDSA Developers Guide.pdf
17/74
Microsoft
Page 13
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
Adding Single Concept Match ing L ist
1. To include Single Concept
Matching, select it from the Section
Gallery.This control supports the formal
encoding of terms. Therefore,
including it in your document also
creates an entry in the Document
Summarypanel
2. Besides altering the Section Id,
display and label text, you can also
specify the terminology to search
through and modify the controls
watermarks.
To do so, click Developer
Propertiesand edit theseConfigurationfields for the control:
SearchSubset Specifies the
clinical terminology subset that
CDSA will search against
ConceptSearchWatermark
Modifies the watermark in the
Concept Search box
Add it ionalTextWatermark
Modifies the watermark in the
Additional Text box
3. You can also alter the headings
used in the display of the concepts.
To do so, in the Office Word
Developerribbon, click Design
Modeand follow these steps:
1. In the document, select the
heading to change
2. Click Properties
3. Uncheck theContents cannot
be editedbox and click OK
4. Modify the heading
5. Click Properties and recheck
the Contents cannot be edited
box
6. Click OKand click Design
Modeto exit
7/22/2019 CDSA Developers Guide.pdf
18/74
Microsoft
Page 14
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
Adding a Free Text Parser
1. To include a Free-Text parser, add
it from the Section Gallery.
This control supports the formalencoding of terms. Therefore,
including it in your document also
creates an entry in the Document
Summarypanel
2. Change the Section Id as described
previously.
As also described previously, you
can alter other aspects of the free-
text parser operation and display by
modifying the appropriate fields in
the Configurationtab.
7/22/2019 CDSA Developers Guide.pdf
19/74
Microsoft
Page 15
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
Adding a Drop Down List
1. To include a drop-down list, add it
from the Section Gallery.
2. Change the Section ID as
described previously.
To add items to the drop-down list:
1. Select the list
2. In the Office Word Developer
ribbon,click Properties
3. In the Content Control
Propertiesscreen, clickAdd 4. On theAdd Choicescreen,
enter the details for the menu
item
5. Click OK
6. Repeat steps 3, 4 and 5 for
each item you want to add to
the menu
7. When complete, click OK
7/22/2019 CDSA Developers Guide.pdf
20/74
Microsoft
Page 16
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
Adding a Radio But ton
1. To include a radio button, add it
from the Section Gallery.
Add as many radio buttons asneeded to match the number of
options you wish to offer your
users.
2. Besides altering the Section Id, you
will also need to specify a label for
each button and a group name that
they share.
To do so, click Developer
Propertiesand edit these
Configurationfields for the control:
Word Control Label
Specifies the label that appearsbeside the button
GroupName Specifies an
identifier for this group of
buttons (use the same identifier
for all the buttons in this group)
Table 5: Adding Controls to the Template
3.4 Deleting Controls
As you progress with the development of your template, you may decide that controls entered
earlier are no longer needed. However, because CDSA documents are structured, you cannot
simply delete controls as you would normally delete items from an ordinary Office Word document.
Instead, you have to use the CDSA DeleteSectiontool.
To delete a control using the Delete Sectiontool:
1. Select all of the control that you wish to delete
2. Open the CDSA Developerribbon
3. Click Delete Section
4. To ensure the document is cleanly updated, click Refresh All Sections
7/22/2019 CDSA Developers Guide.pdf
21/74
Microsoft
Page 17
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
4 CREATING A SIMPLE CONTROL
4.1 Introduction
CDSA controls are made up of parts. Each part is an Office Word content control that has a specific
title and/or tag. For more advanced controls, you can insert buttons and .NET controls to handle
user input.
Note
Not all types of Office Word content control can be bound to the CDSA XML. For example, plain text and
drop down lists can be bound but a rich text content control cannot. Therefore, when designing a new
control, it is important that you identify which of its areas need to display bound content and which are
placeholders for buttons or .NET controls.
This section describes the steps to take when building a simple control. The control used as an
example is a name input control that provides fields for the user to enter a family name, a given
name and a title.
The example shows how the control is constructed from:
An outer section content control (a CDSA Section Part)
Inner plain text content controls for each field (Office Word content controls)
When the control is complete, the example goes on to show:
How to bind the control to the CDSA XML
How to add the control to the CDSA Section Gallery for use in other documents
When adding a new control, you always begin by following the same steps:
1. Start Office Word
2. Open the CDSA Developertab and click the Convert To Clinical Documentbutton to
begin the development process
Having done that, you can continue to develop your new control. Follow the steps in the next
section to see how this is done for the example name input control.
7/22/2019 CDSA Developers Guide.pdf
22/74
Microsoft
Page 18
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
4.2 Creating the Name Input Control
Table 5 shows the steps required to create a simple name input control:
Step Descript ion Screenshot
1. In the Custom Parts Gallery
menu, select Section Partto
insert it in your document
2. In the Insertribbon, click Table.
Format the table to match the
layout requirements for your
control.
For the example name input
control, the layout is:
Two columns (resized to fit the
content) and three rows No borders
Add labels in the first column
(Family name, Given name
and Title), right-aligned and
italic
3. Insert plain text content controls in
each cell of the second column.
In the Controlsgroup of the
Office Word Developerribbon,
click the button to insert each
one.
4. Select each plain text content
control in turn and follow these
steps:
1. In the Controlsgroup, click
Properties
2. Enter a name for the control in
the Titlefield (respectively
Family name, Given name
and Title)
3. Click OK
7/22/2019 CDSA Developers Guide.pdf
23/74
Microsoft
Page 19
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
5. You may want to change the
watermark text displayed (Click
here to enter text).
To edit this:
1. In the Office Word Developer
ribbon, click Design Mode
2. Edit the text as required
3. Click Design Modeto exit
Note
Design Mode shows the
beginning and end section
tags and all the fields inside.
This lets you see the range
your control uses.
6. Office Word includes paragraph
spaces before and after the table
to prevent it interfering with the
section controls.
To better align the table:
1. Place your cursor in the
paragraph space
2. In the Homeribbon, open the
Paragraphdialog
3. InSpacing, set Beforeand
Afterto a suitable value
4.
From theLine Spacingmenu,selectExactlyand use theAt
field to set a suitable height
7. In the CDSA Developer ribbon,
click Refresh All Sections.
This updates the new control and
creates bindings for it in the CDSA
XML using the Content Control
Properties title as the name for the
binding.
7/22/2019 CDSA Developers Guide.pdf
24/74
Microsoft
Page 20
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
8. You can see that your new control
(now identified as a CDSA
section) is in place by:
1. In the CDSA Developer
ribbon, click DeveloperProperties
2. Select the section in the left
pane
3. Click the Datatab
Three new UniqueIdentifiers
match the plain text content
controls you defined.
TheDeveloper Properties
screen will also reflect content
entered in the fields in the
document.
Table 6: Creating a Simple Control
7/22/2019 CDSA Developers Guide.pdf
25/74
Microsoft
Page 21
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
5 CUSTOMISING THE LAYOUT OF AN EXISTING CONTROL
5.1 Introduction
The example in this section describes the steps you take to create a customised version of one of
the built-in CDSA controls. The example chosen is that of a single concept list control.
To create a custom layout for a single concept list control, you need to include the following parts in
your control layout:
An outer section content control (a CDSA Section Part)
A section line insertion point content control (a CDSA Section Lines Part)
An action control insertion point content control (a CDSAAct ion Control Part)
A word control insertion point content control (a CDSA Word Control Part)
Each of those parts is available from the CDSA Custom Parts Gallery.
As before, when adding a new control, you always begin by following the same steps:
1. Start Office Word
2. Open the CDSA Developertab and click the Convert To Clinical Documentbutton to
begin the development process
Having done that, you can continue to create your customised control. Follow the steps in the next
section to see how this is done for the example single concept list control.
5.2 Creating the Customised Single Concept List Control
Table 5 shows the steps required to create the customised single concept list control:
Step Descript ion Screenshot
Inserting Parts and Formatting the Layout
1. In the Custom Parts Gallery
menu, select Section Partto
insert it in your document
Add some extra paragraphs inside
the Section Part to make it easier
to insert the other components of
the layout.
2. For this custom layout, the part
that will provide the search controlgoes in first:
1. Position the cursor on the first
paragraph
2. In the Custom Parts Gallery
menu, selectAct ion Contr ol
Partto add it
This provides a rich text content
control as a placeholder for the
WPF control that will support
searching later.
7/22/2019 CDSA Developers Guide.pdf
26/74
Microsoft
Page 22
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
3. Add an insertion point for the Add
button at the second paragraph:
1. Right-align the second
paragraph
2. In the Custom Parts Gallery
menu, select Word Control
Partto add it
4. Add a part to position the other
lines that will make up the layout:
1. Position the cursor at the
paragraph below the Word
Control Part
2. In the Custom Parts Gallery
menu, selectSection Lines
Partto add it
This provides a rich text contentcontrol as a placeholder for the
lines that will display the list of
search results.
5. Format the lines in the layout
using a table:
1. Position the cursor in the
Section Lines Part
2. In the Insertribbon, click
Table
Create the layout in this fixed
order:
1. Two rows
2. Each row distinctly shaded
with a rule below the first and
the last
3. No other borders
4.All cell margins = 0
6. To format the headings, insert
another table in the top row with
these features:
First column width = 35%
Second column width = 65%
All cell margins = 0
No borders
Enter Diagnosis in the first
column and Additional Text in the
second. Make both bold italic.
7/22/2019 CDSA Developers Guide.pdf
27/74
Microsoft
Page 23
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
7. Remove any unwanted space:
Set the bottom row height to
hide it from view leaving just
the table headings visible
Delete unneeded paragraphs
and modify the size of those
remaining to achieve the
desired layout (for example,
Office Word allows a minimum
Multiple line spacing of 0.06)
Adding Control Assembly and Class Informat ion
1. Configure the control properties:
1. In the CDSA Developer
ribbon, click Developer
Properties
2. Select the section in the left
pane
3. Click the Configurationtab
Complete theCommon
Propertiesfields as follows:
Section Id DiagnosisList
Display Name Diagnosis
List
This appears in the Document
Summarypane
Word Control Label Add
DiagnosisThis is the label for what will
be the Add button
Section Line Edit Button
Edit
This is the label for what will
be the Edit button
Section Line Delete Button
Delete
This is the label for what will
be the Delete button
7/22/2019 CDSA Developers Guide.pdf
28/74
Microsoft
Page 24
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
2. This control is a customised
version of the built-in Single
Concept List control. Therefore,
configure the Section Class
Propertiesfields to match thoseof the Single Concept List control.
The simplest way to do this is to:
1. Position the cursor on an
empty line
2. Select Single Concept Li st
from the Section Galleryto
insert it
3. OpenDeveloper Properties
and use it to move between
the configurations
4. Copy the individual Single
Concept Li stsettings andpaste them into the
Configurationtab for your
control
5. Use theDelete Secti ontool to
remove the Single Concept
List section when you have
finished
The settings are as shown in the
screenshot.
Initialising, Customising and Testing the Control
1. In the CDSA Developer ribbon,click Refresh All Sections.
This initialises the control using
the assembly information you
entered in the previous step.
7/22/2019 CDSA Developers Guide.pdf
29/74
Microsoft
Page 25
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
2. Examine and if necessary modify
the custom properties inherited
from Single Concept List Control:
1. In the CDSA Developer
ribbon, click DeveloperProperties
2. Select DiagnosisListfrom the
left pane
3. Click the Configurationtab
For example, to modify the
watermark prompt displayed in the
additional text field, edit the
Add it ionalTextWatermark field.
When done, exit the Clinical
Documentation Developer
Window.
3. To test that the control works:
1. Click theAdd Diagnos is
button
The WPF search control
displays above the button
2. In the Search for a conceptbox, enter Chest pain and
click
3. Select the term you want from
the list and click Save
4. Repeat steps 1, 2 and 3 but
search for hypertension.
4. As defined in your format:
The lines display with rows
shaded every second row
EditandDeletebuttons
enable you to modify the
content
Table 7: Customising the Layout of an Existing Control
7/22/2019 CDSA Developers Guide.pdf
30/74
Microsoft
Page 26
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
6 CREATING A WPF-BASED CONTROL
6.1 Introduction
CDSA provides support for two types of control for use in your clinical document templates:
Simple controls (constructed using the built-in Office Word content controls)
Complex, rich-editing controls (constructed using custom-built WPF controls)
Section4 described how to construct a simple control using the Office Word content controls. This
section provides a worked example of how to build a complex CDSA control based upon an
existing CDSA WPF control.
Important
The example shows how to include an existing WPF control into the CDSA control gallery. It does notcover how to create a WPF-based control from first principles. To learn more about creating
WPF-based controls, consult the relevant articles on the Microsoft Developer Network (MSDN) Web
site. In addition, you can find WPF controls in the MSCUI Controls Toolkit7
For further guidance, look at the code for some of the CDSA controls. For example, after inserting aWPF control into a document, CDSA controls also listen for a number of events raised by Office Word
(such as BeforeSave, BeforePrint and SelectionChanged)in order to remove the WPF control from
the document if necessary. It is good practice to follow a similar pattern for all controls based on WPF
or on other .NET Framework controls.
.
In the example, you will see how to construct a new CDSA control starting from a WPF-based
person-lookup control. That control allows the user to enter some characters and use them to
initiate a search against a list of people (such as the names of clinical staff within a hospital stored
in a local database).
7Available fromwww.mscui.net
http://www.mscui.net/http://www.mscui.net/http://www.mscui.net/http://www.mscui.net/7/22/2019 CDSA Developers Guide.pdf
31/74
Microsoft
Page 27
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Figure 3 shows how such a control might work:
Figure 3: How the WPF-Based Control Might Work
Figure 3 shows the controls sequence of operation:
1. The section in the document shows that no one has yet been selected. It contains a
Changebutton
2. Clicking the Changebutton causes the WPF control to appear above the section
3. Entering a name and clicking the Searchbutton presents a list of search results, where a
result can be selected
4. Clicking the Savebutton removes the WPF control and displays the selected persons
details in the document
To create this control, you need to take these steps:
Add a new section control to the CDSA Visual Studio solution
Create an Office Word building block for the Control
Test the new control in a CDSA document
To guide you in creating your control, the remainder of this section provides more details and
examples to illustrate each of those steps.
7/22/2019 CDSA Developers Guide.pdf
32/74
Microsoft
Page 28
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
6.2 Creating the WPF-Based Control
Table 5 shows the steps required to create a WPF-based control:
Step Descript ion Screenshot
Adding a New Section Control to the Visual Stud io Solut ion1. In Visual Studio, open the CDSA
Solution:
1. Expand the
Microsoft.Consulting.OfficeT
ools.Controlsproject
2. In this example, a custom
WPF control has already been
added to the project, called
PersonEntry and the default
style and templates are
already present in the
Generic.xaml file
2. Create a new section control to
place the Person Entrycontrol in
the document and handle the
SaveandCancelevents.
To do this, first create a new class
calledPersonField
3. ThePersonFieldclass inherits
basic behaviour definitions from
the providedSectionBase
control.
Note
For security reasons, all
sections must derive from
SectionBase to prevent
execution of code not related
to the CDSA solution
namespace Mi crosof t . Consul t i ng. Of f i ceTool s. Cont r ol s{
publ i c cl ass Per sonFi el d : Sect i onBase{}
}
7/22/2019 CDSA Developers Guide.pdf
33/74
Microsoft
Page 29
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
4. Specify the private fields within
the class. These fields are:
Wrapper of type
Microsoft.Office.Tools.Word.
OLEControl
PersonEntry of type
PersonEntry
Host of type ElementHost
/ / / / / / St or es t he cont r ol wr apper ./ / / pr i vat e Mi crosof t . Of f i ce. Tool s. Wor d. OLEContr ol wr apper;
/ / / / / / The person ent r y cont r ol ./ / / pri vat e Per sonEntr y per sonEnt r y;
/ / / / / / The WPF el ement host ./ / /
pr i vat e El ementHost host ;
5. Override the initialisation method
to allow addition of a custom
configuration value for the
watermark in the search field.
publ i c over r i de voi d I ni t i al i ze(Mi crosof t . Of f i ce. I nt er op. Wor d. Cont ent Cont r ol
cont ent Cont r ol ){
base. I ni t i al i ze( contentContr ol ) ;i f ( st r i ng. I sNul l Or Empt y(
thi s. Get Conf i gur at i onVal ue( "Wat er mar k" ) ) ){
thi s. AddConf i gur at i onI t em("Wat er mar k" ,"Ent er a search f or a person") ;
}
}
6. Override theEditSection method.
CDSA calls EditSection when the
user clicks a sections Editbutton.
The button is inserted from theSectionBaseclass
pr ot ect ed over r i de voi d Edi t Secti on( ){
base. Edi tSect i on() ;t hi s. I nsert Act i onContr ol () ;
}
7/22/2019 CDSA Developers Guide.pdf
34/74
Microsoft
Page 30
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
7. Before inserting the WPF control,
check if the WPF control is not
already in the document and also
check that an action control
insertion point was found withinthe section.
If both checks are OK, go ahead
and insert the WPF control into
the ActionControlInsertionPoint:
1. If necessary, create an
instance of thepersonEntry
control. Add handlers to the
Saveand Canceledevents
2. Update theWatermark
property to use the value
specified in the custom
configuration3. Host the WPF control in a
WinForms control (Office Word
does not support WPF content
directly in a document)
4. Create an instance of an
ElementHost and set the
background colour to white
5. Set the LockContents
property to falseto enable
insertion of the control.
6. Insert the ElementHost into the
document. ThepersonEntrycontrol methods set the size at
insertion. The method returns
the wrapper that Office Word
uses to host the control. Store
this locally to allow deletion of
the wrapper when the control
is removed from the
document.
7.Add the person entry control
as a child
8. Lock the action control
insertion point.
The control is now in the
document.
pr i vat e voi d I nser t Acti onCont r ol ( ){
i f ( t hi s. wr apper == nul l &&thi s. Acti onCont r ol I nsert i onPoi nt ! = nul l )
{i f ( t hi s. per sonEnt r y == nul l ){
thi s. per sonEnt r y = new Per sonEnt r y( ) ;thi s. per sonEnt r y. Saved +=
new EventHandl er ( per sonEnt r y_Saved) ;thi s. per sonEnt r y. Cancel ed +=
newEventHandl er ( per sonEnt r y_Cancel ed) ;
}
thi s. per sonEnt r y. Wat ermark =thi s. Get Conf i gur at i onVal ue("Wat ermar k" ) ;
t hi s. host = new El ementHost ( ) ;t hi s. host . BackCol or =
Syst em. Dr awi ng. Col or . Whi t e;thi s. Act i onCont r ol I nser t i onPoi nt . LockCont ent s
= fal se;thi s. wr apper =
Mi crosof t . Of f i ce. Tool s. Wor d. Extensi ons. Document Ext ensi ons. Get Vst oObj ect (
thi s. Act i onCont r ol I nsert i onPoi nt . Range. Document ) . Contr ol s. AddCont r ol (
thi s. host ,thi s. Acti onCont r ol I nser t i onPoi nt . Range,
thi s. per sonEnt r y. Desi r edWi dt h,thi s. per sonEnt r y. Desi r edHei ght ,st r i ng. For mat(
System. Gl obal i zat i on. Cul t ureI nf o. Cur r ent Cul t ur e,"{0}_Per sonEnt r y_{1}",
t hi s. Sect i onI d,
Sect i onLi st Xml Hel per . Get Uni queI denti f i er () )) ;t hi s. host. Chi l d = thi s. per sonEnt r y;thi s. Act i onCont r ol I nser t i onPoi nt . LockCont ent s
= true;}
}
7/22/2019 CDSA Developers Guide.pdf
35/74
Microsoft
Page 31
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
8. Add a method called
RemoveActionControlthat:
1. Deletes the wrapper control
from the document
2. Unlocks the action control
insertion point
3. Sets the range text to empty to
clear out the content control
4. Locks the action control
insertion point again and sets
focus back to the Editbutton
pr i vat e voi d RemoveAct i onCont r ol ( ){
i f ( t hi s. wr apper ! = nul l ){
thi s. wr apper . Del et e( ) ;
t hi s. wr apper = nul l ;}
i f ( t hi s. host ! = nul l ){
thi s. host. Chi l d = nul l ;}
thi s. Act i onCont r ol I nser t i onPoi nt . LockCont ent s =f al se;
thi s. Act i onCont r ol I nser t i onPoi nt . Range. Text =st r i ng. Empty;
thi s. Act i onCont r ol I nser t i onPoi nt . LockCont ent s =true;
}
9. Create an event handler
personEntry_Canceled (if it does
not already exist) and call
RemoveActionControlto remove
the WPF control from the
document without updating the
values
voi d per sonEnt r y_Cancel ed( obj ect sender, EventAr gs e){
thi s. RemoveAct i onCont r ol ( ) ;
}
7/22/2019 CDSA Developers Guide.pdf
36/74
Microsoft
Page 32
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
10. Create an event handler
personEntry_Saved (if it does
not already exist). Add a call to
RemoveActionControlto remove
the WPF control from thedocument, first saving the
information in the control back to
the native data XML:
1. Create a field for the custom
XML part storing the document
data
2. Call AddElementNode for each
part of the name, passing in
the:
Custom XML part
Element name
Section Id
Empty section line ID (as
this is not a list item)
Value ( if no person was
selected, pass in an empty
string)
3. Repeat for GivenName and
Title
The values in the document
update automatically because the
plain text content controls in the
document are already bound to
those elements in the native dataXML.
voi d per sonEnt r y_Saved(obj ect sender , EventAr gs e){
Of f i ce. Cor e. Cust omXMLPar t xml =
El ement Li st Xml Hel per . Get El ement Li st Par t ( t hi s. Secti onC
ont ent Cont r ol . Range. Document ) ;El ement Li st Xml Hel per . AddEl ement Node(
xml ,"Fami l yName",thi s. Sect i onI d,st r i ng. Empty,thi s. per sonEnt r y. Sel ect edPer son ! = nul l ?
thi s. per sonEnt r y. Sel ect edPer son. Fami l yName :s t r i ng. Empt y) ;
El ement Li st Xml Hel per . AddEl ement Node(xml ,"Gi venName" ,
thi s. Sect i onI d,st r i ng. Empty,thi s. per sonEnt r y. Sel ect edPer son ! = nul l ?
thi s. per sonEnt r y. Sel ectedPer son. Gi venName: st r i ng. Empt y);
El ement Li st Xml Hel per . AddEl ement Node(xml ," Ti t l e",t hi s. Sect i onI d,st r i ng. Empty,thi s. per sonEnt r y. Sel ect edPer son ! = nul l ?thi s. per sonEnt r y. Sel ectedPer son. Ti t l e :
s t r i ng. Empt y) ;
t hi s. RemoveAct i onCont r ol ( ) ;}
Creating an Office Word Building B lock for the Control
1. To create a reusable Office Word
building block, open the
CDSABuildingBlocks.dotx
template file found in the
WordAddinproject
7/22/2019 CDSA Developers Guide.pdf
37/74
Microsoft
Page 33
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
2. CDSABuildingBlocks.dotx
contains all of the building blocks
for each of the controls.
Each control layout is on a
separate page in the document.To change a layout, edit it in these
pages and then update the
building blocks collection held
within the template.
3. At the end of the document:
1.Add a new page for the new
control
2.Add the control title: Person
Field3. Click the CDSA Developertab
(if it is not on view, access it
through the CDSA Usertab as
described in section2.7).
The next steps in creating the
building block use options on the
CDSA Developerribbon and the
Office Word Developerribbon.
Sections3and4describe the use
of both sets of options.
4. Insert a Section Partfrom the
Custom Parts Gallery.
5. Add some paragraphs to create
some space and insert anAct ion
Control Insertion Partfrom the
Custom Parts Gallery
6. Add a table with these features:
Three rows and two columns
Table width = AutoFit Contents
Labels in the left column
7/22/2019 CDSA Developers Guide.pdf
38/74
Microsoft
Page 34
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
7. Open the Office WordDeveloper
ribbon and in each cell of the
second column:
1. Insert a Plain Text Content
Control
2. Select Properties from the
Developerribbon
3. Enter the title for the content
control and check the
Contents cannot be edited
box
8. Click Design Modeand enter
watermark prompt text in each
content control.
When done, click Design Mode
to exit and open the CDSA
Developerribbon again
9. Add an edit button insertion point
by following these steps:
1. Position the cursor below the
table
2. Right-align the paragraph
3. Select Section Edit Button
Insertion Partfrom the
Custom Parts Gallery
7/22/2019 CDSA Developers Guide.pdf
39/74
Microsoft
Page 35
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
10. Click the Developer Properties
button to see your new control
listed.
Next you need to:
Set some default properties on
the control
Point the control at the
PersonField class created at
the beginning
11. Select the control name on the
Developer Propertiesscreen and
set the following values:
Section Id= Person Field
Section Edit Button Label =
Change
Section Control Assembly=
Microsoft.Consulting.OfficeToo
ls.Controls
Section Control Class=Microsoft.Consulting.OfficeToo
ls.Controls.PersonField.
Close the Developer Properties
screen.
7/22/2019 CDSA Developers Guide.pdf
40/74
Microsoft
Page 36
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
12. Ensure that the section
configuration gets used with this
building block by following these
steps:
1. Click on the section to select it
2. In the Office Word Developer
ribbon, click Properties
3. Enter a name in the Titlefield
that is the same as the Section
Id set in step11(Person
Field)
4. Click OK
13. Save the building block by
following these steps:
1. Open the Insertribbon
2. Click Quick Parts
3. Select Save selection to
Quick Part Gallery
7/22/2019 CDSA Developers Guide.pdf
41/74
Microsoft
Page 37
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
14. Complete the Create New
Building Blockfields as follows:
Name A unique and
meaningful name (in this case,
Person Field)
Gallery For consistency, add
CDSA building blocks to the
Custom 1gallery
Category As this is a new
section control, select Section
Save in Select
CDSABuildingBlocks.dotx
Note
Often, Save inlists two
CDSABuildingBlocks.dotx
items. Select the top onehere. The second is
overwritten every time the
project is built.
15. Save the CDSA building blocks
template and your new control is
ready to use. If you run the
project, you can test the control in
a document.
Testing the New Control in a CDSA Document
1. To test your new control, follow
these steps:
1. Open a new document in
Office Word
2. Open the CDSA Developer
ribbon
3. Click Convert to Clinical
Document
4. Click Section Gallery. You
can see that Person Fieldis
now an option
5. Select Person Fieldto insert it
into the document.
7/22/2019 CDSA Developers Guide.pdf
42/74
Microsoft
Page 38
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
2. The display shows the Person
Field layout, including the Change
button
3. Clicking Changecauses the WPF
control to appear and you can
search for a person
4. Having found a match, click Save
to select the person
5. CDSA inserts the persons details
into the document
Clicking Changedisplays the
WPF control again to allow
another search and clicking Save
again updates the selection
Table 8: Creating a WPF-Based Control
7/22/2019 CDSA Developers Guide.pdf
43/74
Microsoft
Page 39
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
7 CREATING A WPF-BASED LIST CONTROL
7.1 Introduction
Section6 covered how to create a simple WPF-based section control. This section covers the
creation of a basic list control to input values using the same WPF control (a person-lookup
control).
Important
As in Section6,the example shows how to include an existing WPF control into the CDSA controlgallery. It does not cover how to create a WPF-based control from first principles. To learn more about
creating WPF-based controls, consult the relevant articles on the Microsoft Developer Network
(MSDN) Web site. In addition, you can find WPF controls in the MSCUI Controls Toolkit8
For further guidance, look at the code for some of the CDSA controls. For example, after inserting aWPF control into a document, CDSA controls also listen for a number of events raised by Office Word
(such as BeforeSave, BeforePrint and SelectionChanged)in order to remove the WPF control from
the document if necessary. It is good practice to follow a similar pattern for all controls based on WPF
or on other .NET Framework controls.
.
Figure 4 shows how such a control might work:
Figure 4: How the WPF-Based List Control Might Work
8Available fromwww.mscui.net
http://www.mscui.net/http://www.mscui.net/http://www.mscui.net/http://www.mscui.net/7/22/2019 CDSA Developers Guide.pdf
44/74
Microsoft
Page 40
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Figure 4 shows the controls sequence of operation:
1. The section in the document shows that no one has yet been selected. It contains anAdd
Personbutton
2. Clicking theAdd Person button causes the WPF control to appear in the section
3. Entering a name and clicking the Searchbutton presents a list of search results, where aresult can be selected
4. Clicking the Savebutton removes the WPF control and adds the selected persons details
to a new table row in the document. CDSA appends a Deletebutton to allow the row to be
removed later
To create this control, you need to take these steps:
Add a new section control in the CDSA Visual Studio solution
Create an Office Word building block for the control
Create another building block to represent a row within the table
Test the new control in a CDSA document
7.2 Creating the WPF-Based List Control
Table 5 shows the steps required to create a WPF-based list control:
Step Descript ion Screenshot
Adding a New Section Control to the Visual Stud io Solut ion
1. In Visual Studio, open the CDSA
Solution, and expand the
Microsoft.Consulting.OfficeTool
s.Controlsproject.In the example, the custom WPF
control namedPersonEntryhas
already been added to the
solution and is present in the WPF
folder.
The default style and templates
are already present in the
Generic.xaml file located in the
Themes folder
7/22/2019 CDSA Developers Guide.pdf
45/74
Microsoft
Page 41
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
2. Create a new class called
PersonList for the new section
control in theSectionControls
folder
3. Make thePersonListclass inherit
the providedSectionListBase
class.
TheSectionListBaseclass
inherits SectionBaseand adds
virtual methods that are useful
when working with list controls.
These include methods for
populating the lines collection as
the control loads and for adding,
editing or deleting a line in thetable.
Note
For security reasons, all
sections must derive from
SectionBase to prevent
execution of code not related
to the CDSA solution
namespace Mi crosof t . Consul t i ng. Of f i ceTool s. Cont rol s{
cl ass Per sonLi st : Sect i onLi st Base{}
}
4. Add the following private fields to
the class:
Wrapper of type
Microsoft.Office.Tools.Word.OLEControl
PersonEntry of type
PersonEntry
Host of typeElementHost
/ / / / / / St ores t he cont r ol wr apper./ / / pri vate Mi crosof t . Of f i ce. Tool s. Word. OLECont r ol wr apper ;
/ / / / / / The person ent r y cont r ol ./ / / pri vate Per sonEnt r y personEnt r y;
/ / / / / / The WPF el ement host ./ / /
pri vate El ement Host host ;
7/22/2019 CDSA Developers Guide.pdf
46/74
Microsoft
Page 42
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
5. Create an override for the
Initializemethod by adding the
code shown opposite. This adds a
custom configuration value for the
watermark in the search field
publ i c overr i de voi d I ni t i al i ze(Mi crosof t . Of f i ce. I nt er op. Word. Cont ent Cont r ol cont ent Cont r ol ){
base. I ni t i al i ze(contentCont r ol ) ;i f ( s t r i ng. I sNul l Or Empt y(
t hi s. GetConf i gur ati onVal ue("Wat er mar k" ) ) ){
t hi s. AddConf i gur ati onI t em("Wat er mar k" ,"Ent er a search f or a per son" ) ;
}
}
6. Before inserting the WPF control,
check if the WPF control is not
already in the document and also
check that an action control
insertion point was found within
the section.
If both checks are OK, go ahead
and insert the WPF control into
the ActionControlInsertionPoint:
1. If necessary, create an
instance of thepersonEntry
control. Add handlers to the
Saveand Canceledevents
2. Update the Watermark
property to use the value
specified in the custom
configuration
3. Host the WPF control in a
WinForms control (Office Word
does not support WPF contentdirectly in a document)
4. Create an instance of an
ElementHost and set the
background colour to white
5. Set the LockContents
property to falseto enable
insertion of the control.
6. Insert the ElementHost into the
document. The personEntry
control methods set the size at
insertion. The method returns
the wrapper that Office Worduses to host the control. Store
this locally to allow deletion of
the wrapper when the control
is removed from the
document.
7.Add the personEntry control as
a child
8. Lock the action control
insertion point
pr i vate voi d I nsert Acti onCont r ol ( ){
i f ( t hi s. wr apper == nul l &&t hi s. Acti onCont r ol I nsert i onPoi nt ! = nul l )
{i f ( t hi s. per sonEnt r y == nul l ){
t hi s. per sonEnt r y = new Per sonEnt r y( ) ;t hi s. per sonEnt r y. Saved +=
new Event Handl er ( personEntr y_Saved) ;t hi s. per sonEnt r y. Cancel ed +=
new Event Handl er ( personEntr y_Cancel ed) ;}
t hi s. per sonEnt r y. Wat ermark =t hi s. GetConf i gurat i onVal ue("Wat er mar k" ) ;
t hi s. host = new El ement Host ( ) ;t hi s. host . BackCol or = Syst em. Dr awi ng. Col or . Whi t e;
t hi s. Act i onCont r ol I nsert i onPoi nt . LockCont ent s =f a l s e;t hi s. wr apper =
Mi crosof t . Of f i ce. Tool s. Word. Extensi ons. DocumentExtensi ons. Get Vst oObj ect (
t hi s. Act i onCont r ol I nsert i onPoi nt . Range. Document ) . Cont r ol s. AddCont r ol (
t hi s. host ,t hi s. Acti onCont rol I nsert i onPoi nt . Range,t hi s. personEntr y. Desi r edWi dth,t hi s. personEnt r y. Desi r edHei ght ,s t r i ng. For mat(
Syst em. Gl obal i zati on. Cul t ureI nf o. Cur rent Cul t ure,"{0}_PersonEnt r y_{1}" , t hi s. Sect i onI d,
Secti onLi st Xml Hel per. Get Uni queI dent i f i er( ) ) ) ;t hi s. host . Chi l d = t hi s. personEnt r y;t hi s. Act i onCont r ol I nsert i onPoi nt . LockCont ent s =
true;}
}
7/22/2019 CDSA Developers Guide.pdf
47/74
Microsoft
Page 43
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
7. Create a new method called
RemoveActionControl.
This method:
1. Deletes the wrapper control
from the document
2. Unlocks the action control
insertion point
3. Sets the range text to empty to
clear out the content control
4. Locks the action control
insertion point again
pr i vate voi d RemoveAct i onCont r ol ( ){
i f ( t hi s. wr apper ! = nul l ){
t hi s. wrapper. Del et e( ) ;
t hi s. wr apper = nul l ;}
i f ( t hi s. host ! = nul l ){
t hi s. host . Chi l d = nul l ;}
t hi s. Act i onCont r ol I nsert i onPoi nt . LockCont ent s = f al s e;t hi s. Act i onCont r ol I nsert i onPoi nt . Range. Text =
st r i ng. Empty;t hi s. Act i onCont r ol I nsert i onPoi nt . LockCont ent s = true;
}
8. Create an override for the
HandleAddButtonClickmethod
that gets called when theAdd button is clicked. Add a call to
InsertActionControlto add the
WPF control into the document
pr ot ect ed overr i de voi d Handl eAddButt onCl i ck( ){
base. Handl eAddBut t onCl i ck() ;t hi s. I nsert Act i onCont rol ( ) ;
}
9. Create an event handler
personEntry_Canceled (if it does
not already exist) and call
RemoveActionControlto remove
the WPF control from the
document without creating a line
voi d per sonEnt r y_Cancel ed( obj ect sender, Event Ar gs e){
t hi s. RemoveAct i onCont r ol ( ) ;
}
10. Create an event handler
personEntry_Saved (if it does
not already exist) and add a call tothe CreateSectionLinemethod to
create a new SectionLine in the
table:
Specify sectionLineId as null
so that CDSA will create a
randomly generated line id
Specify
SectionLineBuildingBlockNa
me as this is the name of the
building block that represents
a line for the table
Thedefault implementation ofCreateSectionLinemethod found
in the SectionListBaseclass
checks that the table for insertion
exists, adds a row at the bottom of
the table and inserts the line
building block into the row
voi d per sonEnt r y_Saved(obj ect sender, Event Ar gs e){
Sect i onLi neBase sect i onLi ne =t hi s. Cr eat eSect i onLi ne(nul l ,t hi s. Secti onLi neBui l di ngBl ockName);
}
7/22/2019 CDSA Developers Guide.pdf
48/74
Microsoft
Page 44
Clinical Documentation Solution Accelerator Developer's Guide
Prepared by Microsoft, Version 1.0.0.0
Last modified on 15 April 2010
Step Descript ion Screenshot
11. Include these additions in the
personEntry_Saved event
handler:
1.Add code to add the line data
to the native data XML
2.Add a call toCreateBindings
for the sectionLineinstance
This finds all plain text content
controls in the line and binds
them to the native data XML
using the section ID, the
section line ID and the content
control title.
3.Add a call toInsertControls
for the sectionLineinstance
to add an edit and delete
button for the line, if required4.Add the sectionLineinstance
to the controls SectionLines
collection
5. CallRemoveActionControlto
remove the WPF control from
the document
voi d per sonEnt r y_Saved(obj ect sender, Event Ar gs e){
Sect i onLi neBase sect i onLi ne =t hi s. Cr eat eSect i onLi ne(nul l ,t hi s. Secti onLi neBui l di ngBl ockName);
i f ( sect i onLi ne != nul l ){
Of f i ce. Core. Cust omXMLPar t xml =El ement Li